git.marmaro.de Git - mmh/blob - docs/README.start-devel

   1 How to start developing nmh
   2 ===========================
   3
   4 markus schnalke <meillo@marmaro.de>
   5 2010-12
   6
   7
   8 I started using nmh in Fall 2009. Soon afterwards, I used it exclusivly.
   9 In Spring 2010, I subscribed to the nmh-workers mailing list. From
  10 October until December 2010, I worked for two month full-time on nmh as
  11 a private project.
  12
  13 First of all, I needed to become familiar with the code. This had been
  14 the most difficult part. This document is based on my experience on
  15 starting to hack nmh. It describes how I would do it a second time.
  16 These are my recommendations.
  17
  18
  19 Prerequisites
  20 -------------
  21
  22 You should be familiar with nmh. Use it!
  23
  24 Adjust nmh to your needs. This is almost a requirement for using it
  25 for modern emailing. It took me several month until I had a satisfying
  26 setup. Lots of research and reading was necessary.
  27
  28 Subscribe to the nmh-workers mailing list [0] and read it.
  29
  30
  31 Reading documentation
  32 ---------------------
  33
  34 Read Jerry Peek's book ``MH & nmh: Email for Users & Programmers'' [1],
  35 at least the history, concepts, and get an overview of the rest. This
  36 book is a wonderful resource for everything about nmh.
  37
  38 Cross-read the FAQs [2] although they are old.
  39
  40 Read README and docs/README.developers. The rest below docs/ is
  41 valuable too. You might want to read it now or later.
  42
  43
  44 Reading code
  45 ------------
  46
  47 I split the task of code reading into five stages.
  48
  49 (1) Get an overview:
  50
  51 Understand the directory structure. Get a feeling for what kinds of
  52 files are unter sbr/ and what under uip/. Scrolling through the files
  53 is sufficient for that. These two directories will be most important.
  54 See docs/README.developers for help.
  55
  56 (2) Take a look at some simple tool:
  57
  58 I recommend reading uip/rmm.c, which is a pretty straight-forward
  59 tool. It shows the structure of the common tool code in nmh pretty
  60 well. You don't need to fully understand it, but you should try to
  61 find out how things work generally. The identifiers and comments in
  62 the code will provide most of that information.
  63
  64 (3) Read through the header files:
  65
  66 Read h/mh.h, the central header file of the project. It contains a lot
  67 of important information. Like above, you don't need to understand it
  68 fully now. Later, jump back to this header file as needed in order to
  69 incrementally understand it better and better.
  70
  71 (4) Read code in uip/, starting with simple tools:
  72
  73 Now you can continue reading tool code in uip/. Go from the simple
  74 tools (e.g. mhparam, mhpath) to the more complex ones (e.g. send,
  75 pick, spost). Defer everything with MIME involved (e.g. mhshow,
  76 mhbuild) and the tools that use format or component files until the
  77 end. As a rule of thumb: Simple tools are those with few lines of code
  78 and no *sbr.c files.
  79
  80 (5) Jump to sbr/ as needed:
  81
  82 As you read through the code, you'll encounter several functions that
  83 are not part of the C standard library but of similar style. Look for
  84 these below sbr/. There most files are named like the single function
  85 they contain. You can often guess from the filename what is inside.
  86 Read their sources as you need them. I found it useful to write down
  87 short explanations of functions whose names didn't express enough
  88 information.
  89
  90 Once you reached this point, I'm sure you'll find your further way
  91 alone.
  92
  93
  94 Code history
  95 ------------
  96
  97 Note that large parts of the code are very old and were written by a
  98 whole bunch of different people. You will likely encounter code that
  99 simply puzzles you. Check the ChangeLog and similar sources first. If
 100 you still don't understand, ask on the mailing list. You'll see that
 101 the folks there sometimes don't know either. A lot of knowledge was
 102 lost in time.
 103
 104
 105 The Community
 106 -------------
 107
 108 A short note for those who come from the modern Free Software world:
 109 Don't expect nmh to be like modern Free Software projects. Nmh is old
 110 and MH is much older. The community still carries old spirits; you
 111 might not be used to them. Also, keep in mind that nmh is matured
 112 back-end software, thus the view on change may be different than you
 113 might expect. Nonetheless, I encourage you to interact with the
 114 community. You will learn a lot and you will receive valuable comments.
 115
 116
 117
 118 REFERENCES
 119 ----------
 120 [0] http://lists.nongnu.org/mailman/listinfo/nmh-workers
 121 [1] http://rand-mh.sourceforge.net/book/
 122 [2] http://www.newt.com/faq/mh.html