lukechilds
/
lightning
mirror of https://github.com/lukechilds/lightning.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

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.
ppa-0.6.1
Jan Sarenik 7 years ago
committed by Christian Decker
parent
c03f584e19
commit
960548f311
2 changed files with 80 additions and 48 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 101
      doc/HACKING.md
  2. 27
      doc/INSTALL.md

101
doc/HACKING.md
View File

@ -8,29 +8,33 @@ exploits.
It is designed to implement the lightning protocol as specified in It is designed to implement the lightning protocol as specified in
[various BOLTs](https://github.com/lightningnetwork/lightning-rfc). [various BOLTs](https://github.com/lightningnetwork/lightning-rfc).
Getting Started Getting Started
--------------- ---------------
It's in C, to encourage alternate implementations. It uses the [Linux It's in C, to encourage alternate implementations.
coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html). It uses the [Linux coding style][style].
Patches are welcome! 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 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 hierarchical memory allocator, where each allocation has a parent, and
thus lifetimes are grouped. eg. a `struct bitcoin_tx` has a pointer 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 to an array of `struct bitcoin_tx_input`; they are allocated off the
`struct bitcoind_tx`, so freeing the `struct bitcoind_tx` frees them `struct bitcoind_tx`, so freeing the `struct bitcoind_tx` frees them all.
all. Tal also supports destructors, which are usually used to remove Tal also supports destructors, which are usually used to remove things
things from lists, etc. from lists, etc.
Some routines use take(): take() marks a pointer as to be consumed Some routines use take(): take() marks a pointer as to be consumed
(e.g. freed automatically before return) by a called function. It can (e.g. freed automatically before return) by a called function.
safely accept NULL pointers. Functions whose prototype in headers has It can safely accept NULL pointers.
the macro TAKES can have the specific argument as a take() call. Use Functions whose prototype in headers has the macro TAKES can have the
this sparingly, as it can be very confusing. 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 The more complex daemons use async io (ccan/io): you register callbacks
happen once I/O is available, then you return what to do next. This and they happen once I/O is available, then you return what to do next.
does not use threads, so the code flow is generally fairly simple. This does not use threads, so the code flow is generally fairly simple.
The Components The Components
-------------- --------------
@ -57,7 +61,8 @@ Here's a list of parts, with notes:
(as used by check-source) (as used by check-source)
- generate-wire.py: generate marshal/unmarshal routines from - generate-wire.py: generate marshal/unmarshal routines from
extracts from BOLT specs, and as specified by subdaemons. 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 * devtools/ - tools for developers
- Currently just bolt11-cli for decoding bolt11 - 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. * 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. * 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. * 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. * 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 Debugging
--------- ---------
You can debug crashing subdaemons with the argument You can debug crashing subdaemons with the argument
`--dev-debugger=lightning_channeld`, where `channeld` is the subdaemon name. It `--dev-debugger=lightning_channeld`, where `channeld` is the subdaemon name.
will print out (to stderr) a command such as: It will print out (to stderr) a command such as:
gdb -ex 'attach 22398' -ex 'p debugger_connected=1' lightningd/lightning_hsmd 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 Run this command to start debugging.
to exit the infinite while loop, otherwise you can type `continue` to begin. You may need to type `return` one more time to exit the infinite while
loop, otherwise you can type `continue` to begin.
Database Database
-------- --------
c-lightning state is persisted in `lightning-dir`. It is a sqlite database c-lightning state is persisted in `lightning-dir`.
stored in the `lightningd.sqlite3` file, typically under `~/.lightning`. You can It is a sqlite database stored in the `lightningd.sqlite3` file, typically
run queries against this file like so: 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" $ 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. 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 Make sure that clightning is not running when you query the database,
queries may lock the database and cause crashes. as some queries may lock the database and cause crashes.
#### Common variables #### Common variables
Table `vars` contains global variables used by lightning node. 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. * `next_pay_index` next resolved invoice counter that will get assigned.
* `bip32_max_index` last wallet derivation counter. * `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. Note: Each time `newaddr` command is called, `bip32_max_index` counter
Each address generated after `bip32_max_index` is not included as lightning funds. is increased to the last derivation index.
Each address generated after `bip32_max_index` is not included as
lightning funds.
Testing Testing
@ -156,24 +170,28 @@ valgrind installed, and build with DEVELOPER=1 (currently the default).
exists (currently disabled, since BOLTs are being re-edited). exists (currently disabled, since BOLTs are being re-edited).
* unit tests - run by `make check`, these are `run-*.c` files in test/ * unit tests - run by `make check`, these are `run-*.c` files in test/
subdirectories which can test routines inside C source files. You subdirectories which can test routines inside C source files.
should insert `/* AUTOGENERATED MOCKS START */` and `/* AUTOGENERATED MOCKS END */` You should insert `/* AUTOGENERATED MOCKS START */` and
lines, and `make update-mocks` will automatically generate stub functions `/* AUTOGENERATED MOCKS END */` lines, and `make update-mocks`
which will allow you to link (which will conveniently crash if they're called). 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 * blackbox tests - run by `make check` or directly as
`PYTHONPATH=contrib/pylightning DEVELOPER=1 python3 tests/test_lightningd.py -f`. `PYTHONPATH=contrib/pylightning DEVELOPER=1 python3
You can run these much faster by putting `NO_VALGRIND=1` after DEVELOPER=1, or tests/test_lightningd.py -f`.
after `make check`, which has the added bonus of doing memory leak detection. You can run these much faster by putting `NO_VALGRIND=1` after
You can also append `LightningDTests.TESTNAME` to run a single test. 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 Subtleties
---------- ----------
There are a few subtleties you should be aware of as you modify deeper parts There are a few subtleties you should be aware of as you modify deeper
of the code: parts of the code:
* `structeq` will not work on some structures. * `structeq` will not work on some structures.
For example, it will not work with `struct short_channel_id` --- use For example, it will not work with `struct short_channel_id` --- use
@ -191,7 +209,8 @@ of the code:
Further Information 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> Cheers!<br>
Rusty. Rusty.

27
doc/INSTALL.md
View File

@ -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) * asciidoc: for formatting the man pages (if you change them)
* valgrind: for extra debugging checks * 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 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 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 apt-get install software-properties-common
sudo add-apt-repository ppa:bitcoin/bitcoin sudo add-apt-repository ppa:bitcoin/bitcoin
@ -61,7 +63,8 @@ Get dependencies:
# pkg install -y autoconf automake git gmake libtool python python3 sqlite3 # 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 # pkg install -y bitcoin-daemon bitcoin-utils
``` ```
@ -79,7 +82,9 @@ $ gmake
Running lightning: 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 # service bitcoind start
@ -103,9 +108,12 @@ valgrind asciidoc --run make
To cross-compile for Android 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 export PATH=$PATH:/path/to/android/toolchain/bin
@ -119,12 +127,17 @@ export CXX=$target_host-clang++
export LD=$target_host-ld export LD=$target_host-ld
export STRIP=$target_host-strip export STRIP=$target_host-strip
``` ```
Two makefile targets should not be cross-compiled so we specify a native CC: Two makefile targets should not be cross-compiled so we specify a native CC:
``` ```
make CC=clang clean ccan/tools/configurator/configurator make CC=clang clean ccan/tools/configurator/configurator
make clean -C ccan/ccan/cdump/tools && make CC=clang -C ccan/ccan/cdump/tools 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" BUILD=x86_64 HOST=arm-linux-androideabi make PIE=1 DEVELOPER=0 CONFIGURATOR_CC="arm-linux-androideabi-clang -static"
``` ```

Write Preview
Loading…
Cancel
Save