mirror of
https://github.com/Hamlib/Hamlib.git
synced 2024-09-21 10:27:18 +00:00
More minor editing. Hopefully clarified a few issues.
git-svn-id: https://hamlib.svn.sourceforge.net/svnroot/hamlib/trunk@2277 7ae35d74-ebe9-4afe-98af-79ac388436b8
This commit is contained in:
parent
109af84b52
commit
b832b4bf10
317
README.developer
317
README.developer
@ -49,56 +49,72 @@ I expect that IP, USB, and other connectivity will follow afterwards.
|
||||
General Guidelines.
|
||||
-------------------
|
||||
|
||||
0. The top level directory looks like this (Note, it has grown considerably).
|
||||
0. The top level directory looks like this as of 06 Jan 2008
|
||||
(Note, it has grown considerably).
|
||||
|
||||
[fillods@charybde hamlib]$ tree -d
|
||||
~/test/hamlib $ tree -d -I CVS
|
||||
.
|
||||
|-- alinco
|
||||
|-- aor
|
||||
|-- bindings
|
||||
|-- c++
|
||||
|-- debian
|
||||
|-- doc
|
||||
| |-- html
|
||||
| |-- man
|
||||
| `-- sgml
|
||||
|-- drake
|
||||
|-- dummy
|
||||
|-- easycomm
|
||||
|-- flexradio
|
||||
|-- fodtrack
|
||||
|-- gnuradio
|
||||
|-- icom
|
||||
| |-- lib
|
||||
| `-- test
|
||||
|-- include
|
||||
| `-- hamlib
|
||||
|-- jrc
|
||||
|-- kachina
|
||||
|-- kenwood
|
||||
|-- kit
|
||||
|-- kylix
|
||||
| `-- tests
|
||||
|-- lib
|
||||
|-- libltdl
|
||||
|-- lowe
|
||||
|-- macros
|
||||
|-- microtune
|
||||
|-- pcr
|
||||
|-- perl
|
||||
|-- racal
|
||||
|-- rft
|
||||
|-- rotorez
|
||||
|-- rpcrig
|
||||
|-- rpcrot
|
||||
|-- sartek
|
||||
|-- skanti
|
||||
|-- src
|
||||
|-- tapr
|
||||
|-- tentec
|
||||
|-- tests
|
||||
| `-- html
|
||||
| |-- config
|
||||
| |-- rigctl.test
|
||||
| |-- testbcd.test
|
||||
| |-- testfreq.test
|
||||
| `-- testloc.test
|
||||
|-- tuner
|
||||
|-- uniden
|
||||
|-- winradio
|
||||
| `-- linradio
|
||||
|-- wj
|
||||
`-- yaesu
|
||||
|
||||
51 directories
|
||||
|
||||
|
||||
1. Building
|
||||
|
||||
If you just want to recompile the library, please refer
|
||||
to the INSTALL file. This document introduces hacking the code of Hamlib.
|
||||
|
||||
|
||||
1.1 Obtaining sources: anonymous (pserver) cvs checkout
|
||||
|
||||
cvs -d:pserver:anonymous@hamlib.cvs.sourceforge.net:/cvsroot/hamlib login
|
||||
@ -117,6 +133,7 @@ feel free to experiment) deletes empty directories (yes some do exist :-) )
|
||||
and adds any new directories added to the repository since your last
|
||||
checkout.
|
||||
|
||||
|
||||
1.1.1 Obtaining more info on CVS
|
||||
|
||||
Check out the sourceforge page at https://sourceforge.net/cvs/?group_id=8305
|
||||
@ -124,6 +141,7 @@ for more information about how to use the CVS repository of Hamlib.
|
||||
|
||||
A CVS manual is online at http://ximbiot.com/cvs/manual/
|
||||
|
||||
|
||||
1.2. Requirements
|
||||
|
||||
Hamlib is entirely developed using GNU tools, under various Linux systems.
|
||||
@ -134,27 +152,27 @@ That is, if you want to take part in the development of Hamlib,
|
||||
you'll need the following tools. Make sure you have at least the required
|
||||
version or you won't even be able to build from the cvs checkout.
|
||||
|
||||
* Gnu C or any C99 compliant compiler # gcc --version
|
||||
* Gnu make (or any modern one, BSD okay) # make --version
|
||||
* autoconf 2.54 # autoconf --version
|
||||
* automake 1.7 # automake --version
|
||||
* libtool 1.5 # libtool --version
|
||||
* Gnu C or any C99 compliant compiler # gcc --version
|
||||
* Gnu make (or any modern one, BSD okay) # make --version
|
||||
* autoconf 2.54 # autoconf --version
|
||||
* automake 1.7 # automake --version
|
||||
* libtool 1.5 # libtool --version
|
||||
* cvs and ssh for connection to cvs.sourceforge.net
|
||||
|
||||
Optional:
|
||||
* GNU C++ # g++ --version
|
||||
* swig (for bindings) 1.3.14 # swig -version
|
||||
* perl devel # h2xs
|
||||
* GNU C++ # g++ --version
|
||||
* swig (for bindings) 1.3.14 # swig -version
|
||||
* perl devel # h2xs
|
||||
* tcl devel
|
||||
* python devel
|
||||
* libxml2 devel # xml2-config --version
|
||||
* libxml2 devel # xml2-config --version
|
||||
* libgd devel
|
||||
* libusb devel
|
||||
* RPC devel (libc-dev) # rpcgen --version
|
||||
* RPC devel (libc-dev) # rpcgen --version
|
||||
|
||||
Documentation:
|
||||
* doxygen
|
||||
* DocBook
|
||||
* doxygen
|
||||
* DocBook
|
||||
|
||||
Note: Some systems can have several versions of the autotools installed.
|
||||
In that case, autoconf may be called "autoconf2.50", autoheader
|
||||
@ -178,27 +196,27 @@ AUTOHEADER, AUTOHEADER, and ACLOCAL variables with the required versions
|
||||
seen in the previous section (most systems will be fine with the default
|
||||
names).
|
||||
|
||||
sh ./autogen.sh --disable-static --prefix=/usr/local CFLAGS="-g -O0"
|
||||
make
|
||||
make install
|
||||
sh ./autogen.sh --disable-static --prefix=/usr/local CFLAGS="-g -O0"
|
||||
make
|
||||
make install
|
||||
|
||||
If you don't want the build files cluttering the source directories, do the
|
||||
following in the same parent directory of hamlib:
|
||||
|
||||
mkdir build && cd build
|
||||
sh ../hamlib/autogen.sh --disable-static --prefix=/usr/local CFLAGS="-g -O0"
|
||||
make
|
||||
make install
|
||||
mkdir build && cd build
|
||||
sh ../hamlib/autogen.sh --disable-static --prefix=/usr/local CFLAGS="-g -O0"
|
||||
make
|
||||
make install
|
||||
|
||||
This will keep the binary output files seperate from the source tree and aid
|
||||
in development.
|
||||
in development by reducing clutter in the source tree.
|
||||
|
||||
Once you've run autogen.sh, make sure you've got some recent config.guess and
|
||||
config.sub (needed to guess your system type). Anything of at least year 2004
|
||||
should be fine, unless you run some exotic hardware/software system:
|
||||
|
||||
./config.guess --version
|
||||
./config.sub --version
|
||||
./config.guess --version
|
||||
./config.sub --version
|
||||
|
||||
The prefix argument is optional. Convention is that local packages be placed
|
||||
in /usr/local away from distribution installed packages. The --disable-static
|
||||
@ -217,7 +235,7 @@ when make is executed.
|
||||
|
||||
For a Tcl build, add this if needed:
|
||||
|
||||
--with-tcl=/usr/lib/tcl8.2
|
||||
--with-tcl=/usr/lib/tcl8.2
|
||||
|
||||
Note: C-shell users may have to run autogen.sh and make through a bourne shell
|
||||
instead, or pass "SHELL=bash" as a parameter to make.
|
||||
@ -235,73 +253,81 @@ Patches are welcome too! Just send them to the mailing list.
|
||||
So far, Hamlib has been tested successfully under the following systems:
|
||||
(if your system is not present, please report to the mailing list)
|
||||
|
||||
* Debian i386
|
||||
* Debian sid mipsel
|
||||
* RedHat i386
|
||||
* Linux ppc
|
||||
* Slackware i386
|
||||
* FreeBSD & NetBSD
|
||||
* Solaris 2.6
|
||||
* Mac OS X
|
||||
* win32: Cygwin, Mingw
|
||||
* Debian i386
|
||||
* Debian sid mipsel
|
||||
* RedHat i386
|
||||
* Linux ppc
|
||||
* Slackware i386
|
||||
* FreeBSD & NetBSD
|
||||
* Solaris 2.6
|
||||
* Mac OS X
|
||||
* win32: Cygwin, Mingw
|
||||
|
||||
|
||||
2. How to add a new backend
|
||||
|
||||
The rule is one backend per protocol family.
|
||||
Try to share code between rigs of the same family, if applicable.
|
||||
The rule is one backend per protocol family.
|
||||
Try to share code between rigs of the same family, if applicable.
|
||||
|
||||
2.1. mkdir mybackend
|
||||
Create a new subdir, of the name of the protocol backend.
|
||||
NB: the directory MUST be the same as the backend name.
|
||||
2.1. mkdir mybackend
|
||||
Create a new subdir, of the name of the protocol backend.
|
||||
NB: the directory MUST be the same as the backend name.
|
||||
|
||||
2.2. Add <mybackend> to the SUBDIRS variable in the topdir Makefile.am,
|
||||
2.3. Add the backend name to the BACKEND_LIST variable in configure.ac
|
||||
2.4. Add "mybackend/Makefile" in the AC_CONFIG_FILES macro at the bottom
|
||||
of configure.ac
|
||||
2.2. Add <mybackend> to the SUBDIRS variable in the topdir Makefile.am,
|
||||
2.3. Add the backend name to the BACKEND_LIST variable in configure.ac
|
||||
2.4. Add "mybackend/Makefile" in the AC_CONFIG_FILES macro at the bottom
|
||||
of configure.ac
|
||||
|
||||
2.5. Create mybackend/Makefile.am, mybackend.c mybackend.h
|
||||
Use 'dummy' backend as a template.
|
||||
Here are commands for the bourne shell.
|
||||
2.5. Create mybackend/Makefile.am, mybackend.c mybackend.h
|
||||
Use 'dummy' backend as a template.
|
||||
Here are commands for the bourne shell:
|
||||
|
||||
$ automake mybackend/Makefile
|
||||
$ CONFIG_HEADERS= CONFIG_LINKS= \
|
||||
CONFIG_FILES=mybackend/Makefile ./config.status
|
||||
$ automake mybackend/Makefile
|
||||
$ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status
|
||||
|
||||
make in topdir to rebuild all
|
||||
make in topdir to rebuild all
|
||||
|
||||
2.6. Commit your work:
|
||||
$ cvs add mybackend
|
||||
$ cd mybackend
|
||||
$ cvs add Makefile.am mybackend.c mybackend.h
|
||||
$ cvs commit -m "Initial release" Makefile.am mybackend.c mybackend.h
|
||||
2.6. Commit your work (developer access to Hamlib CVS required):
|
||||
$ cvs add mybackend
|
||||
$ cd mybackend
|
||||
$ cvs add Makefile.am mybackend.c mybackend.h
|
||||
$ cvs commit -m "Initial release" Makefile.am mybackend.c mybackend.h
|
||||
|
||||
Note: The `-m' switch passes a short message to the CVS repository
|
||||
upon a commit. If a longer message is desired, do not use the
|
||||
`-m' option. The editor specified in the EDITOR or VISUAL
|
||||
environment variables will be started where a more detailed message
|
||||
may be composed.
|
||||
|
||||
|
||||
3. How to add a new model to and existing backend
|
||||
3.1. make sure there's already a (unique) ID for the model to be added
|
||||
in include/hamlib/riglist.h
|
||||
3.2. locate the existing backend
|
||||
3.3. Clone the most similar model in the backend
|
||||
3.4. Add the new C file to the _SOURCES variable
|
||||
of the backend's Makefile.am
|
||||
3.5. Add "extern const struct rig_caps <mymodel>_caps;" to mybackend.h
|
||||
3.6. In initrigs_<mybackend> of mybackend.c,
|
||||
add "rig_register(&<mymodel>_caps);"
|
||||
|
||||
3.7. Run make if you have dependencies, or the following to regenerate
|
||||
the makefile.
|
||||
$ automake mybackend/Makefile
|
||||
$ CONFIG_HEADERS= CONFIG_LINKS= \
|
||||
CONFIG_FILES=mybackend/Makefile ./config.status
|
||||
3.1. make sure there's already a (unique) ID for the model to be added
|
||||
in include/hamlib/riglist.h
|
||||
|
||||
make in topdir to rebuild all
|
||||
3.2. locate the existing backend
|
||||
3.3. Clone the most similar model in the backend
|
||||
3.4. Add the new C file to the _SOURCES variable
|
||||
of the backend's Makefile.am
|
||||
|
||||
3.8. Commit your work (once tests are satisfactory):
|
||||
$ cd mybackend
|
||||
$ cvs add mymodel.c
|
||||
$ cvs commit -m "added <mymodel> to <mybackend>" \
|
||||
Makefile.am mybackend.c mybackend.h mymodel.c
|
||||
3.5. Add "extern const struct rig_caps <mymodel>_caps;" to mybackend.h
|
||||
3.6. In initrigs_<mybackend> of mybackend.c,
|
||||
add "rig_register(&<mymodel>_caps);"
|
||||
|
||||
3.7. Run `make' if you have dependencies, or the following to regenerate
|
||||
the makefile:
|
||||
$ automake mybackend/Makefile
|
||||
$ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status
|
||||
|
||||
Run `make' in topdir to rebuild all.
|
||||
|
||||
3.8. Commit your work (once tests are satisfactory):
|
||||
$ cd mybackend
|
||||
$ cvs add mymodel.c
|
||||
$ cvs commit -m "added <mymodel> to <mybackend>" Makefile.am mybackend.c mybackend.h mymodel.c
|
||||
|
||||
Note: See Note in section 2.6 above.
|
||||
|
||||
|
||||
4. Read README.betatester to test the new backend/model.
|
||||
Report to mailing list.
|
||||
@ -322,90 +348,95 @@ this. The error checking is removed for simplicity.
|
||||
|
||||
7. Where are the GUI's?
|
||||
|
||||
"Build it and they will come ..."
|
||||
"Build it and they will come ..."
|
||||
|
||||
Seriously, I am hoping the API's will provide a solid framework for some
|
||||
cool GUI development. I would like to see some GTK or Qt apps that use the
|
||||
hamlib API's so they can be used by end users as a nice part of the Ham
|
||||
shack.
|
||||
Seriously, I am hoping the API's will provide a solid framework for some
|
||||
cool GUI development. I would like to see some GTK or Qt apps that use the
|
||||
hamlib API's so they can be used by end users as a nice part of the Ham
|
||||
shack.
|
||||
|
||||
Starting points (not exhaustive):
|
||||
gmfsk, gpredict, grig, klog, kontakt, ktrack, xlog, xtlf
|
||||
|
||||
Starting points (not exhaustive):
|
||||
gmfsk, gpredict, grig, klog, kontakt, ktrack, xlog, xtlf
|
||||
|
||||
8. Contributing code
|
||||
|
||||
8.1 License
|
||||
8.1 License
|
||||
|
||||
Contributed code to the Hamlib frontend must be released under the LGPL.
|
||||
Contributed code to Hamlib backends must follow backend current license.
|
||||
Needless to say, the LGPL is the license of choice.
|
||||
Contributed code to the Hamlib frontend must be released under the LGPL.
|
||||
Contributed code to Hamlib backends must follow backend current license.
|
||||
Needless to say, the LGPL is the license of choice.
|
||||
|
||||
End user applications like rigctl, rotctl and RPC daemons should be released
|
||||
under the GPL, so any contributed code must follow the rule.
|
||||
End user applications like rigctl, rotctl and RPC daemons should be released
|
||||
under the GPL, so any contributed code must follow the rule.
|
||||
|
||||
8.2 Coding guidelines and style
|
||||
8.2 Coding guidelines and style
|
||||
|
||||
Try to keep current style of existing code. Improvements are welcome though.
|
||||
Contributed code should always keep the source base in a compilable
|
||||
state, and not regress unless stated otherwise.
|
||||
Try to keep current style of existing code. Improvements are welcome though.
|
||||
Contributed code should always keep the source base in a compilable
|
||||
state, and not regress unless stated otherwise.
|
||||
|
||||
There's no need to tag the source in a patch with your name in comments
|
||||
behind each modification, we already know the culprit :-)
|
||||
There's no need to tag the source in a patch with your name in comments
|
||||
behind each modification, we already know the culprit :-)
|
||||
|
||||
Patches should take care of portability issues.
|
||||
Keep in mind Hamlib has to run under:
|
||||
* various Linux's
|
||||
* NetBSD, FreeBSD
|
||||
* MacOS X
|
||||
* Windows: MinGW/Cygwin, and VisualC++ support for rig.h
|
||||
Patches should take care of portability issues.
|
||||
Keep in mind Hamlib has to run under:
|
||||
|
||||
Hamlib should also compile with the following common compilers:
|
||||
* gcc-2.9x (most likely deprecated)
|
||||
* gcc-3.0 and gcc-3.2+ (nearly deprecated?)
|
||||
* gcc-4.x and newer
|
||||
* in shared and static
|
||||
* C++ compiler against rig.h, riglist.h, rotator.h
|
||||
* various Linux's
|
||||
* NetBSD, FreeBSD
|
||||
* MacOS X
|
||||
* Windows: MinGW/Cygwin, and VisualC++ support for rig.h
|
||||
|
||||
Portability issues to watch:
|
||||
* little vs. big endian systems (use shifts or adhoc functions)
|
||||
* 64 bit int: avoid them in API
|
||||
* printf/scanf of 64bit int: use PRIll and SCNll
|
||||
* printf/scanf of freq_t: use PRIfreq and SCNfreq
|
||||
Hamlib should also compile with the following common compilers:
|
||||
|
||||
8.3 Submitting patches
|
||||
* gcc-2.9x (most likely deprecated)
|
||||
* gcc-3.0 and gcc-3.2+ (nearly deprecated?)
|
||||
* gcc-4.x and newer
|
||||
* in shared and static
|
||||
* C++ compiler against rig.h, riglist.h, rotator.h
|
||||
|
||||
Patches should be in unified format (diff -u), against CVS head or
|
||||
latest release. This format makes it easily readable.
|
||||
The patches are to be sent to the hamlib-developer
|
||||
mailing list. If the file is too big, you can send it as a compressed
|
||||
attachement.
|
||||
Portability issues to watch:
|
||||
|
||||
* little vs. big endian systems (use shifts or adhoc functions)
|
||||
* 64 bit int: avoid them in API
|
||||
* printf/scanf of 64bit int: use PRIll and SCNll
|
||||
* printf/scanf of freq_t: use PRIfreq and SCNfreq
|
||||
|
||||
8.3 Submitting patches
|
||||
|
||||
Patches should be in unified format (diff -u), against CVS head or
|
||||
latest release. This format makes it easily readable.
|
||||
The patches are to be sent to the hamlib-developer
|
||||
mailing list. If the file is too big, you can send it as a compressed
|
||||
attachement.
|
||||
|
||||
8.3.1 Changelog
|
||||
8.3.1 Changelog
|
||||
|
||||
Caveat: The cvs2cl.pl script is used before each release to generate
|
||||
the Changelog file so any changes made directly to it WILL BE LOST!
|
||||
Simply summarize your changes when the files are committed to CVS or,
|
||||
if providing patches to the mailing list, provide a summary so the
|
||||
uploader can include it in the commit message.
|
||||
Caveat: The cvs2cl.pl script is used before each release to generate
|
||||
the Changelog file so any changes made directly to it WILL BE LOST!
|
||||
Simply summarize your changes when the files are committed to CVS or,
|
||||
if providing patches to the mailing list, provide a summary so the
|
||||
uploader can include it in the commit message.
|
||||
|
||||
8.4 CVS commit access
|
||||
8.4 CVS commit access
|
||||
|
||||
Generally, volunteers can get access to SourceForge Hamlib CVS upon
|
||||
asking one of the project administrators. Sometimes we'll ask you!
|
||||
Generally, volunteers can get access to SourceForge Hamlib CVS upon
|
||||
asking one of the project administrators. Sometimes we'll ask you!
|
||||
|
||||
However, before your start commiting, the project admins would like
|
||||
first to have a look at your "style", just to make sure you have grok
|
||||
the Hamlib approach (c.f. previous section on submitting a patch).
|
||||
Then you'll be able to commit by yourself to the backend you have
|
||||
maintainance of. Please follow the rules hereunder:
|
||||
* Always keep the CVS repository in a compilable state.
|
||||
* Follow the coding guidelines
|
||||
* Touching the frontend (files in src/ and include/hamlib) always
|
||||
requires discussion beforehand on the hamlib-developer list.
|
||||
* Announce on the hamlib-developer list if you're about to do serious
|
||||
maintainance work
|
||||
However, before your start commiting, the project admins would like
|
||||
first to have a look at your "style", just to make sure you have grok
|
||||
the Hamlib approach (c.f. previous section on submitting a patch).
|
||||
Then you'll be able to commit by yourself to the backend you have
|
||||
maintainance of. Please follow the rules hereunder:
|
||||
|
||||
Thanks for contributing and have fun!
|
||||
* Always keep the CVS repository in a compilable state.
|
||||
* Follow the coding guidelines
|
||||
* Touching the frontend (files in src/ and include/hamlib) always
|
||||
requires discussion beforehand on the hamlib-developer list.
|
||||
* Announce on the hamlib-developer list if you're about to do serious
|
||||
maintainance work
|
||||
|
||||
Thanks for contributing and have fun!
|
||||
|
||||
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user