(Quick Reference)
4.5 自定义构建 - Reference Documentation
Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith
Version: null
4.5 自定义构建
Grails无疑是一个固执己见框架,并且它喜欢按照约定来进行配置,但这并不意味着你 不能 去配置它。在本章,我们将看到你可以如何去影响和修改标准的Grails构建。
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.
默认
Grails构建配置的核心就是
grails.util.BuildSettings 类,它包含了大量有用的信息。它控制了哪些类被编译、应用程序依赖什么以及其他类似的设置。
以下是一个配置选项和它们的默认值的集录:
| 属性 | 配置选项 | 默认值 |
|---|
| 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 |
BuildSettings 类也有一些其他属性,但是它们应该被只读处理:
| 属性 | 描述 |
|---|
| baseDir | 项目的位置。 |
| userHome | 用户的主目录。 |
| grailsHome | 正在使用的Grails的安装位置(也许为null)。 |
| grailsVersion | 被项目使用的Grails的版本。 |
| grailsEnv | 当前的Grails环境。 |
| compileDependencies | 编译时项目依赖的文件实例列表。 |
| testDependencies | 测试时项目依赖的文件实例列表。 |
| runtimeDependencies | 运行时项目依赖的文件实例列表。 |
当然,如果你不能获得这些属性那么它们并没有多好。幸运的是这很容易实现:通过
grailsSettings脚本变量可以得到一个
BuildSettings实例用于你的脚本。你也可以在你的代码中通过使用
grails.util.BuildSettingsHolder类来访问它,但是并不推荐这样做。
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. |
| 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.
覆盖默认值
所有在第一个表中的属性都可以被一个系统属性或配置选项所覆盖——简单地使用“config option”名称。例如,要改变项目工作目录,你可以运行这个命令:
grails -Dgrails.project.work.dir=work compile
或者将这个选项添加到你的
grails-app/conf/BuildConfig.groovy 文件中:
grails.project.work.dir = "work"
注意默认值带有许多它们依赖的属性值,因此像这样设置项目工作目录也将迁移编译好的类、测试类、资源和插件。
如果你同时使用系统属性和配置选项将发生什么?当然是系统属性被采用了,因为它优先于
BuildConfig.groovy 文件,而后者优先于默认值。
BuildConfig.groovy 文件是
grails-app/conf/Config.groovy 的姐妹文件,——过去包含的选项仅仅影响构建,但是之后包含的就影响正在运行的应用程序了。这并不局限于第一个表中的选项:你会发现构建配置选项在文档中到处都是,比如其中一些就用来指定内嵌的servlet容器应该运行在哪个端口上或者决定哪些文件应该被打包到WAR文件中。
可用的构建设置
| 名称 | 描述 |
|---|
| grails.server.port.http | 指定内嵌的servlet容器应该运行的端口(“run-app”和“run-war”命令使用)。整型。 |
| grails.server.port.https | 指定内嵌的servlet容器用于HTTPS的运行端口 ("run-app --https" and "run-war --https"). 整型. |
| grails.config.base.webXml | 指定用于应用程序的自定义web.xml文件的路径(取代使用web.xml模板)。 |
| grails.compiler.dependencies | 将额外的依赖添加到编译器classpath的传统方式。设置它到一个包含“fileset()”入口的闭包。 这些入口将被一个AntBuilder处理,所以这些入口的语法是以Groovy的形式出现,对应着Ant构建文件的XML元素,例如: fileset(dir: "$basedir/lib", include: "**/*.class). |
| grails.testing.patterns | 一个Ant路径格式的列表,允许你控制哪些文件可以被包含在测试中。这些格式不应该包括测试用例后缀,它们将在下一个属性中设置。 |
| grails.testing.nameSuffix | 默认的,测试类都假定有一个“Tests”的后缀。你可以设置这个选项来改变它为你想要的任何内容。例如:另一个公共后缀是“Test”。 |
| grails.project.war.file | 一个包含了生成的WAR文件的文件路径的字符串,除了它的全名意外(包括扩展名)。例如,“target/my-app.war”。 |
| grails.war.dependencies | 一个包含“fileset()”入口的闭包,它允许你完全控制什么内容可以被放入WAR文件的“WEB-INF/lib”目录中。 |
| grails.war.copyToWebApp | 一个包含“fileset()”入口的闭包,它允许你完全控制什么内容可以被放入WAR文件的根目录中。它覆盖了包含“web-app”目录下所有内容的那种默认习惯。 |
| grails.war.resources | 一个闭包,用临时目录的地址作为它的第一个参数。你可以使用任何Ant任务来做你想做的任何事。这通常用来在临时目录被打包成WAR之前从中删除文件。 |
| grails.project.web.xml | 生成Grails的web.xml的位置 |
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", include: "**/*.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 |