X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=docs%2FREADME.developers;h=dcec2a73a4971d1c19998ee3a23725b9bdca85b7;hp=44000710f6baf22d3d87bf9bc631c82c4b0215d1;hb=f78e7c6e6e616cc4ff2bee8a726365fafef2d8ce;hpb=7379ff1546ba2feaabe8b6463f448ea0bafd69bb diff --git a/docs/README.developers b/docs/README.developers index 4400071..dcec2a7 100644 --- a/docs/README.developers +++ b/docs/README.developers @@ -1,229 +1,99 @@ # # README.developers # -# $Id$ -# - -This file is intended to provide a few tips for anyone doing development on nmh. -Developers who learn things "the hard way" about the nmh codebase (as opposed to -local info best encoded in a comment) are encouraged to share their wisdom here. - -The topics are organized alphabetically. - --------------- -autoconf files --------------- +This file is intended to provide a few tips for anyone doing development +on mmh. Developers who learn things "the hard way" about the mmh codebase +(as opposed to local info best encoded in a comment) are encouraged to +share their wisdom here. -If you wish to change the `configure' script or its related files, you'll need -to first install GNU m4, available from and then -GNU autoconf (). - -Most of the configure-related files are automatically generated. The only files -you should need to manually edit are acconfig.h and configure.in. Don't, for -instance, edit config.h.in. Though it is an input file from the point of view -of the users (and the configure script) it is an output file from the point of -view of the developers (and the autoconf script). - -If you do change acconfig.h or configure.in and want to `cvs commit' them, be -sure to regenerate the output files and commit them as well. The easiest way to -regenerate the files is to simply run `make' -- it'll do the necessary calls of -autoconf and autoheader and will do a `./config.status --recheck', which will -exercise your new configure script. - -When you commit the configure-related files, it's very important to commit them -in the right order. The timestamps on the files in the CVS archive are based on -the current time at the moment they were committed -- the timestamps from the -local files you commit are not copied over. If you commit the files in the -wrong order, you'll cause unnecessary calls of `autoconf' to occur when people -try to `make' their copies of the latest CVS source. These people may be -end-users who don't have any interest in changing the configure-related files -and don't have autoconf installed. They'll be unable to make without playing -around with `touch'. - -The correct procedure to commit the configure-related files is: - - % cvs commit acconfig.h aclocal.m4 configure.in - % autoheader; autoconf; date > stamp-h.in - % cvs commit config.h.in configure stamp-h.in - -The reason for the three-step commit is that configure.in contains the RCS $Id -keyword, so when you commit it, a new version is written locally. Therefore, -the autoconf regeneration should be held off until after the commit, or your -local stamp-h.in will become out-of-sync with the CVS version (granted, not that -big a deal). For the second step, you're doing the same commands as a -`make reset' would do, but using that command would require extra configure runs -to make Makefile be up-to-date. - -If you haven't changed all the files noted above, just commit the ones you have -changed, in the stated order (for instance, configure.in, then configure and -stamp-h.in). +Absolute beginners should start reading docs/README.start-devel. ------------------- directory structure ------------------- -Following is a list of nmh's directories along with a brief description of the -purpose of each one. Meanings are given for the abbreviations, but note that -these meanings are just informed guesses as to what the MH developers were -thinking. +Following is a list of mmh's directories along with a brief description +of the purpose of each one. Meanings are given for the abbreviations, +but note that these meanings are just informed guesses as to what the +MH developers were thinking. ./ - The top-level directory. Contains files like README and INSTALL. + The top-level directory. Contains files like README and INSTALL. config/ - Contains utility files for the `configure' process. Ordinarily nothing in - here needs to be messed with. + Contains utility files for the `configure' process. Ordinarily + nothing in here needs to be messed with, but config/config.c is + very interesting to have a look at. -doc/ +docs/ Contains more specialized documentation, such as this file and the FAQ. etc/ - Contains files, file templates, and scripts to generate files that will be - installed in the ${prefix}/etc directory. Stuff like replcomps. + Contains files, file templates, and scripts to generate files that + will be installed in the ${prefix}/etc directory. Stuff like + replcomps. h/ - Most of nmh's header (.h) files are kept not in the individual source - directories, but in this central location. + Most of mmh's header files are kept in this central location instead + of in the individual source directories. man/ - Contains all the input files that are processed to generate nmh's manual - pages. - -mts/ - "mts" stands for "Message Transfer Service". Source files specific to the - different MTSs go in the subdirectories. - -mts/mmdf/ (deprecated) - "mmdf" stands for "Multichannel Memorandum Distribution Facility". It is an - alternative to sendmail used primarily on SCO UNIX. - -mts/sendmail/ (deprecated: handled by mts.conf) - When nmh is configured --with-mts=sendmail, the files in this directory are - used. - -mts/smtp/ - When nmh is configured to just talk to an SMTP server over TCP/IP, the - source in this directory is compiled. + Contains all the input files that are processed to generate mmh's + manual pages. sbr/ - "sbr" stands for "subroutine(s)". For the most part, each source file in - this directory contains a single function with the same name as the source - file. These functions are of general use and are called from throughout - nmh. + "sbr" stands for "subroutine(s)". For the most part, each source + file in this directory contains a single function with the same + name as the source file. These functions are of general use and + are called from throughout mmh. uip/ - "uip" stands for "User Interface Programs". Most nmh commands have a file - in this directory named .c containing the code for that command - (e.g. repl.c). In some cases there is also an auxiliary file called - sbr.c which contains additional subroutines called from .c - (which would contain not much else besides main()). - -zotnet/ (deprecated) - Files in this hierarchy were either written by or moved here by UCI - (University of California, Irvine) after they took over MH from the Rand - Corporation. "Zot!" is the sound effect made by the anteater in the "B.C." - comic strip when its tongue lashes out at ants. The anteater is UCI's - official mascot. Not sure whether UCInet was once called ZotNet... - -zotnet/bboards/ (deprecated) - UCI added Bulletin Board functionality to MH with the `bbc' command. This - functionality has been removed from nmh but apparently files in this - directory are still needed for other purposes. - -zotnet/mf/ (deprecated, now in sbr/) - "mf" stands for "Mail Filter". The filtering in this case apparently refers - to translation between different address and mailbox formats. - -zotnet/mts/ (deprecated, now in sbr/) - MTS code not specific to any single MTS apparently goes here. - -zotnet/tws/ (deprecated, now in sbr/) - "tws" apparently stands for "time with structure", a rather odd phrase. - This directory used to be the place for date and time manipulation code, but - currently nothing in here is compiled. There are new, more portable - versions of the key files in h/ and sbr/, and this directory will soon go - away completely. + "uip" stands for "User Interface Programs". Most mmh commands have a + file in this directory named .c containing the code for that + command (e.g. repl.c). In some cases there is also an auxiliary file + called sbr.c which contains additional subroutines called + from .c. -------------------------------------------------------- -nmh-local functions to use in preference to OS versions -------------------------------------------------------- +---------------------- +version control system +---------------------- -For some system functions whose availability or behavior varies from OS to OS, -nmh conditionally uses a local definition with the same name as the OS function -(e.g. snprintf()). For other functions, developers need to avoid the OS -versions and always use the nmh-supplied function. Here is a list of such -functions: +As of December 2010, nmh has switched to using git for revision control +instead of CVS. Mmh has stick to git. While the topic of git is beyond +the scope of this FAQ, to get started with git and mmh, you can run the +following command to checkout the mmh repository: -OS function nmh-local version to use instead -=========== ================================ -getpass() nmh_getpass() + % git clone http://git.marmaro.de/mmh +That will create a workspace called mmh. To update that workspace +change to it and run: -------------- -releasing nmh -------------- + % git pull -To make a public release of nmh (we'll use version 1.0.4 and my mhost.com -account, danh, as examples here): - 1. % echo 1.0.4 > VERSION - - 2. Put a comment like "Released nmh-1.0.4." in the ChangeLog. - - 3. % cvs commit ChangeLog VERSION - - 4. % cvs tag nmh-1_0_4 - (cvs treats dots specially, so underscores are substituted here.) - - 5. % make nmhdist - - 6. Untar nmh-1.0.4.tar.gz and `diff -r' it vs. your CVS tree. Make sure no - files got left out of the distribution that should be in it (due to someone - forgetting to update the DIST variables in the Makefiles). - - 7. If you have root access on your machine, it's good at this point to do: - - % chown -R 0:0 nmh-1.0.4 - % tar cvf nmh-1.0.4.tar nmh-1.0.4 - % gzip nmh-1.0.4.tar - - If you leave the files in the archive as being owned by yourself, your UID - may coincide with one of a user on a machine where nmh is being installed, - making it possible for that user to Trojan the nmh code before the system - administrator finishes installing it. - - 8. Make sure your new tarball uncompresses and untars with no problem. Make - sure you can configure, make, and install nmh from it. - - 9. If all is well and your tarball is final, go back to your CVS tree and do: - - % echo 1.0.4+dev > VERSION - -10. Put a comment like "Upped the version number to 1.0.4+dev until the next nmh - release." in the ChangeLog. - -11. % cvs commit ChangeLog VERSION +-------------- +autoconf files +-------------- -12. If possible, make an MD5 hash and/or a PGP signature of nmh-1.0.4.tar.gz. +If you wish to change the `configure' script or its related files, +you'll need to first install GNU m4 and GNU autoconf. Mmh is currently +using a minimum of autoconf 2.61. -13. % scp -p nmh-1.0.4.tar.gz* danh@mhost.com:/var/ftp/pub/nmh +Most of the configure-related files are automatically generated. The +only files you should need to manually edit are `acconfig.h' and +`configure.ac'. Don't, for instance, edit `config.h.in'. Though it is +an input file from the point of view of the users (and the configure +script) it is an output file from the point of view of the developers +(and the autoconf script). -14. Send an announcement to exmh-users@redhat.com, exmh-workers@redhat.com, - mh-users@ics.uci.edu, and nmh-announce@mhost.com. If the release fixes - significant security holes, also send an announcement to - bugtraq@securityfocus.com. The exmh lists require you to be subscribed in - order to post. Note that you don't need to post separately to comp.mail.mh, - as the mh-users mailing list is apparently bidirectionally gatewayed to it. +Note that the automatically generated autoconf files (such as +`config.h.in', `stamp-h.in', and `configure'), are NOT kept in the +version control system. Thus, when you check out the source tree, +you need to run the `autogen.sh' script before you can build anything: - Preferably, the announcement should contain the MD5 hash generated above, - and should be PGP-signed. It should include the FTP URL for the tarball as - well as the URL of the website. It should contain a brief summary of - visible changes, as well as the URL of the cvsweb diff page that would show - a detailed list of changes. The changes between 1.0.3 and 1.0.4 would be - shown by: + % ./autogen.sh - http://www.mhost.com/cgi-bin/cvsweb/nmh/ChangeLog?r1=1.40&r2=1.71