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.8.0).
• BOOT_CLOJURE_NAME The Maven identifier to use instead of org.clojure/clojure.
• BOOT_HOME Directory where boot stores global state (~/.boot).
• BOOT_FILE Build script name (build.boot).
• BOOT_JVM_OPTIONS Specify JVM options. (*note)
• 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 Jul 13 12:54:08 PDT 2016
BOOT_CLOJURE_NAME=org.clojure/clojure
BOOT_CLOJURE_VERSION=1.8.0
BOOT_VERSION=2.6.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.9.0-alpha10

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

The earliest version of Clojure supported by Boot is 1.6.0.

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

Configuring stack trace display

Boot uses pretty to print exceptions and stack traces. As of Boot 2.7.0, pretty prints stack traces "upside down". That is, the root exception appears at the top of the stack trace instead of at the bottom. To restore the old stack frame printing order, you can add this to your $BOOT_HOME/.profile.boot (normally ~/.boot/profile.boot):

(alter-var-root
 #'boot.from.io.aviso.exception/*traditional*
 (constantly true))

Boot 2.7.0 offers finer-grained control of the formatting and coloring of exceptions. For example, to print exception messages in a normal font instead of italics, you could add this to your ~/.boot/profile.boot:

(alter-var-root
 #'boot.from.io.aviso.exception/*fonts*
 assoc :message boot.from.io.aviso.ansi/white-font)

Note about BOOT_JVM_OPTIONS & BOOT_JAVA_COMMAND

With Boot versions 2.8.0+ those fields are also read from boot.properties files. In older versions you need to specify them as system enviroment variables (e.g. export BOOT_JVM_OPTIONS=-client).

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.