doc/HACKING.md: update.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

doc/HACKING.md

@@ -10,31 +10,39 @@ It is designed to implement the lightning protocol as specified in
 
 Getting Started
 ---------------
-It's in C, to encourage alternate implementations.  It uses the Linux
+It's in C, to encourage alternate implementations.  It uses the [Linux
-coding style.  Patches are welcome!
+coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html). 
+Patches are welcome!
 
 To read the code, you'll probably need to understand ccan/tal: it's a
 hierarchical memory allocator, where each allocation has a parent, and
-thus lifetimes are grouped.  eg. a 'struct bitcoin_tx' has a pointer
+thus lifetimes are grouped.  eg. a `struct bitcoin_tx` has a pointer
-to an array of 'struct bitcoin_tx_input'; they are allocated off the
+to an array of `struct bitcoin_tx_input`; they are allocated off the
-'struct bitcoind_tx', so freeing the 'struct bitcoind_tx' frees them
+`struct bitcoind_tx`, so freeing the `struct bitcoind_tx` frees them
 all.  Tal also supports destructors, which are usually used to remove
 things from lists, etc.
 
-The daemons mostly use async io (ccan/io): you register callbacks and they
+Some routines use take() to indicate whether they should take ownership
+of a pointer.  Use this sparingly, as it can be very confusing.
+
+The more complex daemons use async io (ccan/io): you register callbacks and they
 happen once I/O is available, then you return what to do next.  This
 does not use threads, so the code flow is generally fairly simple.
 
+The Components
+--------------
 Here's a list of parts, with notes:
 
 * ccan - useful routines from http://ccodearchive.net
   - Use make update-ccan to update it.
   - Use make update-ccan CCAN_NEW="mod1 mod2..." to add modules
+  - Do not edit this!  If you want a wrapper, add one to common/utils.h.
 
 * bitcoin/ - bitcoin script, signature and transaction routines.
   - Not a complete set, but enough for our purposes.
 
 * external/ - external libraries from other sources
+  - libbacktrace - library to provide backtraces when things go wrong.
   - libsodium - encryption library (should be replaced soon with built-in)
   - libwally-core - bitcoin helper library
   - secp256k1 - bitcoin curve encryption library within libwally-core
@@ -46,6 +54,10 @@ Here's a list of parts, with notes:
     (as used by check-source)
   - generate-wire.py: generate marshal/unmarshal routines from
     extracts from BOLT specs, and as specified by subdaemons.
+  - mockup.sh / update-mocks.sh: tools to generate mock functions for unit tests.
+
+* devtools/ - tools for developers
+   - Currently just bolt11-cli for decoding bolt11
 
 * contrib/ - python support and other stuff which doesn't belong :)
 
@@ -71,6 +83,33 @@ Here's a list of parts, with notes:
 
 * onchaind/ - daemon to hand a single channel which has had its funding transaction spent.
 
+Testing
+-------
+
+There are three kinds of tests.  For best results, you should have
+valgrind installed, and build with DEVELOPER=1 (currently the default).
+
+* source tests - run by `make check-source`, looks for whitespace,
+  header order, and checks formatted quotes from BOLTs if BOLTDIR
+  exists (currently disabled, since BOLTs are being re-edited).
+
+* unit tests - run by `make check`, these are run-*.c files in test/
+  subdirectories which can test routines inside C source files.  You
+  should insert `/* AUTOGENERATED MOCKS START */` and `/* AUTOGENERATED MOCKS END */`
+  lines, and `make update-mocks` will automatically generate stub functions
+  which will allow you to link (which will conveniently crash if they're called).
+
+* blackbox tests - run by `make check` or directly as
+  `PYTHONPATH=contrib/pylightning DEVELOPER=1 python3 tests/test_lightningd.py -f`.
+  You can run these much faster by putting `NO_VALGRIND=1` after DEVELOPER=1, or
+  after `make check`, which has the added bonus of doing memory leak detection.
+  You can also append `LightningDTests.TESTNAME` to run a single test.
+
+Our Travis CI instance (see `.travis.yml`) runs all these for each pull request.
+
+Further Information
+-------------------
+
 Feel free to ask questions on the lightning-dev mailing list, or on #c-lightning on IRC, or email me at rusty@rustcorp.com.au.
 
 Cheers!<br>