5 This file is intended to provide a few tips for anyone doing development on nmh.
6 Developers who learn things "the hard way" about the nmh codebase (as opposed to
7 local info best encoded in a comment) are encouraged to share their wisdom here.
9 The topics are organized alphabetically.
16 If you wish to change the `configure' script or its related files, you'll need
17 to first install GNU m4, available from <ftp://ftp.gnu.org/pub/gnu/m4/> and then
18 GNU autoconf (<ftp://ftp.gnu.org/pub/gnu/autoconf/>). Nmh is currently using
19 a minimum of autoconf 2.54.
21 Most of the configure-related files are automatically generated. The only files
22 you should need to manually edit are acconfig.h and configure.in. Don't, for
23 instance, edit config.h.in. Though it is an input file from the point of view
24 of the users (and the configure script) it is an output file from the point of
25 view of the developers (and the autoconf script).
27 Note that the automatically generated autoconf files (such as config.h.in,
28 stamp-h.in, and configure), are NOT kept in git. Thus, when you check out
29 a git tree, you need to run the autogen.sh script before you can build
38 Following is a list of nmh's directories along with a brief description of the
39 purpose of each one. Meanings are given for the abbreviations, but note that
40 these meanings are just informed guesses as to what the MH developers were
44 The top-level directory. Contains files like README and INSTALL.
47 Contains utility files for the `configure' process. Ordinarily nothing in
48 here needs to be messed with.
51 Contains more specialized documentation, such as this file and
55 Contains files, file templates, and scripts to generate files that will be
56 installed in the ${prefix}/etc directory. Stuff like replcomps.
59 Most of nmh's header (.h) files are kept not in the individual source
60 directories, but in this central location.
63 Contains all the input files that are processed to generate nmh's manual
67 "mts" stands for "Message Transfer Service". Source files specific to the
68 different MTSs go in the subdirectories.
70 mts/mmdf/ (deprecated)
71 "mmdf" stands for "Multichannel Memorandum Distribution Facility". It is an
72 alternative to sendmail used primarily on SCO UNIX.
74 mts/sendmail/ (deprecated: handled by mts.conf)
75 When nmh is configured --with-mts=sendmail, the files in this directory are
79 When nmh is configured to just talk to an SMTP server over TCP/IP, the
80 source in this directory is compiled.
83 "sbr" stands for "subroutine(s)". For the most part, each source file in
84 this directory contains a single function with the same name as the source
85 file. These functions are of general use and are called from throughout
89 "uip" stands for "User Interface Programs". Most nmh commands have a file
90 in this directory named <command>.c containing the code for that command
91 (e.g. repl.c). In some cases there is also an auxiliary file called
92 <command>sbr.c which contains additional subroutines called from <command>.c
93 (which would contain not much else besides main()).
96 Files in this hierarchy were either written by or moved here by UCI
97 (University of California, Irvine) after they took over MH from the Rand
98 Corporation. "Zot!" is the sound effect made by the anteater in the "B.C."
99 comic strip when its tongue lashes out at ants. The anteater is UCI's
100 official mascot. Not sure whether UCInet was once called ZotNet...
102 zotnet/bboards/ (deprecated)
103 UCI added Bulletin Board functionality to MH with the `bbc' command. This
104 functionality has been removed from nmh but apparently files in this
105 directory are still needed for other purposes.
107 zotnet/mf/ (deprecated, now in sbr/)
108 "mf" stands for "Mail Filter". The filtering in this case apparently refers
109 to translation between different address and mailbox formats.
111 zotnet/mts/ (deprecated, now in sbr/)
112 MTS code not specific to any single MTS apparently goes here.
114 zotnet/tws/ (deprecated, now in sbr/)
115 "tws" apparently stands for "time with structure", a rather odd phrase.
116 This directory used to be the place for date and time manipulation code, but
117 currently nothing in here is compiled. There are new, more portable
118 versions of the key files in h/ and sbr/, and this directory will soon go
126 As of December 2010, nmh has switched to using git for revision control
127 instead of CVS. While the topic of git is beyond the scope of this FAQ,
128 to get started with git & nmh, you can run the following command to checkout
131 % git clone git://git.savannah.nongnu.org/nmh.git
134 -------------------------------------------------------
135 nmh-local functions to use in preference to OS versions
136 -------------------------------------------------------
138 For some system functions whose availability or behavior varies from OS to OS,
139 nmh conditionally uses a local definition with the same name as the OS function
140 (e.g. snprintf()). For other functions, developers need to avoid the OS
141 versions and always use the nmh-supplied function. Here is a list of such
144 OS function nmh-local version to use instead
145 =========== ================================
146 getpass() nmh_getpass()
153 To make a public release of nmh (we'll use version 1.0.4 and my mhost.com
154 account, danh, as examples here; the convention for release candidates
155 is to use something like "1.0.4-RC1"):
157 1. % echo 1.0.4 > VERSION
158 % date +"%e %B %Y" > DATE
159 (DATE should contain something like "30 December 2000")
161 2. Put a comment like "Released nmh-1.0.4." in the ChangeLog.
163 3. % cvs commit ChangeLog VERSION DATE
165 4. % cvs tag nmh-1_0_4
166 (cvs treats dots specially, so underscores are substituted here.)
170 6. Untar nmh-1.0.4.tar.gz and `diff -r' it vs. your CVS tree. Make sure no
171 files got left out of the distribution that should be in it (due to someone
172 forgetting to update the DIST variables in the Makefiles).
174 7. If you have root access on your machine, it's good at this point to do:
176 % chown -R 0:0 nmh-1.0.4
177 % tar cvf nmh-1.0.4.tar nmh-1.0.4
180 If you leave the files in the archive as being owned by yourself, your UID
181 may coincide with one of a user on a machine where nmh is being installed,
182 making it possible for that user to Trojan the nmh code before the system
183 administrator finishes installing it.
185 8. Make sure your new tarball uncompresses and untars with no problem. Make
186 sure you can configure, make, and install nmh from it.
188 9. If all is well and your tarball is final, go back to your CVS tree and do:
190 % echo 1.0.4+dev > VERSION
192 10. Put a comment like "Upped the version number to 1.0.4+dev until the next nmh
193 release." in the ChangeLog.
195 11. % cvs commit ChangeLog VERSION
197 12. If possible, make an MD5 hash and/or a PGP signature of nmh-1.0.4.tar.gz.
198 Assuming you have gpg set up, this should be:
199 % gpg --output nmh-1.0.4.tar.gz.sig --detach-sig nmh-1.0.4.tar.gz
201 You can verify the signature with
202 % gpg --verify nmh-1.0.4.tar.gz.sig nmh-1.0.4.tar.gz
204 13. Upload the files to savannah. First make sure they are mode 664 so
205 they will have the right permissions on the server end
206 (see https://savannah.gnu.org/maintenance/SharedDownloadArea)
207 % chmod 664 nmh-1.0.4.tar.gz*
209 Then scp them across:
210 % scp -p nmh-1.0.4.tar.gz* youruser@dl.sv.nongnu.org:/releases/nmh/
212 14. Update the http://www.nongnu.org/nmh/ homepage. (It lives in the 'webpages
213 repository'; see https://savannah.nongnu.org/cvs/?group=nmh)
215 15. Add a news item to the savannah nmh page. You'll have to submit it first
216 and then separately approve it (under News->Manage).
218 16. Send the release announcement email to the following places:
219 nmh-workers@nongnu.org
220 nmh-announce@nongnu.org
221 exmh-users@redhat.com
222 exmh-workers@redhat.com
223 mh-e-users@lists.sourceforge.net
224 mh-users@ics.uci.edu *or* comp.mail.mh (there is a bidirectional gateway)
226 If the release fixes significant security holes, also send an announcement
227 to bugtraq@securityfocus.com. The exmh lists require you to be subscribed
228 in order to post. Note that you don't need to post separately to
229 comp.mail.mh, as the mh-users mailing list is apparently bidirectionally
232 Preferably, the announcement should contain the MD5 hash generated above,
233 and should be PGP-signed. It should include the URL for the tarball as
234 well as the URL of the website. It should contain a brief summary of
235 visible changes, as well as the URL of the cvsweb diff page that would show
236 a detailed list of changes. The changes between 1.2 and 1.3 would be
239 http://cvs.savannah.gnu.org/viewvc/nmh/ChangeLog?root=nmh&r1=1.215&r2=1.254.2.13