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"
```