Configuring Boot

Configuring Boot (and your project)

It is useful to distinguish two sets of orthogonal concerns while talking about Boot configuration: configuring Boot itself vs configuring your Clojure project (that Boot is going to instrument).

tl;dr Boot itself is configured with environment variables, while your Clojure project is configured with build.boot.

Configuring Boot means controlling the JVM environment before your project is loaded. Configuring your Clojure project means declaring dependencies, specifying which tasks to run, etc. Environment variables and boot.properties are used in the first case, profile.boot and build.boot in the latter.

Configuring Boot itself

Configuring the Java environment that bootstraps Clojure is done via environment variables, JVM system properties, and/or properties files. Boot being a self-documented toolchain, you can query the environment variables and properties files that Boot understands by invoking boot -h on the command line.

Some interesting environment variables / system properties:

•      `BOOT_AS_ROOT`               Set to 'yes' to allow boot to run as root.
  

•      `BOOT_CLOJURE_VERSION`       The version of Clojure boot will provide (1.6.0).
  

•      `BOOT_HOME`                  Directory where boot stores global state (~/.boot).
  

•      `BOOT_FILE`                  Build script name (build.boot).
  

•      `BOOT_JVM_OPTIONS`           Specify [[JVM options|JVM Options]] (Unix/Linux/OSX only). ([*note](#note-about-boot_jvm_options))
  

•      `BOOT_LOCAL_REPO`            The local Maven repo path (~/.m2/repository).
  

•      `BOOT_VERSION`               Specify the version of boot core to use.
  

•      `BOOT_COLOR`                 Turn colorized output on or off
  

And the properties files:

•      `BOOT_HOME/boot.properties`  The global configuration file.
  

•      `./boot.properties`          The local project configuration.
  

And a .bootignore file:

•      `./.bootignore`              Analogous to .gitignore
  

The environment is configured with the following precedence, from highest to lowest:

1. system properties
2. environment variables
3. ./boot.properties file
4. BOOT_HOME/boot.properties file

For example, if you set BOOT_COLOR in the JVM system properties it will override settings in environment variables and properties files.

A special case that belongs in our Boot configuration chapter is when you want to pin your project to a specific Boot version. This is covered in depth here, but in a nutshell (in the project directory):

$ boot -V > boot.properties

On the other hand, if you want to force a Boot version globally, you can edit the BOOT_HOME/boot.properties file:

cat ~/.boot/boot.properties

#http://boot-clj.com
#Wed Dec 16 11:17:32 EST 2015
BOOT_EMIT_TARGET=no
BOOT_CLOJURE_NAME=org.clojure/clojure
BOOT_CLOJURE_VERSION=1.7.0
BOOT_VERSION=2.5.0

For example, you might want to downgrade BOOT_VERSION, or you might want to upgrade BOOT_CLOJURE_VERSION to a release candidate. Boot will look for those global settings in ~/.boot/boot.properties.

Alternatively, You could set an environment variable in your ~/.bashrc file:

export BOOT_CLOJURE_VERSION=1.7.0-RC1

As described above, environment variables override settings in boot.properties files.

.bootignore controls construction of the initial boot-fileset. Files matching the regexes in .bootignore will be excluded. For example, to ignore emacs backup files, .bootignore should contain .*~$. To ignore transient emacs files, add ^\.# and /\.#.

The comment character is #. The file should go in the project root directory.

Note about BOOT_JVM_OPTIONS

Since BOOT_JVM_OPTIONS is used to launch the initial java process, it must be specified as a system environment variable (e.g. export BOOT_JVM_OPTIONS=-client), not in a boot.properties file.

On CI servers

Many existing CI services (CircleCI for example), have limits on the amount of memory available to projects. In some cases, Boot may exceed these limits and/or be automatically terminated, especially when fetching dependencies.

To avoid this issue, first check with your provider as to memory limits, and then provide BOOT_JVM_OPTIONS to suit. For example, CircleCI has a limit of 4 gigabytes—to configure Boot to not exceed that limit, set a conservative limit like so:

BOOT_JVM_OPTIONS="-Xmx2g"

Configuring Your Clojure Project

The profile.boot and build.boot scripts are programs that configure your Clojure project. They impact the program that runs once clojure is bootstrapped.

They are evaluated in the following order:

1. BOOT_HOME/profile.boot
2. ./profile.boot
3. ./build.boot

They are evaluated in the same namespace and environment, so things you define in say BOOT_HOME/profile.boot are visible to expressions in ./profile.boot and ./build.boot, for example. Expressions that are evaluated later can override, redef, etc. anything done in scripts that were evaluated earlier.

The project-local profile.boot script can be useful when you have project-specific configuration that you don't want to keep in version control. Credentials, configuration that is not shared with the team, etc.

boot-shim.clj (Here be dragons)

This can be used to modify how boot works at the lowest levels, in every pod. For example, we could change the default repositories that boot uses to load itself during bootstrapping by creating a boot-shim.clj file either in the BOOT_HOME or the current working directory with the following contents:

    (try (require 'boot.aether)
         (eval '(reset! boot.aether/default-repositories
                        [["public"  {:url "http://repo.local/public/"}]
                         ["private" {:url "http://repo.local/private/"}]]))
         (catch Throwable _))

This file will be evaluated via clojure.core/load-file in each Clojure runtime that's created (all pods, including the main one in which the build.boot runs). Clojure core will be available but no boot-related code will have been loaded or run yet.

So you can use it to patch clojure core if you want or basically override anything in clojure or boot by doing alter-var-root, etc.