From 9b129f7fb55196f6cb099fdad2d25464f2b47bb0 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Wed, 3 Jan 2018 15:58:11 +1030 Subject: [PATCH] doc/HACKING.md: update. Signed-off-by: Rusty Russell --- doc/HACKING.md | 51 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/doc/HACKING.md b/doc/HACKING.md index 41c05878b..4be9d9c50 100644 --- a/doc/HACKING.md +++ b/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 -coding style. Patches are welcome! +It's in C, to encourage alternate implementations. It uses the [Linux +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 -to an array of 'struct bitcoin_tx_input'; they are allocated off the -'struct bitcoind_tx', so freeing the 'struct bitcoind_tx' frees them +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 +`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!