mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 01:43:36 +01:00
Code Issues Projects Releases Wiki Activity

doc/HACKING.md: update.

Browse Source 
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2018-01-03 15:58:11 +10:30
parent 90527498bc
commit 9b129f7fb5
1 changed files with 45 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
doc/HACKING.md
View File

@ -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!<br>