(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:

PropertyConfig optionDefault value
grailsWorkDirgrails.work.dir$USER_HOME/.grails/<grailsVersion>
projectWorkDirgrails.project.work.dir<grailsWorkDir>/projects/<baseDirName>
classesDirgrails.project.class.dir<projectWorkDir>/classes
testClassesDirgrails.project.test.class.dir<projectWorkDir>/test-classes
testReportsDirgrails.project.test.reports.dir<projectWorkDir>/test/reports
resourcesDirgrails.project.resource.dir<projectWorkDir>/resources
projectPluginsDirgrails.project.plugins.dir<projectWorkDir>/plugins
globalPluginsDirgrails.global.plugins.dir<grailsWorkDir>/global-plugins
verboseCompilegrails.project.compile.verbosefalse

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:

PropiedadOpción de configuraciónValor por defecto
grailsWorkDirgrails.work.dir$USER_HOME/.grails/<grailsVersion>
projectWorkDirgrails.project.work.dir<grailsWorkDir>/projects/<baseDirName>
classesDirgrails.project.class.dir<projectWorkDir>/classes
testClassesDirgrails.project.test.class.dir<projectWorkDir>/test-classes
testReportsDirgrails.project.test.reports.dir<projectWorkDir>/test/reports
resourcesDirgrails.project.resource.dir<projectWorkDir>/resources
projectPluginsDirgrails.project.plugins.dir<projectWorkDir>/plugins
globalPluginsDirgrails.global.plugins.dir<grailsWorkDir>/global-plugins
verboseCompilegrails.project.compile.verbosefalse

The BuildSettings class has some other properties too, but they should be treated as read-only:

PropertyDescription
baseDirThe location of the project.
userHomeThe user's home directory.
grailsHomeThe location of the Grails installation in use (may be null).
grailsVersionThe version of Grails being used by the project.
grailsEnvThe current Grails environment.
compileDependenciesA list of compile-time project dependencies as File instances.
testDependenciesA list of test-time project dependencies as File instances.
runtimeDependenciesA 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:

PropiedadDescripción
baseDirLa ubicación del proyecto.
userHomeDirectorio principal del usuario.
grailsHomeLa ubicación de la instalación de Grails en uso (puede ser null).
grailsVersionLa versión de Grails utilizada por el proyecto.
grailsEnvEl entorno actual de Grails.
compileDependenciesUna lista de dependencias del proyecto en tiempo de compilación como instancias de File.
testDependenciesUna lista de dependencias del proyecto en tiempo de pruebas como instancias de File.
runtimeDependenciesUna 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

NameDescription
grails.server.port.httpPort to run the embedded servlet container on ("run-app" and "run-war"). Integer.
grails.server.port.httpsPort to run the embedded servlet container on for HTTPS ("run-app --https" and "run-war --https"). Integer.
grails.config.base.webXmlPath to a custom web.xml file to use for the application (alternative to using the web.xml template).
grails.compiler.dependenciesLegacy 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.patternsA 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.nameSuffixBy 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.fileA 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.dependenciesA closure containing "fileset()" entries that allows you complete control over what goes in the WAR's "WEB-INF/lib" directory.
grails.war.copyToWebAppA 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.resourcesA 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.xmlThe location to generate Grails' web.xml to

Configuración de construcción disponible

NombreDescripción
grails.Server.Port.httpPuerto para ejecutar el contenedor de servlet embebido ("run-app" y "run-war"). Entero.
grails.Server.Port.httpsPuerto para ejecutar el contenedor de servlet embebido bajo HTTPS ("run-app --https" y "run war --https"). Entero.
grails.config.base.webXmlRuta del archivo web.xml personalizada para utilizar para la aplicación (alternativa al uso de la plantilla de web.xml).
grails.compiler.dependenciesEnfoque 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.PatternsUna 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.nameSuffixPor 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.FileUna 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.dependenciesUna 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.copyToWebAppUna 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.resourcesUna 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.xMLLa ubicación en la que se generará el fichero web.xml.