{"id":25037939,"url":"https://github.com/AntelopeIO/spring","last_synced_at":"2025-10-20T22:30:52.912Z","repository":{"id":237066193,"uuid":"782281810","full_name":"AntelopeIO/spring","owner":"AntelopeIO","description":"C++ implementation of the Antelope protocol with Savanna consensus","archived":false,"fork":false,"pushed_at":"2024-10-29T12:30:49.000Z","size":172099,"stargazers_count":9,"open_issues_count":66,"forks_count":4,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-10-29T14:54:19.228Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AntelopeIO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-05T01:40:15.000Z","updated_at":"2024-10-29T12:28:26.000Z","dependencies_parsed_at":"2024-05-22T22:03:22.187Z","dependency_job_id":null,"html_url":"https://github.com/AntelopeIO/spring","commit_stats":null,"previous_names":["antelopeio/spring"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntelopeIO%2Fspring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntelopeIO%2Fspring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntelopeIO%2Fspring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntelopeIO%2Fspring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AntelopeIO","download_url":"https://codeload.github.com/AntelopeIO/spring/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237403368,"owners_count":19304417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-06T02:01:24.993Z","updated_at":"2025-10-20T22:30:50.047Z","avatar_url":"https://github.com/AntelopeIO.png","language":"C++","funding_links":[],"categories":["Recently Updated","Official"],"sub_categories":["[Feb 06, 2025](/content/2025/02/06/README.md)"],"readme":"# Spring\n\n1. [Branches](#branches)\n2. [Supported Operating Systems](#supported-operating-systems)\n3. [Binary Installation](#binary-installation)\n4. [Build and Install from Source](#build-and-install-from-source)\n5. [Bash Autocomplete](#bash-autocomplete)\n\nSpring is a C++ implementation of the [Antelope](https://github.com/AntelopeIO) protocol with support for Savanna consensus. It contains blockchain node software and supporting tools for developers and node operators.\n\n## Branches\nThe `main` branch is the development branch; do not use it for production. Refer to the [release page](https://github.com/AntelopeIO/spring/releases) for current information on releases, pre-releases, and obsolete releases, as well as the corresponding tags for those releases.\n\n## Supported Operating Systems\nWe currently support the following operating systems.\n- Ubuntu 22.04 Jammy\n- Ubuntu 20.04 Focal\n\nOther Unix derivatives such as macOS are tended to on a best-effort basis and may not be full featured. If you aren't using Ubuntu, please visit the \"[Build Unsupported OS](./docs/00_install/01_build-from-source/00_build-unsupported-os.md)\" page to explore your options.\n\nIf you are running an unsupported Ubuntu derivative, such as Linux Mint, you can find the version of Ubuntu your distribution was based on by using this command:\n```bash\ncat /etc/upstream-release/lsb-release\n```\nYour best bet is to follow the instructions for your Ubuntu base, but we make no guarantees.\n\n## Binary Installation\nThis is the fastest way to get started. From the [latest release](https://github.com/AntelopeIO/spring/releases/latest) page, download a binary for one of our [supported operating systems](#supported-operating-systems), or visit the [release tags](https://github.com/AntelopeIO/spring/releases) page to download a binary for a specific version of Spring.\n\nOnce you have a `*.deb` file downloaded for your version of Ubuntu, you can install it as follows:\n```bash\nsudo apt-get update\nsudo apt-get install -y ~/Downloads/spring*.deb\n```\nYour download path may vary. If you are in an Ubuntu docker container, omit `sudo` because you run as `root` by default.\n\nFinally, verify Spring was installed correctly:\n```bash\nnodeos --full-version\n```\nYou should see a [semantic version](https://semver.org) string followed by a `git` commit hash with no errors. For example:\n```\nv1.0.1-9026a03c09c9b4f93edca696b5eef259f0ab96b3\n```\n\n## Build and Install from Source\nYou can also build and install Spring from source.\n\n### Prerequisites\nYou will need to build on a [supported operating system](#supported-operating-systems).\n\nRequirements to build:\n- C++20 compiler and standard library\n- CMake 3.16+\n- LLVM 7 - 11 - for Linux only\n  - newer versions do not work\n- libcurl 7.40.0+\n- git\n- GMP\n- Python 3\n- python3-numpy\n- zlib\n\n### Step 1 - Clone\nIf you don't have the Spring repo cloned to your computer yet, [open a terminal](https://itsfoss.com/open-terminal-ubuntu) and navigate to the folder where you want to clone the Spring repository:\n```bash\ncd ~/Downloads\n```\nClone Spring using either HTTPS...\n```bash\ngit clone --recursive https://github.com/AntelopeIO/spring.git\n```\n...or SSH:\n```bash\ngit clone --recursive git@github.com:AntelopeIO/spring.git\n```\n\n\u003e ℹ️ **HTTPS vs. SSH Clone** ℹ️  \nBoth an HTTPS or SSH git clone will yield the same result - a folder named `spring` containing our source code. It doesn't matter which type you use.\n\nNavigate into that folder:\n```bash\ncd spring\n```\n\n### Step 2 - Checkout Release Tag or Branch\nChoose which [release](https://github.com/AntelopeIO/spring/releases) or [branch](#branches) you would like to build, then check it out. If you are not sure, use the [latest release](https://github.com/AntelopeIO/spring/releases/latest). For example, if you want to build release 1.0.1 then you would check it out using its tag, `v1.0.1`. In the example below, replace `v0.0.0` with your selected release tag accordingly:\n```bash\ngit fetch --all --tags\ngit checkout v0.0.0\n```\n\nOnce you are on the branch or release tag you want to build, make sure everything is up-to-date:\n```bash\ngit pull\ngit submodule update --init --recursive\n```\n\n### Step 3 - Build\nSelect build instructions below for a [pinned build](#pinned-build) (preferred) or an [unpinned build](#unpinned-build).\n\n\u003e ℹ️ **Pinned vs. Unpinned Build** ℹ️  \nWe have two types of builds for Spring: \"pinned\" and \"unpinned.\" A pinned build is a reproducible build with the build environment and dependency versions fixed by the development team. In contrast, unpinned builds use the dependency versions provided by the build platform. Unpinned builds tend to be quicker because the pinned build environment must be built from scratch. Pinned builds, in addition to being reproducible, ensure the compiler remains the same between builds of different Spring major versions. Spring requires the compiler version to remain the same, otherwise its state might need to be recovered from a portable snapshot or the chain needs to be replayed.\n\n\u003e ⚠️ **A Warning On Parallel Compilation Jobs (`-j` flag)** ⚠️  \nWhen building C/C++ software, often the build is performed in parallel via a command such as `make -j \"$(nproc)\"` which uses all available CPU threads. However, be aware that some compilation units (`*.cpp` files) in Spring will consume nearly 4GB of memory. Failures due to memory exhaustion will typically, but not always, manifest as compiler crashes. Using all available CPU threads may also prevent you from doing other things on your computer during compilation. For these reasons, consider reducing this value.\n\n\u003e 🐋 **Docker and `sudo`** 🐋  \nIf you are in an Ubuntu docker container, omit `sudo` from all commands because you run as `root` by default. Most other docker containers also exclude `sudo`, especially Debian-family containers. If your shell prompt is a hash tag (`#`), omit `sudo`.\n\n#### Pinned Reproducible Build\nThe pinned reproducible build requires Docker. Make sure you are in the root of the `spring` repo and then run\n```bash\nDOCKER_BUILDKIT=1 docker build -f tools/reproducible.Dockerfile -o . .\n```\nThis command will take a substantial amount of time because a toolchain is built from scratch. Upon completion, the current directory will contain a built `.deb` and `.tar.gz` (you can change the `-o .` argument to place the output in a different directory). If needing to reduce the number of parallel jobs as warned above, run the command as,\n```bash\nDOCKER_BUILDKIT=1 docker build --build-arg SPRING_BUILD_JOBS=4 -f tools/reproducible.Dockerfile -o . .\n```\n\n#### Unpinned Build\nThe following instructions are valid for this branch. Other release branches may have different requirements, so ensure you follow the directions in the branch or release you intend to build. If you are in an Ubuntu docker container, omit `sudo` because you run as `root` by default.\n\nInstall dependencies:\n```bash\nsudo apt-get update\nsudo apt-get install -y \\\n        build-essential \\\n        cmake \\\n        git \\\n        libcurl4-openssl-dev \\\n        libgmp-dev \\\n        llvm-11-dev \\\n        python3-numpy \\\n        file \\\n        zlib1g-dev\n```\n\nOn Ubuntu 20.04, install gcc-10 which has C++20 support:\n```bash\nsudo apt-get install -y g++-10\n```\n\nTo build, make sure you are in the root of the `spring` repo, then run the following command:\n```bash\nmkdir -p build\ncd build\n\n## on Ubuntu 20, specify the gcc-10 compiler\ncmake -DCMAKE_C_COMPILER=gcc-10 -DCMAKE_CXX_COMPILER=g++-10 -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/usr/lib/llvm-11 ..\n\n## on Ubuntu 22, the default gcc version is 11, using the default compiler is fine\ncmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/usr/lib/llvm-11 ..\n\nmake -j \"$(nproc)\" package\n```\n\nNow you can optionally [test](#step-4---test) your build, or [install](#step-5---install) the `*.deb` binary packages, which will be in the root of your build directory.\n\n### Step 4 - Test\nSpring supports the following test suites:\n\nTest Suite | Test Type | [Test Size](https://testing.googleblog.com/2010/12/test-sizes.html) | Notes\n---|:---:|:---:|---\n[Parallelizable tests](#parallelizable-tests) | Unit tests | Small\n[WASM spec tests](#wasm-spec-tests) | Unit tests | Small | Unit tests for our WASM runtime, each short but _very_ CPU-intensive\n[Serial tests](#serial-tests) | Component/Integration | Medium\n[Long-running tests](#long-running-tests) | Integration | Medium-to-Large | Tests which take an extraordinarily long amount of time to run\n\nWhen building from source, we recommended running at least the [parallelizable tests](#parallelizable-tests).\n\n#### Parallelizable Tests\nThis test suite consists of any test that does not require shared resources, such as file descriptors, specific folders, or ports, and can therefore be run concurrently in different threads without side effects (hence, easily parallelized). These are mostly unit tests and [small tests](https://testing.googleblog.com/2010/12/test-sizes.html) which complete in a short amount of time.\n\nYou can invoke them by running `ctest` from a terminal in your Spring build directory and specifying the following arguments:\n```bash\nctest -j \"$(nproc)\" -LE _tests\n```\n\n#### WASM Spec Tests\nThe WASM spec tests verify that our WASM execution engine is compliant with the web assembly standard. These are very [small](https://testing.googleblog.com/2010/12/test-sizes.html), very fast unit tests. However, there are over a thousand of them so the suite can take a little time to run. These tests are extremely CPU-intensive.\n\nYou can invoke them by running `ctest` from a terminal in your Spring build directory and specifying the following arguments:\n```bash\nctest -j \"$(nproc)\" -L wasm_spec_tests\n```\nWe have observed severe performance issues when multiple virtual machines are running this test suite on the same physical host at the same time, for example in a CICD system. This can be resolved by disabling hyperthreading on the host.\n\n#### Serial Tests\nThe serial test suite consists of [medium](https://testing.googleblog.com/2010/12/test-sizes.html) component or integration tests that use specific paths, ports, rely on process names, or similar, and cannot be run concurrently with other tests. Serial tests can be sensitive to other software running on the same host and they may `SIGKILL` other `nodeos` processes. These tests take a moderate amount of time to complete, but we recommend running them.\n\nYou can invoke them by running `ctest` from a terminal in your Spring build directory and specifying the following arguments:\n```bash\nctest -L \"nonparallelizable_tests\"\n```\n\n#### Long-Running Tests\nThe long-running tests are [medium-to-large](https://testing.googleblog.com/2010/12/test-sizes.html) integration tests that rely on shared resources and take a very long time to run.\n\nYou can invoke them by running `ctest` from a terminal in your Spring build directory and specifying the following arguments:\n```bash\nctest -L \"long_running_tests\"\n```\n\n### Step 5 - Install\nOnce you have [built](#step-3---build-the-source-code) Spring and [tested](#step-4---test) your build, you can install Spring on your system. Don't forget to omit `sudo` if you are running in a docker container.\n\nWe recommend installing the binary package you just built. Navigate to your Spring build directory in a terminal and run this command:\n```bash\nsudo apt-get update\nsudo apt-get install -y ./spring_*.deb\n```\n\nIt is also possible to install using `make` instead:\n```bash\nsudo make install\n```\n\n## Bash Autocomplete\n`cleos` and `spring-util` offer a substantial amount of functionality. Consider using bash's autocompletion support which makes it easier to discover all their various options.\n\nFor our provided `.deb` packages simply install Ubuntu's `bash-completion` package: `apt-get install bash-completion` (you may need to log out/in after installing).\n\nIf building from source install the `build/programs/cleos/bash-completion/completions/cleos` and `build/programs/spring-util/bash-completion/completions/spring-util` files to your bash-completion directory. Refer to [bash-completion's documentation](https://github.com/scop/bash-completion#faq) on the possible install locations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAntelopeIO%2Fspring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAntelopeIO%2Fspring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAntelopeIO%2Fspring/lists"}