document user-facing Make variables

and add an example superproject Makefile
This commit is contained in:
Ștefan Talpalaru 2020-06-12 01:07:05 +02:00
parent 34a884e1cf
commit c187a59e85
No known key found for this signature in database
GPG Key ID: CBF7934204F1B6F9
2 changed files with 170 additions and 1 deletions

View File

@ -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

115
README.md
View File

@ -1,12 +1,125 @@
# Common parts of the build system used by Nimbus and related projects # 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 ## Prerequisites
GNU Make, Bash and the usual POSIX utilities. 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 ## 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` `make USE_SYSTEM_NIM=1 test`