document user-facing Make variables

and add an example superproject Makefile

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
+

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`