From dc911f063ce26066da2af2d7dcea2e4bd6a3e2c2 Mon Sep 17 00:00:00 2001 From: Matt Witherspoon <32485495+spoonincode@users.noreply.github.com> Date: Tue, 5 Jul 2022 11:04:38 -0400 Subject: [PATCH 1/4] various README.md fixups --- README.md | 127 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 81 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 546ea29c09..768e178cc4 100644 --- a/README.md +++ b/README.md @@ -2,24 +2,41 @@ Home of the official [EOS Network Foundation](https://eosnetwork.com/) blockchain node software. -## Repo organization +## Repo Organization -| branch | description | -| ------ | ----------- | -| `main` | Development for future releases | -| `release/3.0.x` | 3.0.x-* series of pre-releases before 3.1.x | -| `release/3.1.x` | 3.1.x* series of 3.1.0 releases | +`main` branch is the development branch: do not use this for production. Refer to the [release page](https://github.com/eosnetworkfoundation/mandel/releases) for current information on releases, pre-releases, and obsolete releases as well as the corresponding tags for those releases. -## Supported Operating Systems +## Software Installation -To speed up development, we're starting with **Ubuntu 20.04**. We'll support additional operating systems as time and personnel allow. In the mean time, they may break. +Visit the [release page](https://github.com/eosnetworkfoundation/mandel/releases) for Ubuntu binaries. This is the fastest way to get started with the software. -## Building +### Building From Source -To speed up development and reduce support overhead, we're initially only supporting the following build approach. CMake options not listed here may break. Build scripts may break. Dockerfiles may break. +Recent Ubuntu LTS releases are the only Linux distributions that we fully support. Other Linux distros and other POSIX operating systems (such as macOS) are tended to on a best-effort basis and may not be full featured. Notable requirements to build are: +* C++17 compiler and standard library +* boost 1.67+ +* CMake 3.8+ +* (for Linux only) LLVM 7 - 11 (newer versions do not work) -### Ubuntu 20.04 dependencies +A few other common libraries are tools also required such as openssl 1.1+, libcurl, curl, libusb, GMP, Python 3, and zlib. +**A Warning On Parallel Compilation Jobs (`-j` flag)**: When building C/C++ software often the build is performed in parallel via a command such as `make -j $(nproc)` which uses the number of CPU cores as the number of compilation jobs to perform simultaneously. However, be aware that some compilation units (.cpp files) in mandel are extremely complex and will consume nearly 4GB of memory to compile. You may need to reduce the level of parallelization depending on the amount of memory on your build host. e.g. instead of `make -j $(nproc)` run `make -j2`. Failures due to memory exhaustion will typically but not always manifest as compiler crashes. + +Generally we recommend performing what we refer to as a "pinned build" which ensures the compiler and boost version remain the same between builds of different mandel versions (mandel requires these versions remain the same otherwise its state needs to be repopulated from a portable snapshot). + +#### Building Pinned Build Binary Packages +In the directory `/scripts` you will find the two scripts `install_deps.sh` and `pinned_build.sh`. If you haven't installed build dependencies then run `install_deps.sh`. Then run `pinned_build.sh `. + +The dependencies directory is where the script will pull the C++ dependencies that need to be built with the pinned compiler for building the pinned binaries for binary packaging. + +The binary package will be produced in the mandel build directory that was supplied. + +#### Manual (non "pinned") Build Instructions + +
+ Ubuntu 20.04 & 22.04 Build Instructions + +Install required dependencies: ``` apt-get update && apt-get install \ build-essential \ @@ -30,62 +47,80 @@ apt-get update && apt-get install \ libcurl4-openssl-dev \ libgmp-dev \ libssl-dev \ - libtinfo5 \ libusb-1.0-0-dev \ - libzstd-dev \ llvm-11-dev \ - ninja-build \ - pkg-config \ - time + pkg-config ``` - -### Building - +and perform the build: ``` git submodule update --init --recursive mkdir build cd build cmake -DCMAKE_BUILD_TYPE=Release .. -make -j $(nproc) +make -j $(nproc) package ``` +
+ +
+ Ubuntu 18.04 Build Instructions -We support the following CMake options: +Install required dependencies. You will need to build Boost from source on this distribution. ``` --DCMAKE_CXX_COMPILER_LAUNCHER=ccache Speed up builds --DCMAKE_C_COMPILER_LAUNCHER=ccache Speed up builds --DCMAKE_BUILD_TYPE=DEBUG Debug builds --DDISABLE_WASM_SPEC_TESTS=yes Speed up builds and skip many tests --DCMAKE_INSTALL_PREFIX=/foo/bar Where to install to --DENABLE_OC=no Disable OC support; useful when this repo is used - as a library --GNinja Use ninja instead of make - (faster on high-core-count machines) +apt-get update && apt-get install \ + build-essential \ + cmake \ + curl \ + g++-8 \ + git \ + libcurl4-openssl-dev \ + libgmp-dev \ + libssl-dev \ + libusb-1.0-0-dev \ + llvm-7-dev \ + pkg-config \ + python3 \ + zlib1g-dev + +curl -L https://boostorg.jfrog.io/artifactory/main/release/1.79.0/source/boost_1_79_0.tar.bz2 | tar jx && \ + cd boost_1_79_0 && \ + ./bootstrap.sh --prefix=$HOME/boost1.79 && \ + ./b2 --with-iostreams --with-date_time --with-filesystem --with-system \ + --with-program_options --with-chrono --with-test -j$(nproc) install && \ + cd .. +``` +and perform the build: +``` +git submodule update --init --recursive +mkdir build +cd build +cmake -DCMAKE_C_COMPILER=gcc-8 -DCMAKE_CXX_COMPILER=g++-8 \ + -DCMAKE_PREFIX_PATH="$HOME/boost1.79;/usr/lib/llvm-7/" -DCMAKE_BUILD_TYPE=Release .. \ +make -j $(nproc) package ``` +After building you may remove the `$HOME/boost1.79` directory, or you may keep it around until next time building the software. +
-I highly recommend the ccache options. They don't speed up the first clean build, but they speed up future clean builds after the first build. +### Running Tests -### Running tests +When building from source it's recommended to run at least what we refer to as the "parallelizable tests". Not included by default in the "parallelizable tests" are the WASM spec tests which can add additional coverage and can also be run in parallel. ``` cd build -# Runs parallelizable tests in parallel. This runs much faster when -# -DDISABLE_WASM_SPEC_TESTS=yes is used. -ctest -j $(nproc) -LE "nonparallelizable_tests|long_running_tests" -E "full-version-label-test|release-build-test|print-build-info-test" +# "parallelizable tests": the minimum test set that should be run +ctest -j $(nproc) -LE _tests + +# Also consider running the WASM spec tests for more coverage +ctest -j $(nproc) -L wasm_spec_tests +``` -# These tests can't run in parallel. +Some other tests are available and recommended but be aware they can be sensitive to other software running on the same host and they may **SIGKILL** other nodeos instances running on the host. +``` +cd build + +# These tests can't run in parallel but are recommended. ctest -L "nonparallelizable_tests" # These tests can't run in parallel. They also take a long time to run. ctest -L "long_running_tests" ``` - -### Building Pinned Build Binary Packages -In the directory `/scripts` you will find the two scripts `install_deps.sh` and `pinned_build.sh`. These are designed currently to run on Ubuntu 18/20/22. - -If you haven't installed build dependencies then run `install_deps.sh`. -Then run `pinned_build.sh `. - -The dependencies directory is where the script will pull the C++ dependencies that need to be built with the pinned compiler for building the pinned binaries for binary packaging. - -The binary package will be produced in the mandel build directory that was supplied. From 07da436a51c6c68dbb08616bab4a6f399e8324f7 Mon Sep 17 00:00:00 2001 From: Kevin Heifner Date: Wed, 6 Jul 2022 08:41:28 -0500 Subject: [PATCH 2/4] Bump to 3.1.0-rc2 --- CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 6961da7075..c79f89da10 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -17,7 +17,7 @@ set( CXX_STANDARD_REQUIRED ON) set(VERSION_MAJOR 3) set(VERSION_MINOR 1) set(VERSION_PATCH 0) -set(VERSION_SUFFIX rc1) +set(VERSION_SUFFIX rc2) if(VERSION_SUFFIX) set(VERSION_FULL "${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}-${VERSION_SUFFIX}") From 66faea7d1a49400c223889293b48d4abd0fde873 Mon Sep 17 00:00:00 2001 From: Bucky Kittinger Date: Wed, 6 Jul 2022 09:44:15 -0400 Subject: [PATCH 3/4] bump submod --- libraries/fc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/fc b/libraries/fc index 68115c0793..35c45cb2de 160000 --- a/libraries/fc +++ b/libraries/fc @@ -1 +1 @@ -Subproject commit 68115c0793be9fbfb4c7f9f5b6f7eefa0b6cc788 +Subproject commit 35c45cb2defe6ce5738074a47c18fdb7616bf9fc From a0e740b7953d7ad1c2e29483e82190d481c68b0f Mon Sep 17 00:00:00 2001 From: Bucky Kittinger Date: Wed, 6 Jul 2022 09:45:20 -0400 Subject: [PATCH 4/4] wrong reference --- libraries/fc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/fc b/libraries/fc index 35c45cb2de..26cffa0ae4 160000 --- a/libraries/fc +++ b/libraries/fc @@ -1 +1 @@ -Subproject commit 35c45cb2defe6ce5738074a47c18fdb7616bf9fc +Subproject commit 26cffa0ae4118bd6cd01458d1d98efa702ed92b1