git.marmaro.de Git - mmh/blob - docs/README.developers

   1 #
   2 # README.developers
   3 #
   4
   5 This file is intended to provide a few tips for anyone doing development
   6 on mmh. Developers who learn things "the hard way" about the mmh codebase
   7 (as opposed to local info best encoded in a comment) are encouraged to
   8 share their wisdom here.
   9
  10 Absolute beginners should start reading docs/README.start-devel.
  11
  12
  13 -------------------
  14 directory structure
  15 -------------------
  16
  17 Following is a list of mmh's directories along with a brief description
  18 of the purpose of each one. Meanings are given for the abbreviations,
  19 but note that these meanings are just informed guesses as to what the
  20 MH developers were thinking.
  21
  22 ./
  23     The top-level directory. Contains files like README and INSTALL.
  24
  25 config/
  26     Contains utility files for the `configure' process. Ordinarily
  27     nothing in here needs to be messed with, but config/config.c is
  28     very interesting to have a look at.
  29
  30 docs/
  31     Contains more specialized documentation, such as this file and
  32     the FAQ.
  33
  34 etc/
  35     Contains files, file templates, and scripts to generate files that
  36     will be installed in the ${prefix}/etc directory. Stuff like
  37     replcomps.
  38
  39 h/
  40     Most of mmh's header files are kept in this central location instead
  41     of in the individual source directories.
  42
  43 man/
  44     Contains all the input files that are processed to generate mmh's
  45     manual pages.
  46
  47 sbr/
  48     "sbr" stands for "subroutine(s)". For the most part, each source
  49     file in this directory contains a single function with the same
  50     name as the source file. These functions are of general use and
  51     are called from throughout mmh.
  52
  53 uip/
  54     "uip" stands for "User Interface Programs". Most mmh commands have a
  55     file in this directory named <command>.c containing the code for that
  56     command (e.g. repl.c). In some cases there is also an auxiliary file
  57     called <command>sbr.c which contains additional subroutines called
  58     from <command>.c.
  59
  60
  61 ----------------------
  62 version control system
  63 ----------------------
  64
  65 As of December 2010, nmh has switched to using git for revision control
  66 instead of CVS. Mmh has stick to git. While the topic of git is beyond
  67 the scope of this FAQ, to get started with git and mmh, you can run the
  68 following command to checkout the mmh repository:
  69
  70     % git clone http://git.marmaro.de/mmh
  71
  72 That will create a workspace called mmh. To update that workspace
  73 change to it and run:
  74
  75     % git pull
  76
  77
  78 --------------
  79 autoconf files
  80 --------------
  81
  82 If you wish to change the `configure' script or its related files,
  83 you'll need to first install GNU m4 and GNU autoconf. Mmh is currently
  84 using a minimum of autoconf 2.61.
  85
  86 Most of the configure-related files are automatically generated. The
  87 only files you should need to manually edit are `acconfig.h' and
  88 `configure.ac'. Don't, for instance, edit `config.h.in'. Though it is
  89 an input file from the point of view of the users (and the configure
  90 script) it is an output file from the point of view of the developers
  91 (and the autoconf script).
  92
  93 Note that the automatically generated autoconf files (such as
  94 `config.h.in', `stamp-h.in', and `configure'), are NOT kept in the
  95 version control system. Thus, when you check out the source tree,
  96 you need to run the `autogen.sh' script before you can build anything:
  97
  98         % ./autogen.sh
  99