From c187a59e85c7d79e754f0bd96704840742b291fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C8=98tefan=20Talpalaru?= Date: Fri, 12 Jun 2020 01:07:05 +0200 Subject: [PATCH] document user-facing Make variables and add an example superproject Makefile --- Makefile.superproject.example | 56 +++++++++++++++++ README.md | 115 +++++++++++++++++++++++++++++++++- 2 files changed, 170 insertions(+), 1 deletion(-) create mode 100644 Makefile.superproject.example diff --git a/Makefile.superproject.example b/Makefile.superproject.example new file mode 100644 index 0000000..f30a7b5 --- /dev/null +++ b/Makefile.superproject.example @@ -0,0 +1,56 @@ +SHELL := bash # the shell used internally by "make" + +# used inside the included makefiles +BUILD_SYSTEM_DIR := vendor/nimbus-build-system + +# we don't want an error here, so we can handle things later, in the ".DEFAULT" target +-include $(BUILD_SYSTEM_DIR)/makefiles/variables.mk + +.PHONY: \ + all \ + deps \ + update \ + foo \ + bar \ + clean + +ifeq ($(NIM_PARAMS),) +# "variables.mk" was not included, so we update the submodules. +GIT_SUBMODULE_UPDATE := git submodule update --init --recursive +.DEFAULT: + +@ echo -e "Git submodules not found. Running '$(GIT_SUBMODULE_UPDATE)'.\n"; \ + $(GIT_SUBMODULE_UPDATE) && \ + echo +# Now that the included *.mk files appeared, and are newer than this file, Make will restart itself: +# https://www.gnu.org/software/make/manual/make.html#Remaking-Makefiles +# +# After restarting, it will execute its original goal, so we don't have to start a child Make here +# with "$(MAKE) $(MAKECMDGOALS)". Isn't hidden control flow great? + +else # "variables.mk" was included. Business as usual until the end of this file. + +# default target, because it's the first one that doesn't start with '.' +all: | foo bar + +# must be included after the default target +-include $(BUILD_SYSTEM_DIR)/makefiles/targets.mk + +# add a default Nim compiler argument +NIM_PARAMS += -d:release + +deps: | deps-common + # Have custom deps? Add them above. + +update: | update-common + # Do you need to do something extra for this target? + +# building Nim programs +foo bar: | build deps + echo -e $(BUILD_MSG) "build/$@" && \ + $(ENV_SCRIPT) nim c -o:build/$@ $(NIM_PARAMS) "$@.nim" + +clean: | clean-common + rm -rf build/{foo,bar} + +endif # "variables.mk" was not included + diff --git a/README.md b/README.md index 5d76fd7..4605bc6 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,125 @@ # 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: + +```bash +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: + +```bash +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](./Makefile.superproject.example)" as an... +example. + +See also the Makefiles we wrote for +[Nimbus](https://github.com/status-im/nimbus/), +[nim-beacon-chain](https://github.com/status-im/nim-beacon-chain), +[Stratus](https://github.com/status-im/nim-stratus/blob/master/Makefile), +[nim-status-client](https://github.com/status-im/nim-status-client). + +Instruct your users to run `make update` after cloning your project, after a +`git pull` or after switching branches. + ## Make flags -* use the system Nim instead of the shipped version (usually for testing Nim devel versions) +### V + +Control the verbosity level. Defaults to 0 for a nice, quiet build. + +```bash +make V=1 # verbose +make V=2 test # even more verbose +``` + +### LOG_LEVEL + +Set the [Chronicles log +level](https://github.com/status-im/nim-chronicles#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. + +```bash +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. + +```bash +make NIMFLAGS="-d:release" +``` + +Defaults to Nim parameters mirroring the selected verbosity and log level: + +```bash +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: + +```make +NIM_PARAMS += -d:release +``` + +### CI_CACHE + +Specify a directory where Nim compiler binaries should be cached, in a CI service like AppVeyor: + +```yml +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`