Merge pull request #5539

3f612cda Changed odd bullet point to low level header (Rohaq)
af9bc4ec Used subeaders to avoid slightly wonky looking formatting (Rohaq)
1873af35 Made code block usage consistent across all .md files (Rohaq)
68103075 Updated Copyright notice (Rohaq)
39bd157f Added Table of Contents to main README.md (Rohaq)
This commit is contained in:
Riccardo Spagni 2019-05-15 16:10:40 +02:00
commit e8487fa46b
No known key found for this signature in database
GPG key ID: 55432DF31CCD4FCD
8 changed files with 429 additions and 249 deletions

View file

@ -15,23 +15,33 @@ You do not need anything from Qt in order to use the final translations.
To update ts files after changing source code: To update ts files after changing source code:
./utils/translations/update-translations.sh ```bash
./utils/translations/update-translations.sh
```
To add a new language, eg Spanish (ISO code es): To add a new language, eg Spanish (ISO code es):
cp translations/monero.ts translations/monero_es.ts ```bash
cp translations/monero.ts translations/monero_es.ts
```
To edit translations for Spanish: To edit translations for Spanish:
linguist translations/monero_es.ts ```bash
linguist translations/monero_es.ts
```
To build translations after modifying them: To build translations after modifying them:
./utils/translations/build-translations.sh ```bash
./utils/translations/build-translations.sh
```
To test a translation: To test a translation:
LANG=es ./build/release/bin/monero-wallet-cli ```bash
LANG=es ./build/release/bin/monero-wallet-cli
```
To add new translatable strings in the source code: To add new translatable strings in the source code:
@ -39,6 +49,8 @@ Use the `tr(string)` function if possible. If the code is in a class, and this c
If you're getting messages of the form: If you're getting messages of the form:
Class 'cryptonote::simple_wallet' lacks Q_OBJECT macro ```
Class 'cryptonote::simple_wallet' lacks Q_OBJECT macro
```
all is fine, we don't actually need that here. all is fine, we don't actually need that here.

296
README.md
View file

@ -1,8 +1,28 @@
# Monero # Monero
Copyright (c) 2014-2018 The Monero Project. Copyright (c) 2014-2019 The Monero Project.
Portions Copyright (c) 2012-2013 The Cryptonote developers. Portions Copyright (c) 2012-2013 The Cryptonote developers.
## Table of Contents
- [Development resources](#development-resources)
- [Vulnerability response](#vulnerability-response)
- [Research](#research)
- [Announcements](#announcements)
- [Translations](#translations)
- [Build](#build)
- [IMPORTANT](#important)
- [Coverage](#coverage)
- [Introduction](#introduction)
- [About this project](#about-this-project)
- [Supporting the project](#supporting-the-project)
- [License](#license)
- [Contributing](#contributing)
- [Scheduled software upgrades](#scheduled-software-upgrades)
- [Release staging schedule and protocol](#release-staging-schedule-and-protocol)
- [Compiling Monero from source](#compiling-monero-from-source)
- [Dependencies](#dependencies)
## Development resources ## Development resources
- Web: [getmonero.org](https://getmonero.org) - Web: [getmonero.org](https://getmonero.org)
@ -206,9 +226,11 @@ invokes cmake commands as needed.
* Install the dependencies * Install the dependencies
* Change to the root of the source code directory, change to the most recent release branch, and build: * Change to the root of the source code directory, change to the most recent release branch, and build:
cd monero ```bash
git checkout release-v0.14 cd monero
make git checkout release-v0.14
make
```
*Optional*: If your machine has several cores and enough memory, enable *Optional*: If your machine has several cores and enough memory, enable
parallel build by running `make -j<number of threads>` instead of `make`. For parallel build by running `make -j<number of threads>` instead of `make`. For
@ -232,23 +254,31 @@ invokes cmake commands as needed.
* **Optional**: build and run the test suite to verify the binaries: * **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. *NOTE*: `core_tests` test may take a few hours to complete.
* **Optional**: to build binaries suitable for debugging: * **Optional**: to build binaries suitable for debugging:
make debug ```bash
make debug
```
* **Optional**: to build statically-linked binaries: * **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. 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): * **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 #### On the Raspberry Pi
@ -259,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. * Install the dependencies for Monero from the 'Debian' column in the table above.
* Increase the system swap size: * Increase the system swap size:
```
sudo /etc/init.d/dphys-swapfile stop ```bash
sudo nano /etc/dphys-swapfile sudo /etc/init.d/dphys-swapfile stop
CONF_SWAPSIZE=2048 sudo nano /etc/dphys-swapfile
sudo /etc/init.d/dphys-swapfile start 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 * 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: * Clone monero and checkout the most recent release version:
```
git clone https://github.com/monero-project/monero.git ```bash
cd monero git clone https://github.com/monero-project/monero.git
git checkout tags/v0.14.1.0 cd monero
``` git checkout tags/v0.14.1.0
```
* Build: * Build:
```
make release ```bash
``` make release
```
* Wait 4-6 hours * Wait 4-6 hours
* The resulting executables can be found in `build/release/bin` * The resulting executables can be found in `build/release/bin`
@ -293,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 * As before, `apt-get update && apt-get upgrade` to install all of the latest software, and increase the system swap size
``` ```bash
sudo /etc/init.d/dphys-swapfile stop sudo /etc/init.d/dphys-swapfile stop
sudo nano /etc/dphys-swapfile sudo nano /etc/dphys-swapfile
CONF_SWAPSIZE=2048 CONF_SWAPSIZE=2048
sudo /etc/init.d/dphys-swapfile start sudo /etc/init.d/dphys-swapfile start
``` ```
* Then, install the dependencies for Monero except `libunwind` and `libboost-all-dev` * 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): * 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 ```bash
wget https://sourceforge.net/projects/boost/files/boost/1.64.0/boost_1_64_0.tar.bz2 cd
tar xvfo boost_1_64_0.tar.bz2 wget https://sourceforge.net/projects/boost/files/boost/1.64.0/boost_1_64_0.tar.bz2
cd boost_1_64_0 tar xvfo boost_1_64_0.tar.bz2
./bootstrap.sh cd boost_1_64_0
sudo ./b2 ./bootstrap.sh
``` sudo ./b2
```
* Wait ~8 hours * Wait ~8 hours
```
sudo ./bjam cxxflags=-fPIC cflags=-fPIC -a install ```bash
``` sudo ./bjam cxxflags=-fPIC cflags=-fPIC -a install
```
* Wait ~4 hours * 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. * From here, follow the [general Raspberry Pi instructions](#on-the-raspberry-pi) from the "Clone monero and checkout most recent release version" step.
@ -333,24 +374,32 @@ application.
* Open the MSYS shell via the `MSYS2 Shell` shortcut * Open the MSYS shell via the `MSYS2 Shell` shortcut
* Update packages using pacman: * Update packages using pacman:
pacman -Syu ```bash
pacman -Syu
```
* Exit the MSYS shell using Alt+F4 * 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 * 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: * Restart MSYS shell via modified shortcut and update packages again using pacman:
pacman -Syu ```bash
pacman -Syu
```
* Install dependencies: * Install dependencies:
To build for 64-bit Windows: 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: 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 * 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 or `MinGW-w64-Win64 Shell` shortcut on 32-bit Windows. Note that if you are
@ -360,35 +409,49 @@ application.
* To git clone, run: * 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** **Building**
* Change to the cloned directory, run: * 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: * 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: * 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: * 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` * The resulting executables can be found in `build/release/bin`
* **Optional**: to build Windows binaries suitable for debugging on a 64-bit system, run: * **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: * **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` * The resulting executables can be found in `build/debug/bin`
@ -428,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`. Note: do not use the boost package provided by OpenBSD, as we are installing boost to `/usr/local`.
``` ```bash
# Create boost building directory # Create boost building directory
mkdir ~/boost mkdir ~/boost
cd ~/boost cd ~/boost
@ -464,7 +527,7 @@ Build the cppzmq bindings.
We assume you are compiling with a non-root user and you have `doas` enabled. We assume you are compiling with a non-root user and you have `doas` enabled.
``` ```bash
# Create cppzmq building directory # Create cppzmq building directory
mkdir ~/cppzmq mkdir ~/cppzmq
cd ~/cppzmq cd ~/cppzmq
@ -484,7 +547,10 @@ cmake ..
doas make install 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 #### OpenBSD >= 6.4
@ -507,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: 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 ```bash
cd build/release mkdir -p build/release
cmake -DCMAKE_LINKER=/path/to/ld -D CMAKE_BUILD_TYPE=Release ../.. cd build/release
cd ../.. cmake -DCMAKE_LINKER=/path/to/ld -D CMAKE_BUILD_TYPE=Release ../..
cd ../..
```
Then you can run make as usual. Then you can run make as usual.
### On Linux for Android (using docker): ### On Linux for Android (using docker):
# Build image (for ARM 32-bit) ```bash
docker build -f utils/build_scripts/android32.Dockerfile -t monero-android . # Build image (for ARM 32-bit)
# Build image (for ARM 64-bit) docker build -f utils/build_scripts/android32.Dockerfile -t monero-android .
docker build -f utils/build_scripts/android64.Dockerfile -t monero-android . # Build image (for ARM 64-bit)
# Create container docker build -f utils/build_scripts/android64.Dockerfile -t monero-android .
docker create -it --name monero-android monero-android bash # Create container
# Get binaries docker create -it --name monero-android monero-android bash
docker cp monero-android:/src/build/release/bin . # Get binaries
docker cp monero-android:/src/build/release/bin .
```
### Building portable statically linked binaries ### Building portable statically linked binaries
@ -542,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. 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-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-w64-mingw32``` for 64-bit windows binaries.
* ```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 * Requires: `python3 g++-mingw-w64-x86-64 wine1.6 bc`
* ```make depends target=i686-linux-gnu``` for 32-bit linux binaries. Requires: g++-multilib bc * ```make depends target=x86_64-apple-darwin11``` for macOS binaries.
* ```make depends target=i686-w64-mingw32``` for 32-bit windows binaries. Requires: python3 g++-mingw-w64-i686 * Requires: `cmake imagemagick libcap-dev librsvg2-bin libz-dev libbz2-dev libtiff-tools python-dev`
* ```make depends target=arm-linux-gnueabihf``` for armv7 binaries. Requires: g++-arm-linux-gnueabihf * ```make depends target=i686-linux-gnu``` for 32-bit linux binaries.
* ```make depends target=aarch64-linux-gnu``` for armv8 binaries. Requires: g++-aarch64-linux-gnu * 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. The required packages are the names for each toolchain on apt. Depending on your distro, they may have different names.
@ -563,7 +639,9 @@ Packages are available for
* Ubuntu and [snap supported](https://snapcraft.io/docs/core/install) systems, via a community contributed build. * 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. 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.
@ -573,25 +651,31 @@ Installing a snap is very quick. Snaps are secure. They are isolated with all of
* Void Linux: * Void Linux:
xbps-install -S monero ```bash
xbps-install -S monero
```
* GuixSD * GuixSD
guix package -i monero ```bash
guix package -i monero
```
* Docker * Docker
# Build using all available cores ```bash
docker build -t monero . # 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 . # 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 # 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 # 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. * The build needs 3 GB space.
* Wait one hour or more * Wait one hour or more
@ -604,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 from which cmake was invoked (repository root by default). To run in
foreground: foreground:
./bin/monerod ```bash
./bin/monerod
```
To list all available options, run `./bin/monerod --help`. Options can be 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 specified either on the command line or in a configuration file passed by the
@ -614,7 +700,9 @@ of the argument without the leading dashes, for example `log-level=1`.
To run in background: 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 To run as a systemd service, copy
[monerod.service](utils/systemd/monerod.service) to `/etc/systemd/system/` and [monerod.service](utils/systemd/monerod.service) to `/etc/systemd/system/` and
@ -662,7 +750,9 @@ setting the following configuration parameters and environment variables:
Example command line to start monerod through Tor: 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 ### Using Tor on Tails
@ -670,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 to add a rule to allow this connection too, in addition to telling torsocks to
allow inbound connections. Full example: allow inbound connections. Full example:
sudo iptables -I OUTPUT 2 -p tcp -d 127.0.0.1 -m tcp --dport 18081 -j ACCEPT ```bash
DNS_PUBLIC=tcp torsocks ./monerod --p2p-bind-ip 127.0.0.1 --no-igd --rpc-bind-ip 127.0.0.1 \ sudo iptables -I OUTPUT 2 -p tcp -d 127.0.0.1 -m tcp --dport 18081 -j ACCEPT
--data-dir /home/amnesia/Persistent/your/directory/to/the/blockchain 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 ## Debugging
@ -682,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. 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. Run the build.
Once it stalls, enter the following command: Once it stalls, enter the following command:
``` ```bash
gdb /path/to/monerod `pidof monerod` gdb /path/to/monerod `pidof monerod`
``` ```
@ -706,11 +798,13 @@ 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: 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` Print the stack trace with `bt`
* To run monero within gdb: #### To run monero within gdb:
Type `gdb /path/to/monerod` Type `gdb /path/to/monerod`
@ -722,15 +816,17 @@ Type `run` to run monerod
There are two tools available: There are two tools available:
* ASAN #### ASAN
Configure Monero with the -D SANITIZE=ON cmake flag, eg: 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. You can then run the monero tools normally. Performance will typically halve.
* valgrind #### valgrind
Install valgrind and run as `valgrind /path/to/monerod`. It will be very slow. Install valgrind and run as `valgrind /path/to/monerod`. It will be very slow.
@ -740,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: 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. The output of `mdb_stat -ea <path to blockchain dir>` will indicate inconsistencies in the blocks, block_heights and block_info table.

View file

@ -2,21 +2,29 @@
To build dependencies for the current arch+OS: To build dependencies for the current arch+OS:
make ```bash
make
```
To build for another arch/OS: To build for another arch/OS:
make HOST=host-platform-triplet ```bash
make HOST=host-platform-triplet
```
For example: For example:
make HOST=x86_64-w64-mingw32 -j4 ```bash
make HOST=x86_64-w64-mingw32 -j4
```
A toolchain will be generated that's suitable for plugging into Monero's A toolchain will be generated that's suitable for plugging into Monero's
cmake. In the above example, a dir named x86_64-w64-mingw32 will be cmake. In the above example, a dir named x86_64-w64-mingw32 will be
created. To use it for Monero: created. To use it for Monero:
cmake -DCMAKE_TOOLCHAIN=`pwd`/contrib/depends/x86_64-w64-mingw32 ```bash
cmake -DCMAKE_TOOLCHAIN=`pwd`/contrib/depends/x86_64-w64-mingw32
```
Common `host-platform-triplets` for cross compilation are: Common `host-platform-triplets` for cross compilation are:
@ -31,20 +39,24 @@ No other options are needed, the paths are automatically configured.
Dependency Options: Dependency Options:
The following can be set when running make: make FOO=bar The following can be set when running make: make FOO=bar
SOURCES_PATH: downloaded sources will be placed here ```
BASE_CACHE: built packages will be placed here SOURCES_PATH: downloaded sources will be placed here
SDK_PATH: Path where sdk's can be found (used by OSX) BASE_CACHE: built packages will be placed here
FALLBACK_DOWNLOAD_PATH: If a source file can't be fetched, try here before giving up SDK_PATH: Path where sdk's can be found (used by OSX)
DEBUG: disable some optimizations and enable more runtime checking FALLBACK_DOWNLOAD_PATH: If a source file can't be fetched, try here before giving up
HOST_ID_SALT: Optional salt to use when generating host package ids DEBUG: disable some optimizations and enable more runtime checking
BUILD_ID_SALT: Optional salt to use when generating build package ids HOST_ID_SALT: Optional salt to use when generating host package ids
BUILD_ID_SALT: Optional salt to use when generating build package ids
```
Additional targets: Additional targets:
download: run 'make download' to fetch all sources without building them ```
download-osx: run 'make download-osx' to fetch all sources needed for osx builds download: run 'make download' to fetch all sources without building them
download-win: run 'make download-win' to fetch all sources needed for win builds download-osx: run 'make download-osx' to fetch all sources needed for osx builds
download-linux: run 'make download-linux' to fetch all sources needed for linux builds download-win: run 'make download-win' to fetch all sources needed for win builds
download-linux: run 'make download-linux' to fetch all sources needed for linux builds
```
#Darwin (macos) builds: #Darwin (macos) builds:

View file

@ -9,39 +9,43 @@ General tips:
## Identifiers ## Identifiers
Each package is required to define at least these variables: Each package is required to define at least these variables:
$(package)_version: ```
Version of the upstream library or program. If there is no version, a $(package)_version:
placeholder such as 1.0 can be used. Version of the upstream library or program. If there is no version, a
placeholder such as 1.0 can be used.
$(package)_download_path: $(package)_download_path:
Location of the upstream source, without the file-name. Usually http or Location of the upstream source, without the file-name. Usually http or
ftp. ftp.
$(package)_file_name: $(package)_file_name:
The upstream source filename available at the download path. The upstream source filename available at the download path.
$(package)_sha256_hash: $(package)_sha256_hash:
The sha256 hash of the upstream file The sha256 hash of the upstream file
```
These variables are optional: These variables are optional:
$(package)_build_subdir: ```
cd to this dir before running configure/build/stage commands. $(package)_build_subdir:
cd to this dir before running configure/build/stage commands.
$(package)_download_file:
The file-name of the upstream source if it differs from how it should be
stored locally. This can be used to avoid storing file-names with strange
characters.
$(package)_dependencies:
Names of any other packages that this one depends on.
$(package)_patches:
Filenames of any patches needed to build the package
$(package)_extra_sources: $(package)_download_file:
Any extra files that will be fetched via $(package)_fetch_cmds. These are The file-name of the upstream source if it differs from how it should be
specified so that they can be fetched and verified via 'make download'. stored locally. This can be used to avoid storing file-names with strange
characters.
$(package)_dependencies:
Names of any other packages that this one depends on.
$(package)_patches:
Filenames of any patches needed to build the package
$(package)_extra_sources:
Any extra files that will be fetched via $(package)_fetch_cmds. These are
specified so that they can be fetched and verified via 'make download'.
```
## Build Variables: ## Build Variables:
@ -49,47 +53,55 @@ After defining the main identifiers, build variables may be added or customized
before running the build commands. They should be added to a function called before running the build commands. They should be added to a function called
$(package)_set_vars. For example: $(package)_set_vars. For example:
define $(package)_set_vars ```
... define $(package)_set_vars
endef ...
endef
```
Most variables can be prefixed with the host, architecture, or both, to make Most variables can be prefixed with the host, architecture, or both, to make
the modifications specific to that case. For example: the modifications specific to that case. For example:
Universal: $(package)_cc=gcc ```
Linux only: $(package)_linux_cc=gcc Universal: $(package)_cc=gcc
x86_64 only: $(package)_x86_64_cc = gcc Linux only: $(package)_linux_cc=gcc
x86_64 linux only: $(package)_x86_64_linux_cc = gcc x86_64 only: $(package)_x86_64_cc = gcc
x86_64 linux only: $(package)_x86_64_linux_cc = gcc
```
These variables may be set to override or append their default values. These variables may be set to override or append their default values.
$(package)_cc ```
$(package)_cxx $(package)_cc
$(package)_objc $(package)_cxx
$(package)_objcxx $(package)_objc
$(package)_ar $(package)_objcxx
$(package)_ranlib $(package)_ar
$(package)_libtool $(package)_ranlib
$(package)_nm $(package)_libtool
$(package)_cflags $(package)_nm
$(package)_cxxflags $(package)_cflags
$(package)_ldflags $(package)_cxxflags
$(package)_cppflags $(package)_ldflags
$(package)_config_env $(package)_cppflags
$(package)_build_env $(package)_config_env
$(package)_stage_env $(package)_build_env
$(package)_build_opts $(package)_stage_env
$(package)_config_opts $(package)_build_opts
$(package)_config_opts
```
The *_env variables are used to add environment variables to the respective The `*_env` variables are used to add environment variables to the respective
commands. commands.
Many variables respect a debug/release suffix as well, in order to use them for Many variables respect a debug/release suffix as well, in order to use them for
only the appropriate build config. For example: only the appropriate build config. For example:
$(package)_cflags_release = -O3 ```
$(package)_cflags_i686_debug = -g $(package)_cflags_release = -O3
$(package)_config_opts_release = --disable-debug $(package)_cflags_i686_debug = -g
$(package)_config_opts_release = --disable-debug
```
These will be used in addition to the options that do not specify These will be used in addition to the options that do not specify
debug/release. All builds are considered to be release unless DEBUG=1 is set by debug/release. All builds are considered to be release unless DEBUG=1 is set by
@ -97,51 +109,57 @@ the user. Other variables may be defined as needed.
## Build commands: ## Build commands:
For each build, a unique build dir and staging dir are created. For example, For each build, a unique build dir and staging dir are created. For example,
`work/build/mylib/1.0-1adac830f6e` and `work/staging/mylib/1.0-1adac830f6e`. `work/build/mylib/1.0-1adac830f6e` and `work/staging/mylib/1.0-1adac830f6e`.
The following build commands are available for each recipe: The following build commands are available for each recipe:
$(package)_fetch_cmds: ```
Runs from: build dir $(package)_fetch_cmds:
Fetch the source file. If undefined, it will be fetched and verified Runs from: build dir
against its hash. Fetch the source file. If undefined, it will be fetched and verified
against its hash.
$(package)_extract_cmds: $(package)_extract_cmds:
Runs from: build dir Runs from: build dir
Verify the source file against its hash and extract it. If undefined, the Verify the source file against its hash and extract it. If undefined, the
source is assumed to be a tarball. source is assumed to be a tarball.
$(package)_preprocess_cmds: $(package)_preprocess_cmds:
Runs from: build dir/$(package)_build_subdir Runs from: build dir/$(package)_build_subdir
Preprocess the source as necessary. If undefined, does nothing. Preprocess the source as necessary. If undefined, does nothing.
$(package)_config_cmds: $(package)_config_cmds:
Runs from: build dir/$(package)_build_subdir Runs from: build dir/$(package)_build_subdir
Configure the source. If undefined, does nothing. Configure the source. If undefined, does nothing.
$(package)_build_cmds: $(package)_build_cmds:
Runs from: build dir/$(package)_build_subdir Runs from: build dir/$(package)_build_subdir
Build the source. If undefined, does nothing. Build the source. If undefined, does nothing.
$(package)_stage_cmds: $(package)_stage_cmds:
Runs from: build dir/$(package)_build_subdir Runs from: build dir/$(package)_build_subdir
Stage the build results. If undefined, does nothing. Stage the build results. If undefined, does nothing.
```
The following variables are available for each recipe: The following variables are available for each recipe:
$(1)_staging_dir: package's destination sysroot path ```
$(1)_staging_prefix_dir: prefix path inside of the package's staging dir $(1)_staging_dir: package's destination sysroot path
$(1)_extract_dir: path to the package's extracted sources $(1)_staging_prefix_dir: prefix path inside of the package's staging dir
$(1)_build_dir: path where configure/build/stage commands will be run $(1)_extract_dir: path to the package's extracted sources
$(1)_patch_dir: path where the package's patches (if any) are found $(1)_build_dir: path where configure/build/stage commands will be run
$(1)_patch_dir: path where the package's patches (if any) are found
```
Notes on build commands: Notes on build commands:
For packages built with autotools, $($(package)_autoconf) can be used in the For packages built with autotools, `$($(package)_autoconf)` can be used in the
configure step to (usually) correctly configure automatically. Any configure step to (usually) correctly configure automatically. Any
$($(package)_config_opts) will be appended. `$($(package)_config_opts`) will be appended.
Most autotools projects can be properly staged using: Most autotools projects can be properly staged using:
$(MAKE) DESTDIR=$($(package)_staging_dir) install ```bash
$(MAKE) DESTDIR=$($(package)_staging_dir) install
```

View file

@ -119,7 +119,7 @@ In order to sign gitian builds on your host machine, which has your PGP key,
fork the gitian.sigs repository and clone it on your host machine, fork the gitian.sigs repository and clone it on your host machine,
or pass the signed assert file back to your build machine. or pass the signed assert file back to your build machine.
``` ```bash
git clone git@github.com:monero-project/gitian.sigs.git git clone git@github.com:monero-project/gitian.sigs.git
git remote add fluffypony git@github.com:fluffypony/gitian.sigs.git git remote add fluffypony git@github.com:fluffypony/gitian.sigs.git
``` ```
@ -156,9 +156,9 @@ git push --set-upstream $NAME v0.14.0
``` ```
```bash ```bash
gpg --detach-sign ${VERSION}-linux/${SIGNER}/monero-linux-*-build.assert gpg --detach-sign ${VERSION}-linux/${SIGNER}/monero-linux-*-build.assert
gpg --detach-sign ${VERSION}-win-unsigned/${SIGNER}/monero-win-*-build.assert gpg --detach-sign ${VERSION}-win-unsigned/${SIGNER}/monero-win-*-build.assert
gpg --detach-sign ${VERSION}-osx-unsigned/${SIGNER}/monero-osx-*-build.assert gpg --detach-sign ${VERSION}-osx-unsigned/${SIGNER}/monero-osx-*-build.assert
``` ```
More Build Options More Build Options

View file

@ -79,7 +79,7 @@ LMDB flags (more than one may be specified):
## Examples: ## Examples:
``` ```bash
$ monero-blockchain-import --database lmdb#fastest $ monero-blockchain-import --database lmdb#fastest
$ monero-blockchain-import --database lmdb#nosync $ monero-blockchain-import --database lmdb#nosync

View file

@ -2,7 +2,7 @@
To run all tests, run: To run all tests, run:
``` ```bash
cd /path/to/monero cd /path/to/monero
make [-jn] debug-test # where n is number of compiler processes make [-jn] debug-test # where n is number of compiler processes
``` ```
@ -17,7 +17,7 @@ Tests are located in `tests/core_tests/`, and follow a straightforward naming co
To run only Monero's core tests (after building): To run only Monero's core tests (after building):
``` ```bash
cd build/debug/tests/core_tests cd build/debug/tests/core_tests
ctest ctest
``` ```
@ -36,7 +36,7 @@ Tests correspond to components under `src/crypto/`. A quick comparison reveals t
To run only Monero's crypto tests (after building): To run only Monero's crypto tests (after building):
``` ```bash
cd build/debug/tests/crypto cd build/debug/tests/crypto
ctest ctest
``` ```
@ -53,13 +53,13 @@ To run the same tests on a release build, replace `debug` with `release`.
Functional tests are located under the `tests/functional` directory. Functional tests are located under the `tests/functional` directory.
First, run a regtest daemon in the offline mode and with a fixed difficulty: First, run a regtest daemon in the offline mode and with a fixed difficulty:
``` ```bash
monerod --regtest --offline --fixed-difficulty 1 monerod --regtest --offline --fixed-difficulty 1
``` ```
Alternatively, you can run multiple daemons and let them connect with each other by using `--add-exclusive-node`. In this case, make sure that the same fixed difficulty is given to all the daemons. Alternatively, you can run multiple daemons and let them connect with each other by using `--add-exclusive-node`. In this case, make sure that the same fixed difficulty is given to all the daemons.
Next, restore a mainnet wallet with the following seed and restore height 0 (the file path doesn't matter): Next, restore a mainnet wallet with the following seed and restore height 0 (the file path doesn't matter):
``` ```bash
velvet lymph giddy number token physics poetry unquoted nibs useful sabotage limits benches lifestyle eden nitrogen anvil fewest avoid batch vials washing fences goat unquoted velvet lymph giddy number token physics poetry unquoted nibs useful sabotage limits benches lifestyle eden nitrogen anvil fewest avoid batch vials washing fences goat unquoted
``` ```
@ -77,7 +77,7 @@ Hash tests exist under `tests/hash`, and include a set of target hashes in text
To run only Monero's hash tests (after building): To run only Monero's hash tests (after building):
``` ```bash
cd build/debug/tests/hash cd build/debug/tests/hash
ctest ctest
``` ```
@ -98,7 +98,7 @@ Performance tests are located in `tests/performance_tests`, and test features fo
To run only Monero's performance tests (after building): To run only Monero's performance tests (after building):
``` ```bash
cd build/debug/tests/performance_tests cd build/debug/tests/performance_tests
./performance_tests ./performance_tests
``` ```
@ -115,7 +115,7 @@ Unit tests are defined under the `tests/unit_tests` directory. Independent compo
To run only Monero's unit tests (after building): To run only Monero's unit tests (after building):
``` ```bash
cd build/debug/tests/unit_tests cd build/debug/tests/unit_tests
ctest ctest
``` ```

View file

@ -14,15 +14,19 @@ Suppose you put Google Test in directory `${GTEST_DIR}`. To build it,
create a library build target (or a project as called by Visual Studio create a library build target (or a project as called by Visual Studio
and Xcode) to compile and Xcode) to compile
${GTEST_DIR}/src/gtest-all.cc ```bash
${GTEST_DIR}/src/gtest-all.cc
```
with `${GTEST_DIR}/include` in the system header search path and `${GTEST_DIR}` with `${GTEST_DIR}/include` in the system header search path and `${GTEST_DIR}`
in the normal header search path. Assuming a Linux-like system and gcc, in the normal header search path. Assuming a Linux-like system and gcc,
something like the following will do: something like the following will do:
g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \ ```bash
-pthread -c ${GTEST_DIR}/src/gtest-all.cc g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \
ar -rv libgtest.a gtest-all.o -pthread -c ${GTEST_DIR}/src/gtest-all.cc
ar -rv libgtest.a gtest-all.o
```
(We need `-pthread` as Google Test uses threads.) (We need `-pthread` as Google Test uses threads.)
@ -30,8 +34,10 @@ Next, you should compile your test source file with
`${GTEST_DIR}/include` in the system header search path, and link it `${GTEST_DIR}/include` in the system header search path, and link it
with gtest and any other necessary libraries: with gtest and any other necessary libraries:
g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \ ```bash
-o your_test g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \
-o your_test
```
As an example, the make/ directory contains a Makefile that you can As an example, the make/ directory contains a Makefile that you can
use to build Google Test on systems where GNU make is available use to build Google Test on systems where GNU make is available
@ -43,9 +49,11 @@ script.
If the default settings are correct for your environment, the If the default settings are correct for your environment, the
following commands should succeed: following commands should succeed:
cd ${GTEST_DIR}/make ```bash
make cd ${GTEST_DIR}/make
./sample1_unittest make
./sample1_unittest
```
If you see errors, try to tweak the contents of `make/Makefile` to make If you see errors, try to tweak the contents of `make/Makefile` to make
them go away. There are instructions in `make/Makefile` on how to do them go away. There are instructions in `make/Makefile` on how to do
@ -62,14 +70,18 @@ CMake works by generating native makefiles or build projects that can
be used in the compiler environment of your choice. The typical be used in the compiler environment of your choice. The typical
workflow starts with: workflow starts with:
mkdir mybuild # Create a directory to hold the build output. ```bash
cd mybuild mkdir mybuild # Create a directory to hold the build output.
cmake ${GTEST_DIR} # Generate native build scripts. cd mybuild
cmake ${GTEST_DIR} # Generate native build scripts.
```
If you want to build Google Test's samples, you should replace the If you want to build Google Test's samples, you should replace the
last command with last command with
cmake -Dgtest_build_samples=ON ${GTEST_DIR} ```bash
cmake -Dgtest_build_samples=ON ${GTEST_DIR}
```
If you are on a \*nix system, you should now see a Makefile in the If you are on a \*nix system, you should now see a Makefile in the
current directory. Just type 'make' to build gtest. current directory. Just type 'make' to build gtest.
@ -108,7 +120,9 @@ end up in your selected build directory (selected in the Xcode
"Preferences..." -> "Building" pane and defaults to xcode/build). "Preferences..." -> "Building" pane and defaults to xcode/build).
Alternatively, at the command line, enter: Alternatively, at the command line, enter:
xcodebuild ```bash
xcodebuild
```
This will build the "Release" configuration of gtest.framework in your This will build the "Release" configuration of gtest.framework in your
default build location. See the "xcodebuild" man page for more default build location. See the "xcodebuild" man page for more
@ -152,18 +166,24 @@ tell Google Test to use the same TR1 tuple library the rest of your
project uses, or the two tuple implementations will clash. To do project uses, or the two tuple implementations will clash. To do
that, add that, add
-DGTEST_USE_OWN_TR1_TUPLE=0 ```bash
-DGTEST_USE_OWN_TR1_TUPLE=0
```
to the compiler flags while compiling Google Test and your tests. If to the compiler flags while compiling Google Test and your tests. If
you want to force Google Test to use its own tuple library, just add you want to force Google Test to use its own tuple library, just add
-DGTEST_USE_OWN_TR1_TUPLE=1 ```bash
-DGTEST_USE_OWN_TR1_TUPLE=1
```
to the compiler flags instead. to the compiler flags instead.
If you don't want Google Test to use tuple at all, add If you don't want Google Test to use tuple at all, add
-DGTEST_HAS_TR1_TUPLE=0 ```bash
-DGTEST_HAS_TR1_TUPLE=0
```
and all features using tuple will be disabled. and all features using tuple will be disabled.
@ -177,11 +197,15 @@ macro to see whether this is the case (yes if the macro is `#defined` to
If Google Test doesn't correctly detect whether pthread is available If Google Test doesn't correctly detect whether pthread is available
in your environment, you can force it with in your environment, you can force it with
-DGTEST_HAS_PTHREAD=1 ```bash
-DGTEST_HAS_PTHREAD=1
```
or or
-DGTEST_HAS_PTHREAD=0 ```bash
-DGTEST_HAS_PTHREAD=0
```
When Google Test uses pthread, you may need to add flags to your When Google Test uses pthread, you may need to add flags to your
compiler and/or linker to select the pthread library, or you'll get compiler and/or linker to select the pthread library, or you'll get
@ -198,7 +222,9 @@ as a shared library (known as a DLL on Windows) if you prefer.
To compile *gtest* as a shared library, add To compile *gtest* as a shared library, add
-DGTEST_CREATE_SHARED_LIBRARY=1 ```bash
-DGTEST_CREATE_SHARED_LIBRARY=1
```
to the compiler flags. You'll also need to tell the linker to produce to the compiler flags. You'll also need to tell the linker to produce
a shared library instead - consult your linker's manual for how to do a shared library instead - consult your linker's manual for how to do
@ -206,7 +232,9 @@ it.
To compile your *tests* that use the gtest shared library, add To compile your *tests* that use the gtest shared library, add
-DGTEST_LINKED_AS_SHARED_LIBRARY=1 ```bash
-DGTEST_LINKED_AS_SHARED_LIBRARY=1
```
to the compiler flags. to the compiler flags.
@ -229,18 +257,24 @@ conflict.
Specifically, if both Google Test and some other code define macro Specifically, if both Google Test and some other code define macro
FOO, you can add FOO, you can add
-DGTEST_DONT_DEFINE_FOO=1 ```bash
-DGTEST_DONT_DEFINE_FOO=1
```
to the compiler flags to tell Google Test to change the macro's name to the compiler flags to tell Google Test to change the macro's name
from `FOO` to `GTEST_FOO`. Currently `FOO` can be `FAIL`, `SUCCEED`, from `FOO` to `GTEST_FOO`. Currently `FOO` can be `FAIL`, `SUCCEED`,
or `TEST`. For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll or `TEST`. For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll
need to write need to write
GTEST_TEST(SomeTest, DoesThis) { ... } ```c++
GTEST_TEST(SomeTest, DoesThis) { ... }
```
instead of instead of
TEST(SomeTest, DoesThis) { ... } ```c++
TEST(SomeTest, DoesThis) { ... }
```
in order to define a test. in order to define a test.
@ -254,9 +288,11 @@ To make sure your changes work as intended and don't break existing
functionality, you'll want to compile and run Google Test's own tests. functionality, you'll want to compile and run Google Test's own tests.
For that you can use CMake: For that you can use CMake:
mkdir mybuild ```bash
cd mybuild mkdir mybuild
cmake -Dgtest_build_tests=ON ${GTEST_DIR} cd mybuild
cmake -Dgtest_build_tests=ON ${GTEST_DIR}
```
Make sure you have Python installed, as some of Google Test's tests Make sure you have Python installed, as some of Google Test's tests
are written in Python. If the cmake command complains about not being are written in Python. If the cmake command complains about not being
@ -264,12 +300,16 @@ able to find Python (`Could NOT find PythonInterp (missing:
PYTHON_EXECUTABLE)`), try telling it explicitly where your Python PYTHON_EXECUTABLE)`), try telling it explicitly where your Python
executable can be found: executable can be found:
cmake -DPYTHON_EXECUTABLE=path/to/python -Dgtest_build_tests=ON ${GTEST_DIR} ```bash
cmake -DPYTHON_EXECUTABLE=path/to/python -Dgtest_build_tests=ON ${GTEST_DIR}
```
Next, you can build Google Test and all of its own tests. On \*nix, Next, you can build Google Test and all of its own tests. On \*nix,
this is usually done by 'make'. To run the tests, do this is usually done by 'make'. To run the tests, do
make test ```bash
make test
```
All tests should pass. All tests should pass.