nimbus-build-system-desktop/README.md

Common parts of the build system used by Nimbus and related projects

We focus on building Nim software on multiple platforms without having to deal with language-specific package managers.

We care about dependencies specified with commit-level accuracy (including the Nim compiler), reproducible builds, bisectable Git histories and self-contained projects that don't create dirs/files outside their main directory.

We try to minimise complexity, but we will trade implementation complexity increases for a simpler user experience.

Prerequisites

GNU Make, Bash and the usual POSIX utilities.

Usage

Add this repository to your project as a Git submodule. You can use our handy shell script:

curl -OLs https://raw.githubusercontent.com/status-im/nimbus-build-system/master/scripts/add_submodule.sh
less add_submodule.sh # you do read random Internet scripts before running them, right?
chmod 755 add_submodule.sh
./add_submodule.sh status-im/nimbus-build-system

Or you can do it by hand:

git submodule add https://github.com/status-im/nimbus-build-system.git vendor/nimbus-build-system
# specify a branch
git config -f .gitmodules submodule.vendor/nimbus-build-system.branch master
# hide submodule work tree changes in `git diff`
git config -f .gitmodules submodule.vendor/nimbus-build-system.ignore dirty

Write your own top-level Makefile, taking our "Makefile.superproject.example" as an... example.

See also the Makefiles we wrote for Nimbus, nim-beacon-chain, Stratus, nim-status-client.

Instruct your users to run make update after cloning your project, after a git pull or after switching branches.

Make flags

V

Control the verbosity level. Defaults to 0 for a nice, quiet build.

make V=1 # verbose
make V=2 test # even more verbose

LOG_LEVEL

Set the Chronicles log level to one of: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR, FATAL, NONE.

This Make variable is unset by default, which means that Chronicles' default kicks in (DEBUG in debug builds and INFO in release mode) or some application-specific default takes precedence.

Note that this sets the compile-time log level. If runtime log level selection is implemented (which cannot have larger values than what was set at compile time), additional steps need to be taken to pass the proper command line argument to your binary.

make LOG_LEVEL=DEBUG foo # this is the default
make LOG_LEVEL=TRACE bar # log everything

NIMFLAGS

Pass arbitrary parameters to the Nim compiler. Uses an internal NIM_PARAMS variable that should not be overridden by the user.

make NIMFLAGS="-d:release"

Defaults to Nim parameters mirroring the selected verbosity and log level:

make V=0 # NIMFLAGS="--verbosity:0 --hints:off"
make V=1 LOG_LEVEL=TRACE # NIMFLAGS="--verbosity:1 -d:chronicles_log_level=TRACE"
make V=2 # NIMFLAGS="--verbosity:2"

Projects using this build system may choose to add other default flags like -d:release in their Makefiles (usually those that can't be placed in a top-level "config.nims" or "nim.cfg"). This will be done by appending to the internal variable:

NIM_PARAMS += -d:release

CI_CACHE

Specify a directory where Nim compiler binaries should be cached, in a CI service like AppVeyor:

build_script:
  # the 32-bit build is done on a 64-bit image, so we need to override the architecture
  - mingw32-make -j2 ARCH_OVERRIDE=%PLATFORM% CI_CACHE=NimBinaries update

USE_SYSTEM_NIM

Use the system Nim instead of our shipped version (usually for testing Nim devel versions). Defaults to 0. Setting it to 1 means you're on your own, when it comes to support.

make USE_SYSTEM_NIM=1 test

Make targets

show-deps

Lists all Git submodule URLs, including nested ones.

License

Licensed and distributed under either of

• MIT license: LICENSE-MIT or http://opensource.org/licenses/MIT

or

• Apache License, Version 2.0, (LICENSE-APACHEv2 or http://www.apache.org/licenses/LICENSE-2.0)

at your option. These files may not be copied, modified, or distributed except according to those terms.