From 960548f311cca0ea04cd49f5a3de3efa77a1a41d Mon Sep 17 00:00:00 2001 From: Jan Sarenik Date: Thu, 1 Mar 2018 14:58:48 +0100 Subject: [PATCH] doc: Reflow HACKING.md and INSTALL.md without textual change See previous commit 9504a77b for a script to prove there is no change in the rendered file, just readability plain-text improvements. --- doc/HACKING.md | 101 +++++++++++++++++++++++++++++-------------------- doc/INSTALL.md | 27 +++++++++---- 2 files changed, 80 insertions(+), 48 deletions(-) diff --git a/doc/HACKING.md b/doc/HACKING.md index d4e24c173..63949c0b2 100644 --- a/doc/HACKING.md +++ b/doc/HACKING.md @@ -8,29 +8,33 @@ exploits. It is designed to implement the lightning protocol as specified in [various BOLTs](https://github.com/lightningnetwork/lightning-rfc). + Getting Started --------------- -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). +It's in C, to encourage alternate implementations. +It uses the [Linux coding style][style]. Patches are welcome! +[style]: https://www.kernel.org/doc/html/v4.10/process/coding-style.html + 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 -all. Tal also supports destructors, which are usually used to remove -things from lists, etc. +`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. Some routines use take(): take() marks a pointer as to be consumed -(e.g. freed automatically before return) by a called function. It can -safely accept NULL pointers. Functions whose prototype in headers has -the macro TAKES can have the specific argument as a take() call. Use -this sparingly, as it can be very confusing. +(e.g. freed automatically before return) by a called function. +It can safely accept NULL pointers. +Functions whose prototype in headers has the macro TAKES can have the +specific argument as a take() call. +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 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 -------------- @@ -57,7 +61,8 @@ 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. + - mockup.sh / update-mocks.sh: tools to generate mock functions for + unit tests. * devtools/ - tools for developers - Currently just bolt11-cli for decoding bolt11 @@ -70,40 +75,47 @@ Here's a list of parts, with notes: * cli/ - commandline utility to control lightning daemon. -* lightningd/ - master daemon which controls the subdaemons and passes peer file descriptors between them. +* lightningd/ - master daemon which controls the subdaemons and passes + peer file descriptors between them. * wallet/ - database code used by master for tracking what's happening. -* hsmd/ - daemon which looks after the cryptographic secret, and performs commitment signing. +* hsmd/ - daemon which looks after the cryptographic secret, and performs + commitment signing. -* gossipd/ - daemon to chat to peers which don't have any channels, and maintains routing information and broadcasts gossip. +* gossipd/ - daemon to chat to peers which don't have any channels, + and maintains routing information and broadcasts gossip. * openingd/ - daemon to open a channel for a single peer. -* channeld/ - daemon to operate a single peer once channel is operating normally. +* channeld/ - daemon to operate a single peer once channel is operating + normally. * closingd/ - daemon to handle mutual closing negotiation with a single peer. -* onchaind/ - daemon to hand a single channel which has had its funding transaction spent. +* onchaind/ - daemon to hand a single channel which has had its funding + transaction spent. Debugging --------- You can debug crashing subdaemons with the argument -`--dev-debugger=lightning_channeld`, where `channeld` is the subdaemon name. It -will print out (to stderr) a command such as: +`--dev-debugger=lightning_channeld`, where `channeld` is the subdaemon name. +It will print out (to stderr) a command such as: gdb -ex 'attach 22398' -ex 'p debugger_connected=1' lightningd/lightning_hsmd -Run this command to start debugging. You may need to type `return` one more time -to exit the infinite while loop, otherwise you can type `continue` to begin. +Run this command to start debugging. +You may need to type `return` one more time to exit the infinite while +loop, otherwise you can type `continue` to begin. Database -------- -c-lightning state is persisted in `lightning-dir`. It is a sqlite database -stored in the `lightningd.sqlite3` file, typically under `~/.lightning`. You can -run queries against this file like so: +c-lightning state is persisted in `lightning-dir`. +It is a sqlite database stored in the `lightningd.sqlite3` file, typically +under `~/.lightning`. +You can run queries against this file like so: $ sqlite3 ~/.lightning/lightningd.sqlite3 "SELECT HEX(prev_out_tx), prev_out_index, status FROM outputs" @@ -121,8 +133,8 @@ Or you can launch into the sqlite3 repl and check things out from there: Some data is stored as raw bytes, use `HEX(column)` to pretty print these. -Make sure that clightning is not running when you query the database, as some -queries may lock the database and cause crashes. +Make sure that clightning is not running when you query the database, +as some queries may lock the database and cause crashes. #### Common variables Table `vars` contains global variables used by lightning node. @@ -141,8 +153,10 @@ Variables: * `next_pay_index` next resolved invoice counter that will get assigned. * `bip32_max_index` last wallet derivation counter. -Note: Each time `newaddr` command is called, `bip32_max_index` counter is increased to the last derivation index. -Each address generated after `bip32_max_index` is not included as lightning funds. +Note: Each time `newaddr` command is called, `bip32_max_index` counter +is increased to the last derivation index. +Each address generated after `bip32_max_index` is not included as +lightning funds. Testing @@ -156,24 +170,28 @@ valgrind installed, and build with DEVELOPER=1 (currently the default). 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). + 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. + `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. +Our Travis CI instance (see `.travis.yml`) runs all these for each +pull request. Subtleties ---------- -There are a few subtleties you should be aware of as you modify deeper parts -of the code: +There are a few subtleties you should be aware of as you modify deeper +parts of the code: * `structeq` will not work on some structures. For example, it will not work with `struct short_channel_id` --- use @@ -191,7 +209,8 @@ of the code: 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. +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!
Rusty. diff --git a/doc/INSTALL.md b/doc/INSTALL.md index e4c5c8b4c..68a5eb6ec 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -10,7 +10,8 @@ For actually doing development and running the tests, you will also need: * asciidoc: for formatting the man pages (if you change them) * valgrind: for extra debugging checks -You will also need a version of bitcoind with segregated witness and estimatesmartfee economical node, such as the 0.15 or above. +You will also need a version of bitcoind with segregated witness and +estimatesmartfee economical node, such as the 0.15 or above. To Build on Ubuntu 15.10 or above --------------------- @@ -20,7 +21,8 @@ Get dependencies: sudo apt-get install -y autoconf automake build-essential git libtool libgmp-dev libsqlite3-dev python python3 net-tools libsodium-dev ``` -If you don't have Bitcoin installed locally you'll need to install that as well: +If you don't have Bitcoin installed locally you'll need to install that +as well: ``` sudo apt-get install software-properties-common sudo add-apt-repository ppa:bitcoin/bitcoin @@ -61,7 +63,8 @@ Get dependencies: # pkg install -y autoconf automake git gmake libtool python python3 sqlite3 ``` -If you don't have Bitcoin installed locally you'll need to install that as well: +If you don't have Bitcoin installed locally you'll need to install that +as well: ``` # pkg install -y bitcoin-daemon bitcoin-utils ``` @@ -79,7 +82,9 @@ $ gmake Running lightning: -**Note**: Edit your `/usr/local/etc/bitcoin.conf` to include `rpcuser=` and `rpcpassword=` first, you may also need to include `testnet=1` +**Note**: Edit your `/usr/local/etc/bitcoin.conf` to include +`rpcuser=` and `rpcpassword=` first, you may also need to +include `testnet=1` ``` # service bitcoind start @@ -103,9 +108,12 @@ valgrind asciidoc --run make To cross-compile for Android -------------------- -Make a standalone toolchain as per https://developer.android.com/ndk/guides/standalone_toolchain.html. For c-lightning you must target an API level of 24 or higher. +Make a standalone toolchain as per +https://developer.android.com/ndk/guides/standalone_toolchain.html. +For c-lightning you must target an API level of 24 or higher. -Depending on your toolchain location and target arch, source env variables such as: +Depending on your toolchain location and target arch, source env variables +such as: ``` export PATH=$PATH:/path/to/android/toolchain/bin @@ -119,12 +127,17 @@ export CXX=$target_host-clang++ export LD=$target_host-ld export STRIP=$target_host-strip ``` + Two makefile targets should not be cross-compiled so we specify a native CC: ``` make CC=clang clean ccan/tools/configurator/configurator make clean -C ccan/ccan/cdump/tools && make CC=clang -C ccan/ccan/cdump/tools ``` -Install the `qemu-user` package. This will allow you to properly configure the build for the target device environment. Build with: + +Install the `qemu-user` package. +This will allow you to properly configure +the build for the target device environment. +Build with: ``` BUILD=x86_64 HOST=arm-linux-androideabi make PIE=1 DEVELOPER=0 CONFIGURATOR_CC="arm-linux-androideabi-clang -static" ```