project.clj options

Alexander Yakushev edited this page Jul 26, 2015 · 35 revisions

This page contains a detailed description of all project.clj options that are used by lein-droid.

A default project.clj file that gets created with lein droid new ... command has most of the necessary options defined, so the most of the time you won’t have to change lein-droid related attributes much.

You can also explore a sample file which contains example uses of different lein-droid options.

:android

This is where main and most relevant configuration options are. This option should itself be a map, which contents are described below.

:aot

This is similar to Leiningen’s own :aot option. This could either be:

  • a list of namespaces to be AOT-compiled. List can contain strings for exact match, or regular expressions;
  • :all to AOT-compile all used namespaces;
  • :all-with-unused to AOT-compile all namespaces.

:all-with-unused is usually used with :dev profile because you want to have the complete libraries available while you are developing. For :release profile it is better to use :all value because it compiles only those namespaces that are necessary.

:aot-exclude-ns

This should be a list of namespaces not to be AOT-compiled. List can contain strings for exact match, or regular expressions, for example :aot-exclude-ns [#"cljs-tooling\..+"]. This option has priority over :aot — namespaces will be excluded after the include list is calculated.

:assets-paths

The list of directories which contain assets used by your application. By default its value is ["./assets"].

:build-tools-version

By default lein-droid uses the latest version of Android Build Tools from android-sdk-dir/build-tools/. Use this option to force a specific version to be used.

:build-type

If it’s value is :release, lein-droid will perform release-specific operations. This option should be set in the :release profile.

:dex-opts

With this option you can pass additional arguments to dx executable. We usually use it to give more memory to dx and force use of multiple cores when building large projects like this: ["-JXmx4096M" "--num-threads=2"].

:external-classes-paths

This options is a list of directories with classfiles, and JARs that you want to include in your classpath. It is inadvisable to use this option because it makes your project build environment-dependent. Consider deploying your JAR libraries to local Maven repository instead.

:external-res-paths

Directories in which to find additional resources. It is inadvisable to use this option, consider packaging your resource libraries into AARs and using them as dependencies.

:force-dex-optimize

If you still get errors during DEXing, even with increasing memory in :dex-opts, you can set this option to true. This will result in slower DEXing during debug builds but may resolve the issue.

:ignore-log-priority

Setting this parameter to a vector of logging priorities will force the respective logging methods from neko.log namespace to be completely ignored in the build. You can use this parameter, for example, to elide all neko.log/d calls from the release build in compile time.

Available priorities: :verbose, :debug, :info, :warning, :error.

:key-alias

This option should be an alias of your key inside :keystore-path.

You should set this option only for the :release profile, since :dev profile uses special debug key for signing applications.

It is better to set this option in ~/.lein/profiles.clj for better repeatability.

:keypass

This options can contain a password to your key in the private keystore. It is not advised to use this option.

If not set, you will be asked for the password during release build which is a more secure method.

If you still decide to use this option, specify it in ~/.lein/profiles.clj to avoid exposing your password.

:keystore-path

This options should point at a keystore file for signing your release builds. Please consult this guide for more information on keys and application signing.

You should set this option only for the :release profile, since :dev profile uses special debug key for signing applications.

It is better to set this option in ~/.lein/profiles.clj for better repeatability.

:lean-compile

When set to true, lein-droid will compile the application using Skummet. See details and usage specifics here.

:library

This option should be set to true if you are developing a Clojure/Android library that relies on Android SDK to be compiled and built.

:manifest-options

Contains a map that will be passed to Clostache when rendering AndroidManifest.xml template file.

:manifest-template-path

Path to the Mustache template file of project’s manifest file. Defaults to AndroidManifest.template.xml. You can also use a solid AndroidManifest.xml file here instead, if your manifest doesn’t require any templating.

:multi-dex

When set to true, multiple DEX files will be generated for the application. Use this option when you hit the 65k method limit.

:multi-dex-proguard-conf-path

Path to special Proguard configuration file that determines which classes should go to a primary DEX file. An example of such file is generated in build/proguard-minify.cfg.

:native-libraries-paths

A list of native libraries to include into your application.

:proguard-execute

When set to true, lein-droid will minify and optimize the compiled code using Proguard. This option makes sense only with :lean-compile true, because regular Clojure-compiled projects are incompatible with Proguard.

:proguard-conf-path

Path to Proguard configuration file that tells which classes should be kept or removed. An example of such file is generated in build/proguard-minify.cfg.

:rename-manifest-package

This option changes the application package name defined in manifest to the given string. Inside the application package stays the same. This allows to install several versions of the same application onto the device (for instance, have debug and release version simultaneously).

:repl-device-port

This option should be a port number that will be opened by nREPL on the Android device. By default it is set to 9999.

:repl-local-port

This option should be a port number which will be opened on your local machine to access the remote nREPL. By default it is set to 9999.

:res-path

Path to resources folder. By default it is set to ./res.

:resource-jars-paths

A list of JARs which contain resources you want to include into your application. Use this option only to include JVM-style resources (obtainable with clojure.java.io/resource), not the Android-style resources resources (that need a record in R.java). You can also include such resources from :dependencies.

:sdk-path

Its value should be a string that specifies the path to your Android SDK. Its root path is where tools, platform-tools and other directories are.

It is a good idea to set this option in ~/.lein/profiles.clj file, in :android-common profile. This way you won’t have to copy it into every project, and it also make your project contain less environment-specific parts.

:sigalg

If your release keystore uses signing algorithm different from the default SHA1withRSA, you can specify it using this parameter. For example, if your keystore was generated using DSA, you should set this parameter to SHA1withDSA.

:skummet-skip-vars

This option should be a vector of strings that represent Vars which shouldn’t be lean-compiled by Skummet. See an example here.

:start-nrepl-server

Set this option to true if you want to start nREPL server even in release builds of your application. If so, don’t forget to include nrepl dependency in :release profile.

:storepass

This options can contain a password to your private keystore. It is not advised to use this option.

If not set, you will be asked for the password during release build which is a more secure method.

If you still decide to use this option, specify it in ~/.lein/profiles.clj to avoid exposing your password.

:target-version

This option should be a number which specifies the version of Android API you want to target. You can see the mapping between version names and API numbers here.

You can also use a keyword instead of a number for certain SDK versions. Here’s the mapping:

Keyword Version number
:ics 15
:jelly-bean 18
:kitkat 19
:lollipop 21

:use-debug-keystore

Force usage of debug keystore for signing the APK regardless of the :build-type option. Useful to test the release builds without having to enter release keystore credentials.

:dependencies

This options is the same like in every other project.clj, it should contain a vector of dependency definitions. If you want to include JVM-format resources from certain dependency, add :use-resources true to the definition vector, like this:

:dependencies [[org.clojure-android/clojure "1.5.1-SNAPSHOT" :use-resources true]
               ...]

You can also use AAR dependencies here.

There are two main dependencies that are crucial for Clojure/Android development (you can get a working setup without them, but it won’t be much fun). First is org.clojure-android/clojure, which is a special Clojure build that enables dynamic compilation on Android. Apart from that there are no other changes, so consider which version to use the same as you do it for regular Clojure. Most of the time the latest version will do:

https://clojars.org/org.clojure-android/clojure/latest-version.svg

Neko is a primary library for CoA development. It initializes dynamic compilation and provides with various utilities for creating UI and using Android API. You can get Neko from Clojars as well:

https://clojars.org/neko/latest-version.svg

Other dependencies are up to you, lein-droid allows you to use any conventional Clojure libraries in your projects as long as they don’t require any JVM-specific classes (like sun.* package and the like).

:java-only

If this option is set to true, lein-droid will act like a common Android build tool. Use this option for building Java-only AAR libraries.

:profiles

A default project.clj file in a Clojure-Android project contains two profiles: :dev and :release. These two profiles contain options specific to the debug and release builds respectively. For example, :dev profile contains nREPL dependency which release build usually doesn’t need.

For more information check Profiles page. It also explains how to specify system-wide attributes for Clojure-Android projects.

*warn-on-reflection*

This option is highly recommended to be enabled, since reflection on Android is much slower than on JVM, and most initial performance problems with Clojure/Android development come from unnoticed reflection cases. If *warn-on-reflection* is set to true, you will see them during project compilation stage. The option looks like:

:global-vars {*warn-on-reflection* true}