(Quick Reference)
5.6 Customising the build - Reference Documentation
Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith, Lari Hotari
Version: 2.3.8
5.6 Customising the build
Grails is most definitely an opinionated framework and it prefers convention to configuration, but this doesn't mean you
can't configure it. In this section, we look at how you can influence and modify the standard Grails build.
The defaults
The core of the Grails build configuration is the
grails.util.BuildSettings
class, which contains quite a bit of useful information. It controls where classes are compiled to, what dependencies the application has, and other such settings.
Here is a selection of the configuration options and their default values:
Property | Config option | Default value |
---|
grailsWorkDir | grails.work.dir | $USER_HOME/.grails/<grailsVersion> |
projectWorkDir | grails.project.work.dir | <grailsWorkDir>/projects/<baseDirName> |
classesDir | grails.project.class.dir | <projectWorkDir>/classes |
testClassesDir | grails.project.test.class.dir | <projectWorkDir>/test-classes |
testReportsDir | grails.project.test.reports.dir | <projectWorkDir>/test/reports |
resourcesDir | grails.project.resource.dir | <projectWorkDir>/resources |
projectPluginsDir | grails.project.plugins.dir | <projectWorkDir>/plugins |
globalPluginsDir | grails.global.plugins.dir | <grailsWorkDir>/global-plugins |
verboseCompile | grails.project.compile.verbose | false |
The
BuildSettings
class has some other properties too, but they should be treated as read-only:
Property | Description |
---|
baseDir | The location of the project. |
userHome | The user's home directory. |
grailsHome | The location of the Grails installation in use (may be null ). |
grailsVersion | The version of Grails being used by the project. |
grailsEnv | The current Grails environment. |
config | The configuration settings defined in the project's BuildConfig.groovy file. Access properties in the same way as you access runtime settings: grailsSettings.config.foo.bar.hello . |
compileDependencies | A list of compile-time project dependencies as File instances. |
testDependencies | A list of test-time project dependencies as File instances. |
runtimeDependencies | A list of runtime-time project dependencies as File instances. |
Of course, these properties aren't much good if you can't get hold of them. Fortunately that's easy to do: an instance of
BuildSettings
is available to your scripts as the
grailsSettings
script variable. You can also access it from your code by using the
grails.util.BuildSettingsHolder
class, but this isn't recommended.
Overriding the defaults
All of the properties in the first table can be overridden by a system property or a configuration option - simply use the "config option" name. For example, to change the project working directory, you could either run this command:
grails -Dgrails.project.work.dir=work compile
or add this option to your
grails-app/conf/BuildConfig.groovy
file:
grails.project.work.dir = "work"
Note that the default values take account of the property values they depend on, so setting the project working directory like this would also relocate the compiled classes, test classes, resources, and plugins.
What happens if you use both a system property and a configuration option? Then the system property wins because it takes precedence over the
BuildConfig.groovy
file, which in turn takes precedence over the default values.
The
BuildConfig.groovy
file is a sibling of
grails-app/conf/Config.groovy
- the former contains options that only affect the build, whereas the latter contains those that affect the application at runtime. It's not limited to the options in the first table either: you will find build configuration options dotted around the documentation, such as ones for specifying the port that the embedded servlet container runs on or for determining what files get packaged in the WAR file.
Available build settings
Name | Description |
---|
grails.server.port.http | Port to run the embedded servlet container on ("run-app" and "run-war"). Integer. |
grails.server.port.https | Port to run the embedded servlet container on for HTTPS ("run-app --https" and "run-war --https"). Integer. |
grails.config.base.webXml | Path to a custom web.xml file to use for the application (alternative to using the web.xml template). |
grails.compiler.dependencies | Legacy approach to adding extra dependencies to the compiler classpath. Set it to a closure containing "fileset()" entries. These entries will be processed by an AntBuilder so the syntax is the Groovy form of the corresponding XML elements in an Ant build file, e.g. fileset(dir: "$basedir/lib", includes: "**/*.class") . |
grails.testing.patterns | A list of Ant path patterns that let you control which files are included in the tests. The patterns should not include the test case suffix, which is set by the next property. |
grails.testing.nameSuffix | By default, tests are assumed to have a suffix of "Tests". You can change it to anything you like but setting this option. For example, another common suffix is "Test". |
grails.project.war.file | A string containing the file path of the generated WAR file, along with its full name (include extension). For example, "target/my-app.war". |
grails.war.dependencies | A closure containing "fileset()" entries that allows you complete control over what goes in the WAR's "WEB-INF/lib" directory. |
grails.war.copyToWebApp | A closure containing "fileset()" entries that allows you complete control over what goes in the root of the WAR. It overrides the default behaviour of including everything under "web-app". |
grails.war.resources | A closure that takes the location of the staging directory as its first argument. You can use any Ant tasks to do anything you like. It is typically used to remove files from the staging directory before that directory is jar'd up into a WAR. |
grails.project.web.xml | The location to generate Grails' web.xml to |
Reloading Agent Cache Directory
Grails uses an agent based reloading system in the development environment that allows source code changes to be picked up while the application is running. This reloading agent caches information needed to carry out the reloading efficiently. By default this information is stored under
<USER_HOME_DIR>/.grails/.slcache/
. The
GRAILS_AGENT_CACHE_DIR
environment variable may be assigned a value to cause this cache information to be stored somewhere else. Note that this is an operating system environment variable, not a JVM system property or a property which may be defined in
BuildConfig.groovy
. This setting must be defined as an environment variable because the agent cache directory must be configured very early in the JVM startup process, before any Grails code is executed.