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.
7 years ago · 960548f311
2 changed files with 80 additions and 48 deletions
--- 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!<br>
 Rusty.
--- 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=<foo>` and `rpcpassword=<bar>` first, you may also need to include `testnet=1`
+**Note**: Edit your `/usr/local/etc/bitcoin.conf` to include
+`rpcuser=<foo>` and `rpcpassword=<bar>` 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"
 ```