mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 09:54:16 +01:00
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.
This commit is contained in:
Jan Sarenik
Christian Decker
parent
c03f584e19
commit
960548f311
101
doc/HACKING.md
101
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.
|
||||
|
||||
@ -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"
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user