aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorRohaq <rohaq at dearinternet[dot]com>2019-05-12 05:16:26 +0100
committerRohaq <rohaq at dearinternet[dot]com>2019-05-12 05:16:26 +0100
commit1873af35bfe4f475cfc3c3af66015cd03c34b93b (patch)
tree434b2541637805a810f97ed42df3bd9b35e73df0 /README.md
parentUpdated Copyright notice (diff)
downloadmonero-1873af35bfe4f475cfc3c3af66015cd03c34b93b.tar.xz
Made code block usage consistent across all .md files
Diffstat (limited to 'README.md')
-rw-r--r--README.md268
1 files changed, 173 insertions, 95 deletions
diff --git a/README.md b/README.md
index e13c86934..1d46f1ac6 100644
--- a/README.md
+++ b/README.md
@@ -226,9 +226,11 @@ invokes cmake commands as needed.
* Install the dependencies
* Change to the root of the source code directory, change to the most recent release branch, and build:
- cd monero
- git checkout release-v0.14
- make
+ ```bash
+ cd monero
+ git checkout release-v0.14
+ make
+ ```
*Optional*: If your machine has several cores and enough memory, enable
parallel build by running `make -j<number of threads>` instead of `make`. For
@@ -252,23 +254,31 @@ invokes cmake commands as needed.
* **Optional**: build and run the test suite to verify the binaries:
- make release-test
+ ```bash
+ make release-test
+ ```
*NOTE*: `core_tests` test may take a few hours to complete.
* **Optional**: to build binaries suitable for debugging:
- make debug
+ ```bash
+ make debug
+ ```
* **Optional**: to build statically-linked binaries:
- make release-static
+ ```bash
+ make release-static
+ ```
Dependencies need to be built with -fPIC. Static libraries usually aren't, so you may have to build them yourself with -fPIC. Refer to their documentation for how to build them.
* **Optional**: build documentation in `doc/html` (omit `HAVE_DOT=YES` if `graphviz` is not installed):
- HAVE_DOT=YES doxygen Doxyfile
+ ```bash
+ HAVE_DOT=YES doxygen Doxyfile
+ ```
#### On the Raspberry Pi
@@ -279,24 +289,30 @@ Tested on a Raspberry Pi Zero with a clean install of minimal Raspbian Stretch (
* Install the dependencies for Monero from the 'Debian' column in the table above.
* Increase the system swap size:
-```
- sudo /etc/init.d/dphys-swapfile stop
- sudo nano /etc/dphys-swapfile
- CONF_SWAPSIZE=2048
- sudo /etc/init.d/dphys-swapfile start
-```
+
+ ```bash
+ sudo /etc/init.d/dphys-swapfile stop
+ sudo nano /etc/dphys-swapfile
+ CONF_SWAPSIZE=2048
+ sudo /etc/init.d/dphys-swapfile start
+ ```
+
* If using an external hard disk without an external power supply, ensure it gets enough power to avoid hardware issues when syncing, by adding the line "max_usb_current=1" to /boot/config.txt
* Clone monero and checkout the most recent release version:
-```
- git clone https://github.com/monero-project/monero.git
- cd monero
- git checkout tags/v0.14.1.0
-```
+
+ ```bash
+ git clone https://github.com/monero-project/monero.git
+ cd monero
+ git checkout tags/v0.14.1.0
+ ```
+
* Build:
-```
- make release
-```
+
+ ```bash
+ make release
+ ```
+
* Wait 4-6 hours
* The resulting executables can be found in `build/release/bin`
@@ -313,28 +329,33 @@ If you are using the older Raspbian Jessie image, compiling Monero is a bit more
* As before, `apt-get update && apt-get upgrade` to install all of the latest software, and increase the system swap size
-```
- sudo /etc/init.d/dphys-swapfile stop
- sudo nano /etc/dphys-swapfile
- CONF_SWAPSIZE=2048
- sudo /etc/init.d/dphys-swapfile start
-```
+ ```bash
+ sudo /etc/init.d/dphys-swapfile stop
+ sudo nano /etc/dphys-swapfile
+ CONF_SWAPSIZE=2048
+ sudo /etc/init.d/dphys-swapfile start
+ ```
+
* Then, install the dependencies for Monero except `libunwind` and `libboost-all-dev`
* Install the latest version of boost (this may first require invoking `apt-get remove --purge libboost*` to remove a previous version if you're not using a clean install):
-```
- cd
- wget https://sourceforge.net/projects/boost/files/boost/1.64.0/boost_1_64_0.tar.bz2
- tar xvfo boost_1_64_0.tar.bz2
- cd boost_1_64_0
- ./bootstrap.sh
- sudo ./b2
-```
+
+ ```bash
+ cd
+ wget https://sourceforge.net/projects/boost/files/boost/1.64.0/boost_1_64_0.tar.bz2
+ tar xvfo boost_1_64_0.tar.bz2
+ cd boost_1_64_0
+ ./bootstrap.sh
+ sudo ./b2
+ ```
+
* Wait ~8 hours
-```
- sudo ./bjam cxxflags=-fPIC cflags=-fPIC -a install
-```
+
+ ```bash
+ sudo ./bjam cxxflags=-fPIC cflags=-fPIC -a install
+ ```
+
* Wait ~4 hours
* From here, follow the [general Raspberry Pi instructions](#on-the-raspberry-pi) from the "Clone monero and checkout most recent release version" step.
@@ -353,24 +374,32 @@ application.
* Open the MSYS shell via the `MSYS2 Shell` shortcut
* Update packages using pacman:
- pacman -Syu
+ ```bash
+ pacman -Syu
+ ```
* Exit the MSYS shell using Alt+F4
* Edit the properties for the `MSYS2 Shell` shortcut changing "msys2_shell.bat" to "msys2_shell.cmd -mingw64" for 64-bit builds or "msys2_shell.cmd -mingw32" for 32-bit builds
* Restart MSYS shell via modified shortcut and update packages again using pacman:
- pacman -Syu
+ ```bash
+ pacman -Syu
+ ```
* Install dependencies:
To build for 64-bit Windows:
- pacman -S mingw-w64-x86_64-toolchain make mingw-w64-x86_64-cmake mingw-w64-x86_64-boost mingw-w64-x86_64-openssl mingw-w64-x86_64-zeromq mingw-w64-x86_64-libsodium mingw-w64-x86_64-hidapi
+ ```bash
+ pacman -S mingw-w64-x86_64-toolchain make mingw-w64-x86_64-cmake mingw-w64-x86_64-boost mingw-w64-x86_64-openssl mingw-w64-x86_64-zeromq mingw-w64-x86_64-libsodium mingw-w64-x86_64-hidapi
+ ```
To build for 32-bit Windows:
- pacman -S mingw-w64-i686-toolchain make mingw-w64-i686-cmake mingw-w64-i686-boost mingw-w64-i686-openssl mingw-w64-i686-zeromq mingw-w64-i686-libsodium mingw-w64-i686-hidapi
+ ```bash
+ pacman -S mingw-w64-i686-toolchain make mingw-w64-i686-cmake mingw-w64-i686-boost mingw-w64-i686-openssl mingw-w64-i686-zeromq mingw-w64-i686-libsodium mingw-w64-i686-hidapi
+ ```
* Open the MingW shell via `MinGW-w64-Win64 Shell` shortcut on 64-bit Windows
or `MinGW-w64-Win64 Shell` shortcut on 32-bit Windows. Note that if you are
@@ -380,35 +409,49 @@ application.
* To git clone, run:
- git clone --recursive https://github.com/monero-project/monero.git
+ ```bash
+ git clone --recursive https://github.com/monero-project/monero.git
+ ```
**Building**
* Change to the cloned directory, run:
- cd monero
+ ```bash
+ cd monero
+ ```
* If you would like a specific [version/tag](https://github.com/monero-project/monero/tags), do a git checkout for that version. eg. 'v0.14.1.0'. If you don't care about the version and just want binaries from master, skip this step:
- git checkout v0.14.1.0
+ ```bash
+ git checkout v0.14.1.0
+ ```
* If you are on a 64-bit system, run:
- make release-static-win64
+ ```bash
+ make release-static-win64
+ ```
* If you are on a 32-bit system, run:
- make release-static-win32
+ ```bash
+ make release-static-win32
+ ```
* The resulting executables can be found in `build/release/bin`
* **Optional**: to build Windows binaries suitable for debugging on a 64-bit system, run:
- make debug-static-win64
+ ```bash
+ make debug-static-win64
+ ```
* **Optional**: to build Windows binaries suitable for debugging on a 32-bit system, run:
- make debug-static-win32
+ ```bash
+ make debug-static-win32
+ ```
* The resulting executables can be found in `build/debug/bin`
@@ -448,7 +491,7 @@ We assume you are compiling with a non-root user and you have `doas` enabled.
Note: do not use the boost package provided by OpenBSD, as we are installing boost to `/usr/local`.
-```
+```bash
# Create boost building directory
mkdir ~/boost
cd ~/boost
@@ -484,7 +527,7 @@ Build the cppzmq bindings.
We assume you are compiling with a non-root user and you have `doas` enabled.
-```
+```bash
# Create cppzmq building directory
mkdir ~/cppzmq
cd ~/cppzmq
@@ -504,7 +547,10 @@ cmake ..
doas make install
```
-Build monero: `env DEVELOPER_LOCAL_TOOLS=1 BOOST_ROOT=/usr/local make release-static`
+Build monero:
+```bash
+env DEVELOPER_LOCAL_TOOLS=1 BOOST_ROOT=/usr/local make release-static
+```
#### OpenBSD >= 6.4
@@ -527,23 +573,27 @@ Then you need to increase the data ulimit size to 2GB and try again: `ulimit -d
The default Solaris linker can't be used, you have to install GNU ld, then run cmake manually with the path to your copy of GNU ld:
- mkdir -p build/release
- cd build/release
- cmake -DCMAKE_LINKER=/path/to/ld -D CMAKE_BUILD_TYPE=Release ../..
- cd ../..
+```bash
+mkdir -p build/release
+cd build/release
+cmake -DCMAKE_LINKER=/path/to/ld -D CMAKE_BUILD_TYPE=Release ../..
+cd ../..
+```
Then you can run make as usual.
### On Linux for Android (using docker):
- # Build image (for ARM 32-bit)
- docker build -f utils/build_scripts/android32.Dockerfile -t monero-android .
- # Build image (for ARM 64-bit)
- docker build -f utils/build_scripts/android64.Dockerfile -t monero-android .
- # Create container
- docker create -it --name monero-android monero-android bash
- # Get binaries
- docker cp monero-android:/src/build/release/bin .
+```bash
+# Build image (for ARM 32-bit)
+docker build -f utils/build_scripts/android32.Dockerfile -t monero-android .
+# Build image (for ARM 64-bit)
+docker build -f utils/build_scripts/android64.Dockerfile -t monero-android .
+# Create container
+docker create -it --name monero-android monero-android bash
+# Get binaries
+docker cp monero-android:/src/build/release/bin .
+```
### Building portable statically linked binaries
@@ -562,12 +612,18 @@ By default, in either dynamically or statically linked builds, binaries target t
You can also cross-compile static binaries on Linux for Windows and macOS with the `depends` system.
* ```make depends target=x86_64-linux-gnu``` for 64-bit linux binaries.
-* ```make depends target=x86_64-w64-mingw32``` for 64-bit windows binaries. Requires: python3 g++-mingw-w64-x86-64 wine1.6 bc
-* ```make depends target=x86_64-apple-darwin11``` for macOS binaries. Requires: cmake imagemagick libcap-dev librsvg2-bin libz-dev libbz2-dev libtiff-tools python-dev
-* ```make depends target=i686-linux-gnu``` for 32-bit linux binaries. Requires: g++-multilib bc
-* ```make depends target=i686-w64-mingw32``` for 32-bit windows binaries. Requires: python3 g++-mingw-w64-i686
-* ```make depends target=arm-linux-gnueabihf``` for armv7 binaries. Requires: g++-arm-linux-gnueabihf
-* ```make depends target=aarch64-linux-gnu``` for armv8 binaries. Requires: g++-aarch64-linux-gnu
+* ```make depends target=x86_64-w64-mingw32``` for 64-bit windows binaries.
+ * Requires: `python3 g++-mingw-w64-x86-64 wine1.6 bc`
+* ```make depends target=x86_64-apple-darwin11``` for macOS binaries.
+ * Requires: `cmake imagemagick libcap-dev librsvg2-bin libz-dev libbz2-dev libtiff-tools python-dev`
+* ```make depends target=i686-linux-gnu``` for 32-bit linux binaries.
+ * Requires: `g++-multilib bc`
+* ```make depends target=i686-w64-mingw32``` for 32-bit windows binaries.
+ * Requires: `python3 g++-mingw-w64-i686`
+* ```make depends target=arm-linux-gnueabihf``` for armv7 binaries.
+ * Requires: `g++-arm-linux-gnueabihf`
+* ```make depends target=aarch64-linux-gnu``` for armv8 binaries.
+ * Requires: `g++-aarch64-linux-gnu`
The required packages are the names for each toolchain on apt. Depending on your distro, they may have different names.
@@ -583,7 +639,9 @@ Packages are available for
* Ubuntu and [snap supported](https://snapcraft.io/docs/core/install) systems, via a community contributed build.
- snap install monero --beta
+ ```bash
+ snap install monero --beta
+ ```
Installing a snap is very quick. Snaps are secure. They are isolated with all of their dependencies. Snaps also auto update when a new version is released.
@@ -593,25 +651,31 @@ Installing a snap is very quick. Snaps are secure. They are isolated with all of
* Void Linux:
- xbps-install -S monero
+ ```bash
+ xbps-install -S monero
+ ```
* GuixSD
- guix package -i monero
+ ```bash
+ guix package -i monero
+ ```
* Docker
- # Build using all available cores
- docker build -t monero .
-
- # or build using a specific number of cores (reduce RAM requirement)
- docker build --build-arg NPROC=1 -t monero .
-
- # either run in foreground
- docker run -it -v /monero/chain:/root/.bitmonero -v /monero/wallet:/wallet -p 18080:18080 monero
-
- # or in background
- docker run -it -d -v /monero/chain:/root/.bitmonero -v /monero/wallet:/wallet -p 18080:18080 monero
+ ```bash
+ # Build using all available cores
+ docker build -t monero .
+
+ # or build using a specific number of cores (reduce RAM requirement)
+ docker build --build-arg NPROC=1 -t monero .
+
+ # either run in foreground
+ docker run -it -v /monero/chain:/root/.bitmonero -v /monero/wallet:/wallet -p 18080:18080 monero
+
+ # or in background
+ docker run -it -d -v /monero/chain:/root/.bitmonero -v /monero/wallet:/wallet -p 18080:18080 monero
+ ```
* The build needs 3 GB space.
* Wait one hour or more
@@ -624,7 +688,9 @@ The build places the binary in `bin/` sub-directory within the build directory
from which cmake was invoked (repository root by default). To run in
foreground:
- ./bin/monerod
+```bash
+./bin/monerod
+```
To list all available options, run `./bin/monerod --help`. Options can be
specified either on the command line or in a configuration file passed by the
@@ -634,7 +700,9 @@ of the argument without the leading dashes, for example `log-level=1`.
To run in background:
- ./bin/monerod --log-file monerod.log --detach
+```bash
+./bin/monerod --log-file monerod.log --detach
+```
To run as a systemd service, copy
[monerod.service](utils/systemd/monerod.service) to `/etc/systemd/system/` and
@@ -682,7 +750,9 @@ setting the following configuration parameters and environment variables:
Example command line to start monerod through Tor:
- DNS_PUBLIC=tcp torsocks monerod --p2p-bind-ip 127.0.0.1 --no-igd
+```bash
+DNS_PUBLIC=tcp torsocks monerod --p2p-bind-ip 127.0.0.1 --no-igd
+```
### Using Tor on Tails
@@ -690,9 +760,11 @@ TAILS ships with a very restrictive set of firewall rules. Therefore, you need
to add a rule to allow this connection too, in addition to telling torsocks to
allow inbound connections. Full example:
- sudo iptables -I OUTPUT 2 -p tcp -d 127.0.0.1 -m tcp --dport 18081 -j ACCEPT
- DNS_PUBLIC=tcp torsocks ./monerod --p2p-bind-ip 127.0.0.1 --no-igd --rpc-bind-ip 127.0.0.1 \
- --data-dir /home/amnesia/Persistent/your/directory/to/the/blockchain
+```bash
+sudo iptables -I OUTPUT 2 -p tcp -d 127.0.0.1 -m tcp --dport 18081 -j ACCEPT
+DNS_PUBLIC=tcp torsocks ./monerod --p2p-bind-ip 127.0.0.1 --no-igd --rpc-bind-ip 127.0.0.1 \
+ --data-dir /home/amnesia/Persistent/your/directory/to/the/blockchain
+```
## Debugging
@@ -702,13 +774,13 @@ This section contains general instructions for debugging failed installs or prob
We generally use the tool `gdb` (GNU debugger) to provide stack trace functionality, and `ulimit` to provide core dumps in builds which crash or segfault.
-* To use gdb in order to obtain a stack trace for a build that has stalled:
+* To use `gdb` in order to obtain a stack trace for a build that has stalled:
Run the build.
Once it stalls, enter the following command:
-```
+```bash
gdb /path/to/monerod `pidof monerod`
```
@@ -726,7 +798,9 @@ When it terminates with an output along the lines of "Segmentation fault (core d
You can now analyse this core dump with `gdb` as follows:
-`gdb /path/to/monerod /path/to/dumpfile`
+```bash
+gdb /path/to/monerod /path/to/dumpfile`
+```
Print the stack trace with `bt`
@@ -746,7 +820,9 @@ There are two tools available:
Configure Monero with the -D SANITIZE=ON cmake flag, eg:
- cd build/debug && cmake -D SANITIZE=ON -D CMAKE_BUILD_TYPE=Debug ../..
+```bash
+cd build/debug && cmake -D SANITIZE=ON -D CMAKE_BUILD_TYPE=Debug ../..
+```
You can then run the monero tools normally. Performance will typically halve.
@@ -760,7 +836,9 @@ Instructions for debugging suspected blockchain corruption as per @HYC
There is an `mdb_stat` command in the LMDB source that can print statistics about the database but it's not routinely built. This can be built with the following command:
-`cd ~/monero/external/db_drivers/liblmdb && make`
+```bash
+cd ~/monero/external/db_drivers/liblmdb && make
+```
The output of `mdb_stat -ea <path to blockchain dir>` will indicate inconsistencies in the blocks, block_heights and block_info table.