Articles are a practical way to provide additional guidance beyond
API documentation. Please refer to the documentation to learn more about using them.

Namespaces

We couldn't find any namespaces in this artifact. Most often the reason for this is
that the analysis failed or that the artifact has been mispackaged and does not
contain any Clojure source files. The latter might be on purpose for uber-module
style artifacts. Please open
an issue and we'll be happy to look into it.

Boot is a Clojure build framework and ad-hoc Clojure script evaluator. Boot provides a runtime environment that includes all of the tools needed to build Clojure projects from scripts written in Clojure that run in the context of the project.

Build processes for applications always end up being complex things. A simple web application, for instance, may require many integrations–asset pipelines, deployment to different environments, the compilation of multiple artifacts with different compilers, packaging, etc.

The more complex the build process becomes, the more flexible the build tool needs to be. Static build specifications become less and less useful as the project moves toward completion. Being Lispers we know what to do: Lambda is the ultimate declarative.

Instead of building the project based on a global configuration map, boot provides a runtime environment in which a build script written in Clojure can be evaluated. It is this script—a Turing-complete build specification—which builds the project.

You should see the boot manual page printed to the terminal. This information includes command line options recognized by boot, a list of available tasks, and other information about relevant configuration files and environment variables.

You can also get help for a specific task, for example the repl task:

boot repl -h

You should see usage info and command line options for the specified task.

This was specified on the command line as the -r or --resource-paths and -d or --dependencies arguments to boot itself. These translate to calls to set-env! in the REPL or in a script. Note that the keyword always corresponds to the long option from the command line.

It gets tedious to specify all of those options on the command line or in the REPL every time you build your project. Boot provides facilities for setting task options globally, with the ability to override them by providing options on the command line or in the REPL later.

Now we can build the project without specifying these options, because the task functions have been replaced with curried versions of themselves:

boot.user=> (boot (pom) (jar) (install))

Individual options can still be set by providing arguments to the tasks such that they override those set with task-options!. Let's build our project with a different version number, for example:

boot.user=> (boot (pom :version "0.1.1") (jar) (install))

Pretty simple, right? This way of setting options requires no participation by the tasks themselves. There is no global configuration map or anything like that. It works because tasks accept only keyword arguments, so partial application is idempotent and last setting wins.

Custom tasks can be defined in the project or in build.boot. This is generally how boot is expected to be used, in fact. Boot ships with a selection of small tasks that can be composed uniformly, and the user assembles them into something that makes sense for the specific project.

As an example let's make a task that performs the last example above, and name it build. We'll modify build.boot such that it contains the following:

Now we should be able to see the build task listed among the available tasks in the output of boot -h, and we can run the task from the command line as we would run any other task:

boot build

Tasks are functions that return pipelines. Pipelines compose functionally to produce new pipelines. If you've used transducers or ring middleware this pattern should be familiar. The pom and install functions we used in the definition of build are, in fact, the same functions that were called when we used them on the command line before. Boot's command line parsing implicitly composes them; in our task we compose them using Clojure's comp function.

Code from other projects was incorporated into boot wherever necessary to eliminate external dependencies of boot itself. This ensures that the project classpath remains pristine and free from potential dependency conflicts. We've pulled in code from the following projects (thanks, guys!)