aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--README.i18n.md24
-rw-r--r--README.md296
-rw-r--r--contrib/depends/README.md42
-rw-r--r--contrib/depends/packages.md196
-rw-r--r--contrib/gitian/README.md8
-rw-r--r--src/blockchain_utilities/README.md2
-rw-r--r--tests/README.md16
-rw-r--r--tests/gtest/README.md98
8 files changed, 431 insertions, 251 deletions
diff --git a/README.i18n.md b/README.i18n.md
index a3bd8070e..5df277624 100644
--- a/README.i18n.md
+++ b/README.i18n.md
@@ -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:
- ./utils/translations/update-translations.sh
+```bash
+./utils/translations/update-translations.sh
+```
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:
- linguist translations/monero_es.ts
+```bash
+linguist translations/monero_es.ts
+```
To build translations after modifying them:
- ./utils/translations/build-translations.sh
+```bash
+./utils/translations/build-translations.sh
+```
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:
@@ -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:
- 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.
diff --git a/README.md b/README.md
index c46856b17..cd005ac49 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,28 @@
# Monero
-Copyright (c) 2014-2018 The Monero Project.
+Copyright (c) 2014-2019 The Monero Project.
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
- Web: [getmonero.org](https://getmonero.org)
@@ -206,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
@@ -232,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
@@ -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.
* 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`
@@ -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
-```
- 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.
@@ -333,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
@@ -360,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`
@@ -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`.
-```
+```bash
# Create boost building directory
mkdir ~/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.
-```
+```bash
# Create cppzmq building directory
mkdir ~/cppzmq
cd ~/cppzmq
@@ -484,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
@@ -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:
- 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
@@ -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.
* ```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.
@@ -563,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.
@@ -573,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
@@ -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
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
@@ -614,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
@@ -662,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
@@ -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
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
@@ -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.
-* 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`
```
@@ -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:
-`gdb /path/to/monerod /path/to/dumpfile`
+```bash
+gdb /path/to/monerod /path/to/dumpfile`
+```
Print the stack trace with `bt`
-* To run monero within gdb:
+#### To run monero within gdb:
Type `gdb /path/to/monerod`
@@ -722,15 +816,17 @@ Type `run` to run monerod
There are two tools available:
-* ASAN
+#### ASAN
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.
-* valgrind
+#### valgrind
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:
-`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.
diff --git a/contrib/depends/README.md b/contrib/depends/README.md
index c9f8b0783..6a15055b4 100644
--- a/contrib/depends/README.md
+++ b/contrib/depends/README.md
@@ -2,21 +2,29 @@
To build dependencies for the current arch+OS:
- make
+```bash
+make
+```
To build for another arch/OS:
- make HOST=host-platform-triplet
+```bash
+make HOST=host-platform-triplet
+```
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
cmake. In the above example, a dir named x86_64-w64-mingw32 will be
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:
@@ -31,20 +39,24 @@ No other options are needed, the paths are automatically configured.
Dependency Options:
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
- SDK_PATH: Path where sdk's can be found (used by OSX)
- FALLBACK_DOWNLOAD_PATH: If a source file can't be fetched, try here before giving up
- DEBUG: disable some optimizations and enable more runtime checking
- HOST_ID_SALT: Optional salt to use when generating host package ids
- BUILD_ID_SALT: Optional salt to use when generating build package ids
+```
+SOURCES_PATH: downloaded sources will be placed here
+BASE_CACHE: built packages will be placed here
+SDK_PATH: Path where sdk's can be found (used by OSX)
+FALLBACK_DOWNLOAD_PATH: If a source file can't be fetched, try here before giving up
+DEBUG: disable some optimizations and enable more runtime checking
+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:
- 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-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
+```
+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-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:
diff --git a/contrib/depends/packages.md b/contrib/depends/packages.md
index 7c8036250..ae5b47327 100644
--- a/contrib/depends/packages.md
+++ b/contrib/depends/packages.md
@@ -9,39 +9,43 @@ General tips:
## Identifiers
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
- placeholder such as 1.0 can be used.
+```
+$(package)_version:
+Version of the upstream library or program. If there is no version, a
+placeholder such as 1.0 can be used.
- $(package)_download_path:
- Location of the upstream source, without the file-name. Usually http or
- ftp.
+$(package)_download_path:
+Location of the upstream source, without the file-name. Usually http or
+ftp.
- $(package)_file_name:
- The upstream source filename available at the download path.
+$(package)_file_name:
+The upstream source filename available at the download path.
- $(package)_sha256_hash:
- The sha256 hash of the upstream file
+$(package)_sha256_hash:
+The sha256 hash of the upstream file
+```
These variables are optional:
- $(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:
- 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'.
+```
+$(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:
+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:
@@ -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
$(package)_set_vars. For example:
- define $(package)_set_vars
- ...
- endef
+```
+define $(package)_set_vars
+...
+endef
+```
Most variables can be prefixed with the host, architecture, or both, to make
the modifications specific to that case. For example:
- Universal: $(package)_cc=gcc
- Linux only: $(package)_linux_cc=gcc
- x86_64 only: $(package)_x86_64_cc = gcc
- x86_64 linux only: $(package)_x86_64_linux_cc = gcc
+```
+Universal: $(package)_cc=gcc
+Linux only: $(package)_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.
- $(package)_cc
- $(package)_cxx
- $(package)_objc
- $(package)_objcxx
- $(package)_ar
- $(package)_ranlib
- $(package)_libtool
- $(package)_nm
- $(package)_cflags
- $(package)_cxxflags
- $(package)_ldflags
- $(package)_cppflags
- $(package)_config_env
- $(package)_build_env
- $(package)_stage_env
- $(package)_build_opts
- $(package)_config_opts
-
-The *_env variables are used to add environment variables to the respective
+```
+$(package)_cc
+$(package)_cxx
+$(package)_objc
+$(package)_objcxx
+$(package)_ar
+$(package)_ranlib
+$(package)_libtool
+$(package)_nm
+$(package)_cflags
+$(package)_cxxflags
+$(package)_ldflags
+$(package)_cppflags
+$(package)_config_env
+$(package)_build_env
+$(package)_stage_env
+$(package)_build_opts
+$(package)_config_opts
+```
+
+The `*_env` variables are used to add environment variables to the respective
commands.
Many variables respect a debug/release suffix as well, in order to use them for
only the appropriate build config. For example:
- $(package)_cflags_release = -O3
- $(package)_cflags_i686_debug = -g
- $(package)_config_opts_release = --disable-debug
+```
+$(package)_cflags_release = -O3
+$(package)_cflags_i686_debug = -g
+$(package)_config_opts_release = --disable-debug
+```
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
@@ -97,51 +109,57 @@ the user. Other variables may be defined as needed.
## Build commands:
- 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`.
+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`.
+
+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
+Fetch the source file. If undefined, it will be fetched and verified
+against its hash.
- $(package)_fetch_cmds:
- Runs from: build dir
- Fetch the source file. If undefined, it will be fetched and verified
- against its hash.
+$(package)_extract_cmds:
+Runs from: build dir
+Verify the source file against its hash and extract it. If undefined, the
+source is assumed to be a tarball.
- $(package)_extract_cmds:
- Runs from: build dir
- Verify the source file against its hash and extract it. If undefined, the
- source is assumed to be a tarball.
+$(package)_preprocess_cmds:
+Runs from: build dir/$(package)_build_subdir
+Preprocess the source as necessary. If undefined, does nothing.
- $(package)_preprocess_cmds:
- Runs from: build dir/$(package)_build_subdir
- Preprocess the source as necessary. If undefined, does nothing.
+$(package)_config_cmds:
+Runs from: build dir/$(package)_build_subdir
+Configure the source. If undefined, does nothing.
- $(package)_config_cmds:
- Runs from: build dir/$(package)_build_subdir
- Configure the source. If undefined, does nothing.
+$(package)_build_cmds:
+Runs from: build dir/$(package)_build_subdir
+Build the source. If undefined, does nothing.
- $(package)_build_cmds:
- Runs from: build dir/$(package)_build_subdir
- Build the source. If undefined, does nothing.
+$(package)_stage_cmds:
+Runs from: build dir/$(package)_build_subdir
+Stage the build results. If undefined, does nothing.
+```
- $(package)_stage_cmds:
- Runs from: build dir/$(package)_build_subdir
- 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)_extract_dir: path to the package's extracted sources
- $(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
+```
+$(1)_staging_dir: package's destination sysroot path
+$(1)_staging_prefix_dir: prefix path inside of the package's staging dir
+$(1)_extract_dir: path to the package's extracted sources
+$(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:
-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
-$($(package)_config_opts) will be appended.
+`$($(package)_config_opts`) will be appended.
Most autotools projects can be properly staged using:
- $(MAKE) DESTDIR=$($(package)_staging_dir) install
+```bash
+$(MAKE) DESTDIR=$($(package)_staging_dir) install
+```
diff --git a/contrib/gitian/README.md b/contrib/gitian/README.md
index b869bde87..1efc87e0a 100644
--- a/contrib/gitian/README.md
+++ b/contrib/gitian/README.md
@@ -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,
or pass the signed assert file back to your build machine.
-```
+```bash
git clone git@github.com:monero-project/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
- 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}-osx-unsigned/${SIGNER}/monero-osx-*-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}-osx-unsigned/${SIGNER}/monero-osx-*-build.assert
```
More Build Options
diff --git a/src/blockchain_utilities/README.md b/src/blockchain_utilities/README.md
index ad5963f27..1462e3186 100644
--- a/src/blockchain_utilities/README.md
+++ b/src/blockchain_utilities/README.md
@@ -79,7 +79,7 @@ LMDB flags (more than one may be specified):
## Examples:
-```
+```bash
$ monero-blockchain-import --database lmdb#fastest
$ monero-blockchain-import --database lmdb#nosync
diff --git a/tests/README.md b/tests/README.md
index 053dd2244..f6dd25ead 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -2,7 +2,7 @@
To run all tests, run:
-```
+```bash
cd /path/to/monero
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):
-```
+```bash
cd build/debug/tests/core_tests
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):
-```
+```bash
cd build/debug/tests/crypto
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.
First, run a regtest daemon in the offline mode and with a fixed difficulty:
-```
+```bash
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.
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
```
@@ -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):
-```
+```bash
cd build/debug/tests/hash
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):
-```
+```bash
cd build/debug/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):
-```
+```bash
cd build/debug/tests/unit_tests
ctest
```
diff --git a/tests/gtest/README.md b/tests/gtest/README.md
index e0ea1b0f3..43a16bde0 100644
--- a/tests/gtest/README.md
+++ b/tests/gtest/README.md
@@ -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
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}`
in the normal header search path. Assuming a Linux-like system and gcc,
something like the following will do:
- g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \
- -pthread -c ${GTEST_DIR}/src/gtest-all.cc
- ar -rv libgtest.a gtest-all.o
+```bash
+g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \
+ -pthread -c ${GTEST_DIR}/src/gtest-all.cc
+ar -rv libgtest.a gtest-all.o
+```
(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
with gtest and any other necessary libraries:
- g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \
- -o your_test
+```bash
+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
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
following commands should succeed:
- cd ${GTEST_DIR}/make
- make
- ./sample1_unittest
+```bash
+cd ${GTEST_DIR}/make
+make
+./sample1_unittest
+```
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
@@ -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
workflow starts with:
- mkdir mybuild # Create a directory to hold the build output.
- cd mybuild
- cmake ${GTEST_DIR} # Generate native build scripts.
+```bash
+mkdir mybuild # Create a directory to hold the build output.
+cd mybuild
+cmake ${GTEST_DIR} # Generate native build scripts.
+```
If you want to build Google Test's samples, you should replace the
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
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).
Alternatively, at the command line, enter:
- xcodebuild
+```bash
+xcodebuild
+```
This will build the "Release" configuration of gtest.framework in your
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
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
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.
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.
@@ -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
in your environment, you can force it with
- -DGTEST_HAS_PTHREAD=1
+```bash
+-DGTEST_HAS_PTHREAD=1
+```
or
- -DGTEST_HAS_PTHREAD=0
+```bash
+-DGTEST_HAS_PTHREAD=0
+```
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
@@ -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
- -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
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
- -DGTEST_LINKED_AS_SHARED_LIBRARY=1
+```bash
+-DGTEST_LINKED_AS_SHARED_LIBRARY=1
+```
to the compiler flags.
@@ -229,18 +257,24 @@ conflict.
Specifically, if both Google Test and some other code define macro
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
from `FOO` to `GTEST_FOO`. Currently `FOO` can be `FAIL`, `SUCCEED`,
or `TEST`. For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll
need to write
- GTEST_TEST(SomeTest, DoesThis) { ... }
+```c++
+GTEST_TEST(SomeTest, DoesThis) { ... }
+```
instead of
- TEST(SomeTest, DoesThis) { ... }
+```c++
+TEST(SomeTest, DoesThis) { ... }
+```
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.
For that you can use CMake:
- mkdir mybuild
- cd mybuild
- cmake -Dgtest_build_tests=ON ${GTEST_DIR}
+```bash
+mkdir mybuild
+cd mybuild
+cmake -Dgtest_build_tests=ON ${GTEST_DIR}
+```
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
@@ -264,12 +300,16 @@ able to find Python (`Could NOT find PythonInterp (missing:
PYTHON_EXECUTABLE)`), try telling it explicitly where your Python
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,
this is usually done by 'make'. To run the tests, do
- make test
+```bash
+make test
+```
All tests should pass.
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-19 07:10:59 +0000