At a minimum, the build.boot file for a GAE webapp must include a dependency for Clojure, for the Appengine Java SDK, and for boot-gae. In addition, if you want to use GAE services (e.g. the datastore), you must include the appropriate API jar. For example:

The purpose of the GAE Java SDK dependency is just to make sure it gets downloaded (its enormous so it takes a long time). The install-sdk task will explode the downloaded zip file to :sdk-root (default: ~/.appengine), and at runtime the devserver will look there for the jars it needs.

The initial boot fileset is determined by the :asset-paths, :resource-paths, and :source-paths keys in the set-env! directive in build.boot. See Boot Environment and Filesets on the boot wiki for details.

The important thing to understand is that putting directories in these lists causes the files they contain to be added to the initial fileset, and marks them with INPUT and OUTPUT flags (boot calls these "roles", see Filesets) as follows:

A detailed explanation of how boot works is beyond the scope of this document, but at a minimum you need to know that only files marked +OUTPUT will be written out to the target directory by the built-in target task; files marked with ‑OUTPUT (i.e. files found in :source-paths) will not be written out. You can see this in action by running

in any directory containing a build.boot file. The show -f task will print all the files in the initial fileset (although it will not indicate their INPUT/OUTPUT "roles"), and the target task will write the +OUTPUT files to the output directory ("target/" by default). So if you put e.g. src/clj in the :source-paths list, they will not be copied to the output directory. The implicit assumption is that source files are there to be transformed (compiled). If you want source files to be copied rather than transformed, you can use the sift task. boot-gae handles this sort of thing automatically, so you should put your Clojure source files in :source-paths.

Similarly, the implicit assumption with respect to files in :asset-paths and :resource-paths is that the former are there to be copied to the output directory without transformation, and the latter are there to be copied to the output directory and possibly transformed.

However, boot tasks have to power to finesse things; they can move files to and from these "roles", for example. Some boot-gae tasks do this.

With the above in mind here’s how boot-gae tasks treat the fileset:

GAE webapps require at least two XML configuration files, WEB-INF/web.xml and WEB-INF/appengine-web.xml. The former configures your webapp; the latter configures appengine.

boot-gae generates these files automatically from .edn files.

Your app may also include several other XML configuration files, depending on which GAE facilities you use:

See also Organizing xml Configuration Files.

boot-gae does not currently provide any direct support for these files; to use them, create them in your :resource-paths, e.g.

"" XML files!? We don' need no stinkin XML files! ""

The dev server will automatically reload appengine-web.xml if it changes, but unfortunately the same cannot be said for web.xml. If you change it - that is, if you make changes to your configuration files that would changes web.xml you’ll need to rebuild the app and reboot the devserver.

Note that the sample apps put filter source code in filters/ rather than src/clj/, and add that path to the :resource-paths list in build.boot. So e.g. filters/hello_filter.clj will be copied to target/WEB-INF/classes/hello_filter.clj. This makes the namespaces single-level, e.g. filters/hello_filter.clj has namespace hello-filter, not filters/hello-filter.

The class file corresponding to this implementation file must be configured in filters.edn, which the sample code puts in config/, which is put in :source-paths.

You don’t have to follow this convention; I use it just because I prefer to treat filters as separate from application code and have them at the root of the classes hierarcy..

The App Engine functions as a servlet container (it’s actually a modified version of Jetty). Servlet containers look on disk for compiled byte code when they need to load a servlet. That means a Clojure webapp must aot-compile a servlet; usually this is done using gen-class in some form.

You will notice that gen-class is nowhere to be found the Clojure source code of this app. That’s because it depends on the boot-gae task library, which contains a servlets task that uses data in the servlets.edn config file to generate the appropriate gen-class code and aot-compiles it at build time. You only have to do that once, unless you change the servlet configuration in build.boot.

The generated code looks like the following:

By default, this code is not retained; once the AOT compile is finished, this source code is discarded. You can modify this by passing -k (keep) to the servlets task.

Note that the generated class extends HttpServlet, which is an abstract class. You will have to implement at least one of its methods. The example uses the defservice macro of the ring.util.servlet component of ring. That macro creates a -service function in the implementation namespace. When the Servlet Container invokes the service method of the AOT-compiled servlet, the generated code will forward the call to the -service function.

This is of course not the only possible technique we could use to implement servlets in Clojure. boot-gae could easily be extended to suppport alternative mechanisms, but this one seems to work pretty well.

The servlet specifications in servlets.edn are also used (by the webxml task) to generate the web.xml configuration file needed by the servlet container.

"Apache Log4j 2 is an upgrade to Log4j that provides significant improvements over its predecessor, Log4j 1.x,…​"

References:

TODO: --jvm_flag="-Dlog4j.configuration=log4j.props"

You’ll use the dev server from the SDK to test locally. Running $ boot gae/run gives:

Notice that the classpath is empty. The dev server runs in its own JVM, and sets the classpath to include only the SDK jars needed plus the jars in WEB-INF/lib, plus the files in WEB-INF/classes.

Local Unit Testing for Java

To run tests using GAE services like memcache and datastore, add the following dependencies, scoped to "test", to your build.boot:

A GAE webapp requires an app id and version. Your source project will have a project name and version. You must specify these separately in your build.boot file. The app id will probably be different than the project name, since the latter may be namespaced, and a GAE app id must follow a different grammar. You set the app id when you register your app in Google’s Cloud Platform console. Your project version will most likely conform to Clojure standard practice, something like 0.1.0, or 0.1.0-SNAPSHOT. GAE version strings must conform to a fairly restrictive grammar: "The version identifier can contain lowercase letters, digits, and hyphens. It cannot begin with the prefix "ah-" and the names "default" and "latest" are reserved and cannot be used."

You can use Clojure version strings for your app version. boot-gae will lowercase it, translate "." to "-", and since "-SNAPSHOT" is for source code rather than running apps, it will be stripped from the version string.

Furthermore, Google recommends that version strings begin with a lowercase letter, to make sure that version strings are not confused with instance numbers. (See About appengine-web.xml). So boot-gae will prepend "r" to your version string.

For example, if your project version string is 0.1.0-SNAPSHOT, then your gae app version string will be r-0-1-0.