Skip to content

Commit 90cef2f

Browse files
pmienkpmienk
committed
Update README.
1 parent c69fae5 commit 90cef2f

File tree

1 file changed

+231
-11
lines changed

1 file changed

+231
-11
lines changed

‎README.md‎

Lines changed: 231 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,241 @@
1-
[![Build Status](https://travis-ci.org/libbitcoin/libbitcoin-node.svg?branch=master)](https://travis-ci.org/libbitcoin/libbitcoin-node)
1+
[![Build Status](https://github.com/libbitcoin/libbitcoin-node/actions/workflows/ci.yml/badge.svg?branch=version3)](https://github.com/libbitcoin/libbitcoin-node/actions/workflows/ci.yml)
22

3-
[![Coverage Status](https://coveralls.io/repos/libbitcoin/libbitcoin-node/badge.svg)](https://coveralls.io/r/libbitcoin/libbitcoin-node)
3+
[![Coverage Status](https://coveralls.io/repos/libbitcoin/libbitcoin-node/badge.svg?branch=version3)](https://coveralls.io/r/libbitcoin/libbitcoin-node?branch=version3)
44

55
# Libbitcoin Node
66

7-
*Bitcoin full node based on libbitcoin-blockchain*
7+
*The Bitcoin full node based on libbitcoin-blockchain*
88

9-
Make sure you have installed [libbitcoin-blockchain](https://github.com/libbitcoin/libbitcoin-blockchain) and [libbitcoin-network](https://github.com/libbitcoin/libbitcoin-network) beforehand according to their build instructions.
9+
**License Overview**
1010

11+
All files in this repository fall under the license specified in [COPYING](COPYING). The project is licensed as [AGPL with a lesser clause](https://wiki.unsystem.net/en/index.php/Libbitcoin/License). It may be used within a proprietary project, but the core library and any changes to it must be published online. Source code for this library must always remain free for everybody to access.
12+
13+
**About Libbitcoin**
14+
15+
The libbitcoin toolkit is a set of cross platform C++ libraries for building bitcoin applications. The toolkit consists of several libraries, most of which depend on the foundational [libbitcoin-system](https://github.com/libbitcoin/libbitcoin-system) library. Each library's repository can be cloned and built using common [automake](http://www.gnu.org/software/automake) 1.14+ instructions or [cmake](https://cmake.org) 3.5+ instructions. There are no packages yet in distribution however each library includes an installation script (described below) which is regularly verified via [github actions](https://github.com/features/actions).
16+
17+
## Installation
18+
19+
On Linux and macOS libbitcoin-node can be build using Autotools and cmake. This process is accomplished via the provided installation scripts `install.sh` or `install-cmake.sh`. These scripts provide a basis for installation of the dependencies of the project. Both support the use of the argument `--help` for further parameterization.
20+
21+
Installation of libbitcoin-node comes with requirements listed below.
22+
23+
* C++11 compiler, currently minimum [GCC 4.8.0](https://gcc.gnu.org/projects/cxx0x.html) or Clang based on [LLVM 3.5](http://llvm.org/releases/3.5.0/docs/ReleaseNotes.html)
24+
* [Autoconf](https://www.gnu.org/software/autoconf/)
25+
* [Automake](https://www.gnu.org/software/automake/) 1.14+
26+
* [libtool](https://www.gnu.org/software/libtool/)
27+
* [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)
28+
* [git](https://git-scm.com/)
29+
* [wget](https://www.gnu.org/software/wget/)
30+
31+
Use of `install-cmake.sh` additionally requires [cmake](https://cmake.org) 3.5+.
32+
33+
A minimal libbitcoin-node build requires boost 1.72.0 to 1.76.0 and libsecp256k1. The [libbitcoin/secp256k1](https://github.com/libbitcoin/secp256k1/tree/version7) repository is forked from [bitcoin-core/secp256k1](https://github.com/bitcoin-core/secp256k1) in order to control for changes and to incorporate the necessary Visual Studio build. The original repository can be used directly but recent changes to the public interface may cause build breaks. The `--enable-module-recovery` switch is required. Both of these are able to be provided via the installation script(s).
34+
35+
Detailed instructions are provided below.
36+
37+
* [Debian/Ubuntu](#debianubuntu)
38+
* [Macintosh](#macintosh)
39+
* [Install Script Execution](#install-script-execution)
40+
* [Windows](#windows)
41+
42+
### Debian/Ubuntu
43+
44+
Below is a breakdown of preparation required to install libbitcoin-node. Once an appropriate [compiler](http://en.wikipedia.org/wiki/Compiler) and [build system](http://wikipedia.org/wiki/GNU_build_system) are in place, proceed to [Install Script Execution](#installscript) below to perform installation.
45+
46+
#### Compiler
47+
48+
The current minimum verified compilers for this project are [gcc](https://en.wikipedia.org/wiki/GNU_Compiler_Collection) 9.4.0 and [clang](https://en.wikipedia.org/wiki/Clang) 11.0.0.
49+
50+
To see your GCC version:
51+
```sh
52+
$ g++ --version
53+
```
54+
```
55+
g++ (Ubuntu 9.4.0-1ubuntu1~20.04.1) 9.4.0
56+
Copyright (C) 2019 Free Software Foundation, Inc.
57+
This is free software; see the source for copying conditions. There is NO
58+
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
59+
```
60+
If necessary, upgrade your GCC compiler as follows:
61+
```sh
62+
$ sudo apt install g++-9
63+
$ sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-9.4 50
64+
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9.4 50
65+
$ sudo update-alternatives --install /usr/bin/gcov gcov /usr/bin/gcov-9.4 50
66+
```
67+
68+
To see your clang version:
69+
```sh
70+
$ clang++ --version
71+
```
72+
```
73+
Ubuntu clang version 11.0.0-2~ubuntu20.04.1
74+
Target: x86_64-pc-linux-gnu
75+
Thread model: posix
76+
InstalledDir: /usr/bin
77+
```
78+
If necessary, upgrade your clang compiler as follows:
79+
```sh
80+
$ sudo apt install clang-11
81+
$ sudo update-alternatives --install /usr/bin/clang++ /usr/bin/clang++-11 50
82+
$ sudo update-alternatives --install /usr/bin/clang /usr/bin/clang-11 50
83+
```
84+
85+
#### Build System
86+
87+
Next install the [build system](http://wikipedia.org/wiki/GNU_build_system) (Automake minimum 1.14) and git:
88+
```sh
89+
$ sudo apt install build-essential autoconf automake libtool pkg-config git
90+
```
91+
92+
#### Boost (Not Recommended)
93+
94+
Next install the [Boost](http://www.boost.org) (1.72.0 - 1.76.0) development package. This can be accomplished via parameterization of the installation script during libbitcoin-node installation and it is recommended to the reader that this approach be used.
95+
96+
Due to the current state of packaging, boost is not provided by the standard packaging system at the required minimum version. This requires either manual source compilation (as is controlled within the installation scripts) or trusting a 3rd party [Personal Package Archive](https://launchpad.net/ubuntu/+ppas). Verification of the build is done against the sources (required for proper use of ICU).
97+
98+
A user may find [Martin Hierholzer's PPA](https://launchpad.net/~mhier/+archive/ubuntu/libboost-latest) useful. This is left for the adventurous reader.
99+
100+
### Macintosh
101+
102+
The macOS preparation differs from Linux the supported compiler and manner of dependency installation.
103+
104+
#### Compiler
105+
106+
Libbitcoin compiles with [clang](https://clang.llvm.org) on macOS and requires C++11 support. Installation has been verified using Clang based on [LLVM 14](http://llvm.org/t/llvm-14-0-6-release). This version or newer should be installed as part of the Xcode command line tools.
107+
108+
To see your Clang/LLVM version:
109+
```sh
110+
$ clang++ --version
111+
```
112+
You may encounter a prompt to install the Xcode command line developer tools, in which case accept the prompt.
113+
```
114+
Apple LLVM version 6.0 (clang-600.0.54) (based on LLVM 3.5svn)
115+
Target: x86_64-apple-darwin14.0.0
116+
Thread model: posix
117+
```
118+
If required update your version of the command line tools as follows:
11119
```sh
12-
$ ./autogen.sh
13-
$ ./configure
14-
$ make
15-
$ sudo make install
16-
$ sudo ldconfig
120+
$ xcode-select --install
17121
```
18122

19-
libbitcoin-node is now installed in `/usr/local/`.
123+
#### Build System
124+
125+
Libbitcoin supports both [Homebrew](http://brew.sh) and [MacPorts](https://www.macports.org) package managers. Both require Apple's [Xcode](https://developer.apple.com/xcode) command line tools. Neither requires Xcode as the tools may be installed independently.
126+
127+
##### Using Homebrew
128+
129+
First install [Homebrew](https://brew.sh).
130+
131+
Next install the [build system](http://wikipedia.org/wiki/GNU_build_system) (Automake minimum 1.14) and [wget](http://www.gnu.org/software/wget):
132+
```sh
133+
$ brew install autoconf automake libtool pkgconfig wget
134+
```
135+
136+
##### Using MacPorts
137+
138+
First install [MacPorts](https://www.macports.org/install.php).
139+
140+
Next install the [build system](http://wikipedia.org/wiki/GNU_build_system) (Automake minimum 1.14) and [wget](http://www.gnu.org/software/wget):
141+
```sh
142+
$ sudo port install autoconf automake libtool pkgconfig wget
143+
```
144+
145+
#### Boost (Not Recommended)
146+
147+
As above, it has been noted that the installation scripts can control the installation of boost from sources. This is desirable due to package system support changes. Installation from Homebrew or MacPorts may be accomplished, however significant parameterization may be required due to version requirements. This is left to the adventerous reader.
148+
149+
### Install Script Execution
150+
151+
The [autotools install script](https://github.com/libbitcoin/libbitcoin-node/blob/version3/install.sh) and [cmake install script](https://github.com/libbitcoin/libbitcoin-node/blob/version3/install-cmake.sh) are written so that the manual build steps for each dependency can be inferred by a developer.
152+
153+
You can run either install script from any directory on your system. By default this will build libbitcoin-node in a subdirectory named `build-libbitcoin-node` and install it to `/usr/local/`. The install script requires `sudo` only if you do not have access to the installation location, which you can change using the `--prefix` option on the installer command line.
154+
155+
The build script clones, builds and installs seven unpackaged repositories, namely:
156+
157+
- [libbitcoin/secp256k1](https://github.com/libbitcoin/secp256k1)
158+
- [libbitcoin/libbitcoin-system](https://github.com/libbitcoin/libbitcoin-system)
159+
- [libbitcoin/libbitcoin-database](https://github.com/libbitcoin/libbitcoin-database)
160+
- [libbitcoin/libbitcoin-consensus](https://github.com/libbitcoin/libbitcoin-consensus)
161+
- [libbitcoin/libbitcoin-blockchain](https://github.com/libbitcoin/libbitcoin-blockchain)
162+
- [libbitcoin/libbitcoin-network](https://github.com/libbitcoin/libbitcoin-network)
163+
- [libbitcoin/libbitcoin-node](https://github.com/libbitcoin/libbitcoin-node)
164+
165+
The script builds from the head of their `version7` and `version3` branches respectively. The `master` branch is a staging area for changes. The version branches are considered release quality.
166+
167+
The below provides examples for install script execution. The use of `./install.sh` may be substituted with `./install-cmake.sh` in order to use cmake tools to build the libbitcoin repositories. It should be noted that autotools is still required for [libbitcoin/secp256k1](https://github.com/libbitcoin/secp256k1) and most other install script managed dependencies.
168+
169+
#### Build Options
170+
171+
Any set of `./configure` options can be passed via the build script, for example:
172+
```sh
173+
$ CFLAGS="-Og -g" ./install.sh --prefix=/home/me/myprefix
174+
```
175+
176+
#### Compiling with ICU (International Components for Unicode)
177+
178+
Since the addition of [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and later [BIP-38](https://github.com/bitcoin/bips/blob/master/bip-0038.mediawiki) support, libbitcoin conditionally incorporates [ICU](http://site.icu-project.org). To use the BIP-38 and BIP-39 passphrase normalization features libbitcoin must be compiled with the `--with-icu` option. Currently [libbitcoin-explorer](https://github.com/libbitcoin/libbitcoin-explorer) is the only library that accesses this feature, so if you do not intend to use passphrase normalization this dependency can be avoided.
179+
```sh
180+
$ ./install.sh --with-icu
181+
```
182+
183+
#### Building ICU and/or Boost
184+
185+
The installer can download and install any or all of these dependencies. ICU is a large package that is not typically preinstalled at a sufficient level. Using these builds ensures compiler and configuration compatibility across all of the build components. It is recommended to use a prefix directory when building these components.
186+
```sh
187+
$ ./install.sh --with-icu --build-icu --build-boost --prefix=/home/me/myprefix
188+
```
189+
190+
### Windows
191+
192+
Visual Studio solutions are maintained for all libbitcoin libraries. NuGet packages exist for dependencies. ICU is integrated into Windows and therefore not required as an additional dependency when using ICU features.
193+
194+
> The libbitcoin execution environment supports `Windows XP Service Pack 2` and newer.
195+
196+
#### Supported Compilers
197+
198+
Libbitcoin requires a C++11 compiler, which means Visual Studio 2013 (with a pre-release compiler update) or later. Download and install one of the following free tools as necessary:
199+
200+
* [Visual Studio 2022 Community](https://www.visualstudio.com/downloads)
201+
202+
#### NuGet Repository
203+
204+
Dependencies apart from the libbitcoin libraries are available as [NuGet packages](https://www.nuget.org):
205+
206+
* Packages maintained by [sergey.shandar](http://www.nuget.org/profiles/sergey.shandar)
207+
* [boost](http://www.nuget.org/packages/boost)
208+
* [boost\_chrono-vc141](http://www.nuget.org/packages/boost_chrono-vc141)
209+
* [boost\_date\_time-vc141](http://www.nuget.org/packages/boost_date_time-vc141)
210+
* [boost\_filesystem-vc141](http://www.nuget.org/packages/boost_filesystem-vc141)
211+
* [boost\_iostreams-vc141](http://www.nuget.org/packages/boost_iostreams-vc141)
212+
* [boost\_locale-vc141](http://www.nuget.org/packages/boost_locale-vc141)
213+
* [boost\_log_setup-vc141](http://www.nuget.org/packages/boost_log_setup-vc141)
214+
* [boost\_log-vc141](http://www.nuget.org/packages/boost_log-vc141)
215+
* [boost\_program\_options-vc141](http://www.nuget.org/packages/boost_program_options-vc141)
216+
* [boost\_regex-vc141](http://www.nuget.org/packages/boost_regex-vc141)
217+
* [boost\_system-vc141](http://www.nuget.org/packages/boost_system-vc141)
218+
* [boost\_thread-vc141](http://www.nuget.org/packages/boost_thread-vc141)
219+
* [boost\_unit\_test\_framework-vc141](http://www.nuget.org/packages/boost_unit_test_framework-vc141)
220+
* Packages maintained by [evoskuil](http://www.nuget.org/profiles/evoskuil)
221+
* [secp256k1\_vc141](http://www.nuget.org/packages/secp256k1_vc141)
222+
223+
The packages can be viewed using the [NuGet package manager](http://docs.nuget.org/docs/start-here/managing-nuget-packages-using-the-dialog) from the libbitcoin solution. The package manager will prompt for download of any missing packages.
224+
225+
The libbitcoin solution files are configured with references to these packages. The location of the NuGet repository is controlled by the [nuget.config](https://github.com/libbitcoin/libbitcoin-node/blob/version3/builds/msvc/nuget.config) file `repositoryPath` setting **and** the `NuGetPackageRoot` element of **each** [\[project\].props](https://github.com/libbitcoin/libbitcoin-node/blob/version3/builds/msvc/vs2022/libbitcoin-node/libbitcoin-node.props) file.
226+
227+
#### Build Libbitcoin Projects
228+
229+
After cloning the the repository the libbitcoin build can be performed from within Visual Studio or using the `build_all.bat` script provided in the `builds\msvc\build\` subdirectory. The script automatically downloads all required NuGet packages.
230+
231+
> Tip: The `build_all.bat` script builds *all* valid configurations for *all* compilers. The build time can be significantly reduced by disabling all but the desired configuration in `build_base.bat` and `build_all.bat`.
232+
233+
The libbitcoin dynamic (DLL) build configurations do not compile, as the exports have not yet been fully implemented. These are currently disabled in the build scripts but you will encounter numerous errors if you build then manually.
234+
235+
#### Optional: Building secp256k1
236+
237+
The secp256k1 package above is maintained using the same [Visual Studio template](https://github.com/evoskuil/visual-studio-template) as all libbitcoin libraries. If so desired it can be built locally, in the same manner as libbitcoin.
238+
239+
* [libbitcoin/secp256k1/version7](https://github.com/libbitcoin/secp256k1/tree/version7/builds/msvc)
20240

21-
In version2 the `bitcoin-node` console app is for demonstration purposes only. See [libbitcoin-server](https://github.com/libbitcoin/libbitcoin-server) for release quality full node functionality.
241+
This change is properly accomplished by disabling the "NuGet Dependencies" in the Visual Studio properties user interface and then importing `secp256k1.import.props`, which references `secp256k1.import.xml`.

0 commit comments

Comments
 (0)