diff --git a/README.developer b/README.developer index 942d4f014..452d8aa7a 100644 --- a/README.developer +++ b/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 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 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 _caps;" to mybackend.h - 3.6. In initrigs_ of mybackend.c, - add "rig_register(&_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 to " \ - Makefile.am mybackend.c mybackend.h mymodel.c + 3.5. Add "extern const struct rig_caps _caps;" to mybackend.h + 3.6. In initrigs_ of mybackend.c, + add "rig_register(&_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 to " 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!