(Quick Reference)
4.5 Personalizar la construcción - Reference Documentation
Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith
Version: null
4.5 Personalizar la construcción
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 |
Grails es definitivamente un framework opinionado y prefiere la convención sobre la configuración, pero esto no significa que no se pueda configurar. En esta sección, veremos cómo puede influir y modificar el la construcción estándar de Grails.
Los valores predeterminados
El núcleo de la configuración de la construcción de Grails es la clase
grails.util.BuildSettings, que contiene bastante información útil. Controla donde se guardan las clases se compiladas, que dependencias tiene la aplicación, y otros ajustes como estos.
He aquí una selección de las opciones de configuración y sus valores predeterminados:
| Propiedad | Opción de configuración | Valor por defecto |
|---|
| 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. |
La clase
BuildSettings también tiene algunas otras propiedades, pero deben ser tratados como de sólo lectura:
| Propiedad | Descripción |
|---|
| baseDir | La ubicación del proyecto. |
| userHome | Directorio principal del usuario. |
| grailsHome | La ubicación de la instalación de Grails en uso (puede ser null). |
| grailsVersion | La versión de Grails utilizada por el proyecto. |
| grailsEnv | El entorno actual de Grails. |
| compileDependencies | Una lista de dependencias del proyecto en tiempo de compilación como instancias de File. |
| testDependencies | Una lista de dependencias del proyecto en tiempo de pruebas como instancias de File. |
| runtimeDependencies | Una lista de dependencias del proyecto en tiempo de ejecución como instancias de File. |
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
Por supuesto, estas propiedades no sirven para nada si no se puede conseguir accceso a ellas. Afortunadamente eso es fácil de hacer: una instancia de
BuildSettings está disponible para tus scripts como la variable
grailsSettings. También se puede acceder desde el código mediante el uso de la clase
grails.util.BuildSettingsHolder, pero esto no es recomendable.
Sobreescribiendo los valores predeterminados
Todas las propiedades de la primera tabla se pueden sobreescribir por una propiedad del sistema o una opción de configuración, simplemente usar el nombre de "opción de configuración". Por ejemplo, para cambiar el directorio de trabajo del proyecto, podría ejecutar este comando:
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.
o añadir esta opción al archivo
grails-app/conf/BuildConfig.groovy:
grails.project.work.dir = "work"
Tenga en cuenta que los valores predeterminados influyen también en las propiedades de las que dependen, así que establecer el directorio de trabajo del proyecto también modifica la ubicación de las clases compiladas, las clasese de prueba, recursos y plugins.
¿Qué ocurre si se utilizan una propiedad del sistema y una opción de configuración? En ese caso, la propiedad del sistema gana porque prevalece sobre el archivo
BuildConfig.groovy, que a su vez tiene prioridad sobre los valores predeterminados.
El archivo
BuildConfig.groovy es un hermano de
grails-app/conf/Config.groovy: la primera contiene opciones que sólo afectan a la construcción, mientras que el segundo contiene opciones que afectan a la aplicación en tiempo de ejecución. No se limita sólo a las opciones de la primera tabla: encontrará las opciones de configuración de generación en esta documentación, como las necesarias para especificar el puerto que se ejecuta el contenedor de servlet embebido o para determinar qué archivos se empaquetan en el archivo WAR.
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 |
Configuración de construcción disponible
| Nombre | Descripción |
|---|
| grails.Server.Port.http | Puerto para ejecutar el contenedor de servlet embebido ("run-app" y "run-war"). Entero. |
| grails.Server.Port.https | Puerto para ejecutar el contenedor de servlet embebido bajo HTTPS ("run-app --https" y "run war --https"). Entero. |
| grails.config.base.webXml | Ruta del archivo web.xml personalizada para utilizar para la aplicación (alternativa al uso de la plantilla de web.xml). |
| grails.compiler.dependencies | Enfoque heredado para agregar dependencias adicionales a los classpath del compilador. Establézcalo en una closure que contenga las entradas "fileset()". Estas entradas serán procesadas por un AntBuilder por lo que la sintaxis es la forma Groovy de los correspondientes elementos XML en un fichero de construcción Ant, por ejemplo, fileset(dir: "$basedir/lib", include: "**/*.class). |
| grails.testing.Patterns | Una lista de patrones de rutas Ant que le permiten controlar qué archivos se incluyen en las pruebas. Los patrones no deben incluir el sufijo de caso de prueba, se establece mediante la propiedad siguiente. |
| grails.testing.nameSuffix | Por defecto, las pruebas se supone que tienen un sufijo de "Tests". Puede cambiarlo a cualquier cosa que le guste asignando esta opción. Por ejemplo, otro sufijo común es "Test". |
| grails.project.war.File | Una cadena que contiene la ruta del archivo WAR generado, junto con su nombre completo (incluye extensión). Por ejemplo, "target/my-app.war". |
| grails.war.dependencies | Una closure que contiene las entradas "fileset()" que permite un control total sobre lo que pasa en el directorio de "WEB-INF/lib" del WAR. |
| grails.war.copyToWebApp | Una closure que contiene las entradas "fileset()" que permite un control total sobre lo que pasa en la raíz del WAR. Reemplaza el comportamiento predeterminado de incluir todo bajo "web-app". |
| grails.war.resources | Una closure que toma la ubicación del directorio provisional (staging) como primer argumento. Puede utilizar cualquier tarea de Ant para hacer cualquier cosa que le guste. Normalmente se utiliza para eliminar archivos del directorio provisional antes de ese directorio jar se incluya en un WAR. |
| grails.project.web.xML | La ubicación en la que se generará el fichero web.xml. |