X-Git-Url: http://git.marmaro.de/?a=blobdiff_plain;ds=sidebyside;f=docs%2FREADME.developers;h=dcec2a73a4971d1c19998ee3a23725b9bdca85b7;hb=860ebc0e4bd25ef45ca0257e90daa6a61b7f477a;hp=14cf138e3a489464b3f40d36672f2615f339f277;hpb=942b25bf618535880b78278283911c26b3a86c0a;p=mmh
diff --git a/docs/README.developers b/docs/README.developers
index 14cf138..dcec2a7 100644
--- a/docs/README.developers
+++ b/docs/README.developers
@@ -1,231 +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
- % date +"%e %B %Y" > DATE
- (DATE should contain something like "30 December 2000")
-
- 2. Put a comment like "Released nmh-1.0.4." in the ChangeLog.
-
- 3. % cvs commit ChangeLog VERSION DATE
-
- 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