Commit 80d66951 authored by Søren Bredlund Caspersen's avatar Søren Bredlund Caspersen Committed by freetrader
Browse files

[doc] Reduce markdown lint errors

Reduce number of markdown lint errors by moving indented codeblocks to fenced codeblocks instead.
Notice in CONTRIBUTING.md and doc/developer-notes.md that the code in lists now render as intended in the mkdocs output.

Test-plan:

- Check out master
- `markdownlint -c .markdownlint.json -o /tmp/before CONTRIBUTING.md contrib/devtools/README.md contrib/seeds/README.md contrib/testgen/README.md doc/build-osx.md doc/build-unix.md doc/developer-notes.md doc/ninja_targets.md doc/unit-tests.md doc/gitian-building/gitian-building-create-vm-debian.md doc/gitian-building/gitian-building-manual.md`
- Check out this MR
- `markdownlint -c .markdownlint.json -o /tmp/after CONTRIBUTING.md contrib/devtools/README.md contrib/seeds/README.md contrib/testgen/README.md doc/build-osx.md doc/build-unix.md doc/developer-notes.md doc/ninja_targets.md doc/unit-tests.md doc/gitian-building/gitian-building-create-vm-debian.md doc/gitian-building/gitian-building-manual.md`
- Compare the `before` a...
parent 2b15e2a1
......@@ -140,8 +140,10 @@ Getting set up with the Bitcoin Cash Node Repository
8. You may want to add the `mreq` alias to your `.git/config`:
[alias]
mreq = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
```
[alias]
mreq = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
```
This `mreq` alias can be used to easily check out Merge Requests from our
main repository if you intend to test them or work on them.
......@@ -177,9 +179,11 @@ as a Merge Request.
For example, for macOS:
curl http://releases.llvm.org/8.0.0/clang+llvm-8.0.0-x86_64-apple-darwin.tar.xz | tar -xJv
ln -s $PWD/clang+llvm-8.0.0-x86_64-apple-darwin/bin/clang-format /usr/local/bin/clang-format
ln -s $PWD/clang+llvm-8.0.0-x86_64-apple-darwin/bin/clang-tidy /usr/local/bin/clang-tidy
```
curl http://releases.llvm.org/8.0.0/clang+llvm-8.0.0-x86_64-apple-darwin.tar.xz | tar -xJv
ln -s $PWD/clang+llvm-8.0.0-x86_64-apple-darwin/bin/clang-format /usr/local/bin/clang-format
ln -s $PWD/clang+llvm-8.0.0-x86_64-apple-darwin/bin/clang-tidy /usr/local/bin/clang-tidy
```
To install `autopep8`, `flake8` and `phpcs` on Ubuntu:
......
......@@ -95,16 +95,20 @@ still compatible with the minimum supported Linux distribution versions.
Example usage after a gitian build:
find ../gitian-builder/build -type f -executable | xargs python3 contrib/devtools/symbol-check.py
```
find ../gitian-builder/build -type f -executable | xargs python3 contrib/devtools/symbol-check.py
```
If only supported symbols are used the return value will be 0 and the output will be empty.
If there are 'unsupported' symbols, the return value will be 1 a list like this will be printed:
.../64/test_bitcoin: symbol memcpy from unsupported version GLIBC_2.14
.../64/test_bitcoin: symbol __fdelt_chk from unsupported version GLIBC_2.15
.../64/test_bitcoin: symbol std::out_of_range::~out_of_range() from unsupported version GLIBCXX_3.4.15
.../64/test_bitcoin: symbol _ZNSt8__detail15_List_nod from unsupported version GLIBCXX_3.4.15
```
.../64/test_bitcoin: symbol memcpy from unsupported version GLIBC_2.14
.../64/test_bitcoin: symbol __fdelt_chk from unsupported version GLIBC_2.15
.../64/test_bitcoin: symbol std::out_of_range::~out_of_range() from unsupported version GLIBCXX_3.4.15
.../64/test_bitcoin: symbol _ZNSt8__detail15_List_nod from unsupported version GLIBCXX_3.4.15
```
update-translations.py
======================
......@@ -126,5 +130,7 @@ This looks only at which files include other files, treating the `.cpp` and `.h`
Example usage:
cd <project root>/src
../contrib/devtools/circular-dependencies.py {*,*/*,*/*/*}.{h,cpp}
```
cd <project root>/src
../contrib/devtools/circular-dependencies.py {*,*/*,*/*/*}.{h,cpp}
```
......@@ -14,17 +14,21 @@ below assume that the `dnsseed.dump` file from the mainnet seeder has been copie
`seeds_main.txt` and the `dnsseed.dump` file from the testnet3 seeder has been copied to
`seeds_testnet3.txt`, etc.
python3 makeseeds.py < seeds_main.txt > nodes_main.txt
python3 makeseeds.py < seeds_testnet3.txt > nodes_testnet3.txt
python3 makeseeds.py < seeds_testnet4.txt > nodes_testnet4.txt
python3 makeseeds.py < seeds_scalenet.txt > nodes_scalenet.txt
python3 generate-seeds.py . > ../../src/chainparamsseeds.h
```
python3 makeseeds.py < seeds_main.txt > nodes_main.txt
python3 makeseeds.py < seeds_testnet3.txt > nodes_testnet3.txt
python3 makeseeds.py < seeds_testnet4.txt > nodes_testnet4.txt
python3 makeseeds.py < seeds_scalenet.txt > nodes_scalenet.txt
python3 generate-seeds.py . > ../../src/chainparamsseeds.h
```
## Dependencies
Ubuntu:
sudo apt-get install python3-dnspython
```
sudo apt-get install python3-dnspython
```
## Testing user agent pattern modifications
......
......@@ -4,8 +4,10 @@ Utilities to generate test vectors for the data-driven Bitcoin tests.
Usage:
gen_base58_test_vectors.py valid 50 > ../../src/test/data/base58_keys_valid.json
gen_base58_test_vectors.py invalid 50 > ../../src/test/data/base58_keys_invalid.json
```
gen_base58_test_vectors.py valid 50 > ../../src/test/data/base58_keys_valid.json
gen_base58_test_vectors.py invalid 50 > ../../src/test/data/base58_keys_invalid.json
```
## ASERT test vectors
......
......@@ -40,7 +40,9 @@ When the popup appears, click *Install*.
If you want to run ZMQ tests with the test framework, you need the zmq python module:
pip3 install pyzmq
```
pip3 install pyzmq
```
Build Bitcoin Cash Node
------------------------
......
......@@ -60,20 +60,20 @@ Make sure you install all the build requirements mentioned above.
Then, install the toolchain and some additional dependencies:
```bash
sudo apt-get install autoconf automake curl g++-arm-linux-gnueabihf gcc-arm-linux-gnueabihf gperf pkg-config libtool
sudo apt-get install autoconf automake curl g++-arm-linux-gnueabihf gcc-arm-linux-gnueabihf gperf pkg-config libtool
```
To build executables for ARM:
```bash
cd depends
make build-linux-arm
cd ..
mkdir build
cd build
cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/LinuxARM.cmake -DENABLE_GLIBC_BACK_COMPAT=ON -DENABLE_STATIC_LIBSTDCXX=ON
ninja
ninja check # recommended
cd depends
make build-linux-arm
cd ..
mkdir build
cd build
cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/LinuxARM.cmake -DENABLE_GLIBC_BACK_COMPAT=ON -DENABLE_STATIC_LIBSTDCXX=ON
ninja
ninja check # recommended
```
For further documentation on the depends system see [README.md](../depends/README.md)
......@@ -89,19 +89,19 @@ Make sure you install all the build requirements mentioned above.
Then, install the toolchain and some additional dependencies:
```bash
sudo apt-get install autoconf automake curl gcc-aarch64-linux-gnu g++-aarch64-linux-gnu gperf pkg-config libtool
sudo apt-get install autoconf automake curl gcc-aarch64-linux-gnu g++-aarch64-linux-gnu gperf pkg-config libtool
```
To build executables for AArch64:
```bash
cd depends
make build-linux-aarch64
cd ..
mkdir build
cd build
cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/LinuxAArch64.cmake -DBUILD_BITCOIN_ZMQ=OFF
ninja
cd depends
make build-linux-aarch64
cd ..
mkdir build
cd build
cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/LinuxAArch64.cmake -DBUILD_BITCOIN_ZMQ=OFF
ninja
```
For further documentation on the depends system see [README.md](../depends/README.md)
......@@ -124,7 +124,7 @@ memory available when compiling Bitcoin Cash Node. On systems with less, gcc can
be tuned to conserve memory with additional CXXFLAGS:
```bash
cmake -GNinja -DCXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768" ..
cmake -GNinja -DCXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768" ..
```
### Strip debug symbols
......@@ -139,8 +139,10 @@ It can be downloaded from [here](http://miniupnp.tuxfamily.org/files/).
UPnP support is compiled in and turned off by default.
See the cmake options for upnp behavior desired:
ENABLE_UPNP Enable UPnP support (miniupnp required, default ON)
START_WITH_UPNP UPnP support turned on by default at runtime (default OFF)
```
ENABLE_UPNP Enable UPnP support (miniupnp required, default ON)
START_WITH_UPNP UPnP support turned on by default at runtime (default OFF)
```
## Security
......@@ -164,16 +166,16 @@ Hardening enables the following features:
To test that you have built PIE executable, install `scanelf`, part of `pax-utils`,
and use:
```bash
scanelf -e ./bitcoin
```
```bash
scanelf -e ./bitcoin
```
The output should contain:
```bash
TYPE
ET_DYN
```
```bash
TYPE
ET_DYN
```
* _Non-executable Stack_: If the stack is executable then trivial stack-based buffer
overflow exploits are possible if vulnerable buffers are found. By default, Bitcoin
......@@ -184,16 +186,16 @@ Hardening enables the following features:
To verify that the stack is non-executable after compiling use:
```bash
scanelf -e ./bitcoin
```
```bash
scanelf -e ./bitcoin
```
The output should contain:
```
STK/REL/PTL
RW- R-- RW-
```
```
STK/REL/PTL
RW- R-- RW-
```
The `STK RW-` means that the stack is readable and writeable but not executable.
......@@ -544,16 +544,16 @@ pay attention to for reviewers of Bitcoin Cash Node code.
- Initialize all non-static class members where they are defined
```cpp
class A
{
uint32_t m_count{0};
}
```
- *Rationale*: Initializing the members in the declaration makes it easy to
spot uninitialized ones, and avoids accidentally reading uninitialized memory
```cpp
class A
{
uint32_t m_count{0};
}
```
### Strings and formatting
- Use `std::string`, avoid C string manipulation functions
......@@ -603,23 +603,23 @@ source code.
the current scope, so surround the statement and the code that needs the lock
with braces
OK:
OK:
```c++
{
TRY_LOCK(cs_vNodes, lockNodes);
...
}
```
```c++
{
TRY_LOCK(cs_vNodes, lockNodes);
...
}
```
Wrong:
Wrong:
```c++
TRY_LOCK(cs_vNodes, lockNodes);
{
...
}
```
```c++
TRY_LOCK(cs_vNodes, lockNodes);
{
...
}
```
### Scripts
......@@ -630,14 +630,16 @@ TRY_LOCK(cs_vNodes, lockNodes);
`#!/bin/bash` assumes it is always installed to /bin/ which can cause issues;
`#!/usr/bin/env bash` searches the user's PATH to find the bash binary.
OK:
```bash
#!/usr/bin/env bash
```
Wrong:
```bash
#!/bin/bash
```
OK:
```bash
#!/usr/bin/env bash
```
Wrong:
```bash
#!/bin/bash
```
### Source code organization
......@@ -663,15 +665,15 @@ TRY_LOCK(cs_vNodes, lockNodes);
- Terminate namespaces with a comment (`// namespace mynamespace`). The comment
should be placed on the same line as the brace closing the namespace, e.g.
```c++
namespace mynamespace {
...
} // namespace mynamespace
```c++
namespace mynamespace {
...
} // namespace mynamespace
namespace {
...
} // namespace
```
namespace {
...
} // namespace
```
- *Rationale*: Avoids confusion about the namespace context
......@@ -699,12 +701,12 @@ All headers should be lexically ordered inside their block.
- Use include guards to avoid the problem of double inclusion. The header file
`foo/bar.h` should use the include guard identifier `BITCOIN_FOO_BAR_H`, e.g.
```c++
#ifndef BITCOIN_FOO_BAR_H
#define BITCOIN_FOO_BAR_H
...
#endif // BITCOIN_FOO_BAR_H
```
```c++
#ifndef BITCOIN_FOO_BAR_H
#define BITCOIN_FOO_BAR_H
...
#endif // BITCOIN_FOO_BAR_H
```
### GUI
......@@ -828,23 +830,27 @@ Git and GitLab tips
- For resolving merge/rebase conflicts, it can be useful to enable diff3 style using
`git config merge.conflictstyle diff3`. Instead of
<<<
yours
===
theirs
>>>
you will see
<<<
yours
|||
original
===
theirs
>>>
This may make it much clearer what caused the conflict. In this style, you can
```
<<<
yours
===
theirs
>>>
```
you will see
```
<<<
yours
|||
original
===
theirs
>>>
```
This may make it much clearer what caused the conflict. In this style, you can
often just look at what changed between *original* and *theirs*, and mechanically
apply that to *yours* (or the other way around).
......@@ -866,9 +872,11 @@ Git and GitLab tips
- When looking at other's pull requests, it may make sense to add the following
section to your `.git/config` file:
[remote "upstream-merges"]
url = git@gitlab.com:bitcoin-cash-node/bitcoin-cash-node.git
fetch = +refs/merge-requests/*/head:refs/remotes/upstream-merges/merge-requests/*
```
[remote "upstream-merges"]
url = git@gitlab.com:bitcoin-cash-node/bitcoin-cash-node.git
fetch = +refs/merge-requests/*/head:refs/remotes/upstream-merges/merge-requests/*
```
This will add an `upstream-merges` remote to your git repository, which can be
fetched using `git fetch --all` or `git fetch upstream-merges`. Afterwards, you
......
......@@ -125,20 +125,20 @@ To select a different button, press `Tab`.
- Disk setup
- Partitioning method: Guided - Use the entire disk
![](figs/debian_install_11_partition_disks.png)
![](figs/debian_install_11_partition_disks.png)
- Select disk to partition: SCSI1 (0,0,0)
![](figs/debian_install_12_choose_disk.png)
![](figs/debian_install_12_choose_disk.png)
- Partition Disks -> *All files in one partition*
![](figs/all_files_in_one_partition.png)
![](figs/all_files_in_one_partition.png)
- Finish partitioning and write changes to disk -> *Yes* (`Tab`, `Enter` to select the `Yes` button)
![](figs/debian_install_14_finish.png)
![](figs/debian_install_15_write_changes.png)
![](figs/debian_install_14_finish.png)
![](figs/debian_install_15_write_changes.png)
- The base system will be installed, this will take a minute or so
- Scan another CD or DVD? -> *No*
......@@ -180,20 +180,22 @@ On Windows you can use [putty](https://www.chiark.greenend.org.uk/~sgtatham/putt
For example, to connect as `gitianuser` from a Linux command prompt use
$ ssh gitianuser@localhost -p 22222
The authenticity of host '[localhost]:22222 ([127.0.0.1]:22222)' can't be established.
RSA key fingerprint is ae:f5:c8:9f:17:c6:c7:1b:c2:1b:12:31:1d:bb:d0:c7.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '[localhost]:22222' (RSA) to the list of known hosts.
gitianuser@localhost's password: (enter gitianuser password configured during install)
The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
gitianuser@debian:~$
```
$ ssh gitianuser@localhost -p 22222
The authenticity of host '[localhost]:22222 ([127.0.0.1]:22222)' can't be established.
RSA key fingerprint is ae:f5:c8:9f:17:c6:c7:1b:c2:1b:12:31:1d:bb:d0:c7.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '[localhost]:22222' (RSA) to the list of known hosts.
gitianuser@localhost's password: (enter gitianuser password configured during install)
The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
gitianuser@debian:~$
```
Use `sudo` to execute commands as root.
......
......@@ -28,27 +28,29 @@ tail -f var/build.log
Output from `gbuild` will look something like
Initialized empty Git repository in /home/gitianuser/gitian-builder/inputs/bitcoin/.git/
remote: Counting objects: 57959, done.
remote: Total 57959 (delta 0), reused 0 (delta 0), pack-reused 57958
Receiving objects: 100% (57959/57959), 53.76 MiB | 484.00 KiB/s, done.
Resolving deltas: 100% (41590/41590), done.
From https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node.git
... (new tags, new branch etc)
--- Building for trusty amd64 ---
Stopping target if it is up
Making a new image copy
stdin: is not a tty
Starting target
Checking if target is up
Preparing build environment
Updating apt-get repository (log in var/install.log)
Installing additional packages (log in var/install.log)
Grabbing package manifest
stdin: is not a tty
Creating build script (var/build-script)
lxc-start: Connection refused - inotify event with no name (mask 32768)
Running build script (log in var/build.log)
```
Initialized empty Git repository in /home/gitianuser/gitian-builder/inputs/bitcoin/.git/
remote: Counting objects: 57959, done.
remote: Total 57959 (delta 0), reused 0 (delta 0), pack-reused 57958
Receiving objects: 100% (57959/57959), 53.76 MiB | 484.00 KiB/s, done.
Resolving deltas: 100% (41590/41590), done.
From https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node.git
... (new tags, new branch etc)
--- Building for trusty amd64 ---
Stopping target if it is up
Making a new image copy
stdin: is not a tty
Starting target
Checking if target is up
Preparing build environment
Updating apt-get repository (log in var/install.log)
Installing additional packages (log in var/install.log)
Grabbing package manifest
stdin: is not a tty
Creating build script (var/build-script)
lxc-start: Connection refused - inotify event with no name (mask 32768)
Running build script (log in var/build.log)
```
Building an alternative repository
----------------------------------
......
......@@ -240,7 +240,9 @@ Builds and installs the project.
You can override the installation root (which defaults to /usr/local) by defining
the `CMAKE_INSTALL_PREFIX` when you configure your build, like this:
cmake -DCMAKE_INSTALL_PREFIX=${your_install_root_path} -GNinja ..
```
cmake -DCMAKE_INSTALL_PREFIX=${your_install_root_path} -GNinja ..
```
where you can use `$HOME` or `$(pwd)` (if you want to install into your build folder)
or whatever you prefer for `${your_install_root_path}`.
......
......@@ -42,11 +42,15 @@ that implement new `BOOST_AUTO_TEST_SUITE` sections.
`test_bitcoin` has some built-in command-line arguments; for
example, to run just the `getarg_tests` verbosely:
test_bitcoin --log_level=all --run_test=getarg_tests
```
test_bitcoin --log_level=all --run_test=getarg_tests
```
... or to run just the doubledash test:
test_bitcoin --run_test=getarg_tests/doubledash
```
test_bitcoin --run_test=getarg_tests/doubledash
```
Run `test_bitcoin --help` for the full list.
......@@ -69,6 +73,7 @@ explaining how the boost unit test framework works:
### Debugging unit tests
Simple example of debugging unit tests with GDB on Linux:
```
cd /build/src/test
gdb test_bitcoin
......@@ -80,6 +85,7 @@ c # continue
```
Simple example of debugging unit tests with LLDB (OSX or Linux):
```
cd /build/src/test
lldb -- test_bitcoin
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment