How to start developing nmh =========================== markus schnalke 2010-12 I started using nmh in Fall 2009. Soon afterwards, I used it exclusivly. In Spring 2010, I subscribed to the nmh-workers mailing list. From October until December 2010, I worked for two month full-time on nmh as a private project. First of all, I needed to become familiar with the code. This had been the most difficult part. This document is based on my experience on starting to hack nmh. It describes how I would do it a second time. These are my recommendations. Prerequisites ------------- You should be familiar with nmh. Use it! Adjust nmh to your needs. This is almost a requirement for using it for modern emailing. It took me several month until I had a satisfying setup. Lots of research and reading was necessary. Subscribe to the nmh-workers mailing list [0] and read it. Reading documentation --------------------- Read Jerry Peek's book ``MH & nmh: Email for Users & Programmers'' [1], at least the history, concepts, and get an overview of the rest. This book is a wonderful resource for everything about nmh. Cross-read the FAQs [2] although they are old. Read README and docs/README.developers. The rest below docs/ is valuable too. You might want to read it now or later. Reading code ------------ I split the task of code reading into five stages. (1) Get an overview: Understand the directory structure. Get a feeling for what kinds of files are unter sbr/ and what under uip/. Scrolling through the files is sufficient for that. These two directories will be most important. See docs/README.developers for help. (2) Take a look at some simple tool: I recommend reading uip/rmm.c, which is a pretty straight-forward tool. It shows the structure of the common tool code in nmh pretty well. You don't need to fully understand it, but you should try to find out how things work generally. The identifiers and comments in the code will provide most of that information. (3) Read through the header files: Read h/mh.h, the central header file of the project. It contains a lot of important information. Like above, you don't need to understand it fully now. Later, jump back to this header file as needed in order to incrementally understand it better and better. (4) Read code in uip/, starting with simple tools: Now you can continue reading tool code in uip/. Go from the simple tools (e.g. mhparam, mhpath) to the more complex ones (e.g. send, pick, spost). Defer everything with MIME involved (e.g. mhshow, mhbuild) and the tools that use format or component files until the end. As a rule of thumb: Simple tools are those with few lines of code and no *sbr.c files. (5) Jump to sbr/ as needed: As you read through the code, you'll encounter several functions that are not part of the C standard library but of similar style. Look for these below sbr/. There most files are named like the single function they contain. You can often guess from the filename what is inside. Read their sources as you need them. I found it useful to write down short explanations of functions whose names didn't express enough information. Once you reached this point, I'm sure you'll find your further way alone. Code history ------------ Note that large parts of the code are very old and were written by a whole bunch of different people. You will likely encounter code that simply puzzles you. Check the ChangeLog and similar sources first. If you still don't understand, ask on the mailing list. You'll see that the folks there sometimes don't know either. A lot of knowledge was lost in time. The Community ------------- A short note for those who come from the modern Free Software world: Don't expect nmh to be like modern Free Software projects. Nmh is old and MH is much older. The community still carries old spirits; you might not be used to them. Also, keep in mind that nmh is matured back-end software, thus the view on change may be different than you might expect. Nonetheless, I encourage you to interact with the community. You will learn a lot and you will receive valuable comments. REFERENCES ---------- [0] http://lists.nongnu.org/mailman/listinfo/nmh-workers [1] http://rand-mh.sourceforge.net/book/ [2] http://www.newt.com/faq/mh.html