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. Boot being a self-documented toolchain, you can query the environment variables that Boot understands by invoking boot -h on the command line.

•      `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).
  

•      `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
  

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:

$ boot -V > boot.properties

On the other hand, if you want to force a Boot version globally, you can do it with environment variables, like this:

BOOT_VERSION=xxx BOOT_CLOJURE_VERSION=yyy boot -u

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

Now remember, every boot -uinvocation will revert to the defaults, which consist in the latest Boot core libraries and the current stable Clojure release. If you want to make a global change that will survive a boot upgrade, use environment variables. For example, in your shell init:

export BOOT_CLOJURE_VERSION=1.7.0-RC1

Note: Editing boot.properties by hand isn't recommended because it needs to have both BOOT_CLOJURE_VERSION and BOOT_VERSION and it needs to be a valid properties file. (Redirecting the output of boot -V is recommended)

Precedence rules: Environment variables override boot.properties.

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 project

profile.boot and build.boot configure your Clojure project, they impact the program that runs once clojure is bootstrapped. profile.boot is a global configuration file that lives in BOOT_HOME, which defaults to ~/.boot. As of 2.5.0, a profile.boot is allowed in the root of your project. This 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.

Precedence rules: profile.boot and build.boot are concatenated. Anything you do in profile.boot will be evaluated before the expressions in build.boot, so the expressions in build.boot can override, redef, etc anything done in profile.boot.

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.