Merge branch '2.1.x'

src/en/guide/commandLine/antAndMaven.gdoc

@@ -53,11 +53,11 @@ How you populate these paths is up to you. If you use the @home@ attribute and p
 
 h3. Maven Integration
 
-Grails provides integration with "Maven 2":http://maven.apache.org with a Maven plugin. The current Maven plugin is based on but supersedes the version created by [Octo|http://forge.octo.com/], who did a great job with the original.
+Grails provides integration with "Maven 2":http://maven.apache.org with a Maven plugin. 
 
 h4. Preparation
 
-In order to use the new plugin, all you need is Maven 2 installed and set up. This is because *you no longer need to install Grails separately to use it with Maven!*
+In order to use the Maven plugin, all you need is Maven 2 installed and set up. This is because *you no longer need to install Grails separately to use it with Maven!*
 
 {note}
 The Maven 2 integration for Grails has been designed and tested for Maven 2.0.9 and above. It will not work with earlier versions.
@@ -71,17 +71,61 @@ The default mvn setup DOES NOT supply sufficient memory to run the Grails enviro
 
 h4. Creating a Grails Maven Project
 
-To create a Mavenized Grails project simply run the following command:
+Using the @create-pom@ command you can generate a valid Maven @pom.xml@ file for any existing Grails project. The below presents an example:
+
+{code}
+$ grails create-app myapp
+$ cd myapp
+$ grails create-pom com.mycompany
+{code}
+
+The @create-pom@ command expects a group id as an argument. The name and the version are taken from the @application.properties@ of the application. The Maven plugin will keep the version in the @pom.xml@ in sync with the version in @application.properties@.
+
+The following standard Maven commands are then possible:
+
+* @compile@ - Compiles a Grails project
+* @package@ - Builds a WAR file from the Grails project.
+* @install@ - Builds a WAR file (or plugin zip/jar if a plugin) and installs it into your local Maven cache
+* @test@ - Runs the tests of a Grails project
+* @clean@ - Cleans the Grails project
+
+Other standard Maven commands will likely work too.
+
+You can also use some of the Grails commands that have been wrapped as Maven goals:
+
+* @grails:create-controller@ - Calls the [create-controller|commandLine] command
+* @grails:create-domain-class@ - Calls the [create-domain-class|commandLine] command
+* @grails:create-integration-test@ - Calls the [create-integration-test|commandLine] command
+* @grails:create-pom@ - Creates a new Maven POM for an existing Grails project
+* @grails:create-script@ - Calls the [create-script|commandLine] command
+* @grails:create-service@ - Calls the [create-service|commandLine] command
+* @grails:create-taglib@ - Calls the [create-tag-lib|commandLine] command
+* @grails:create-unit-test@ - Calls the [create-unit-test|commandLine] command
+* @grails:exec@ - Executes an arbitrary Grails command line script
+* @grails:generate-all@ - Calls the [generate-all|commandLine] command
+* @grails:generate-controller@  - Calls the [generate-controller|commandLine] command
+* @grails:generate-views@ - Calls the [generate-views|commandLine] command
+* @grails:install-templates@ - Calls the [install-templates|commandLine] command
+* @grails:list-plugins@ - Calls the [list-plugins|commandLine] command
+* @grails:package@ - Calls the [package|commandLine] command
+* @grails:run-app@ - Calls the [run-app|commandLine] command
+
+For a complete, up to date list, run @mvn grails:help@
+
+h4. Creating a Grails Maven Project using the Archetype
+
+You can create a Maven Grails project without having Grails installed, simply run the following command:
 
 {code}
 mvn archetype:generate -DarchetypeGroupId=org.grails \\\
     -DarchetypeArtifactId=grails-maven-archetype \\\
-    -DarchetypeVersion=1.3.2 \\\
+    -DarchetypeVersion=2.1.0.RC1 \\\
     -DgroupId=example -DartifactId=my-app
 {code}
 
 Choose whichever grails version, group ID and artifact ID you want for your application, but everything else must be as written. This will create a new Maven project with a POM and a couple of other files. What you won't see is anything that looks like a Grails application. So, the next step is to create the project structure that you're used to.
 But first, to set target JDK to Java 6, do that now. Open my-app/pom.xml and change
+
 {code}
 <plugin>
   <artifactId>maven-compiler-plugin</artifactId>
@@ -109,77 +153,103 @@ cd my-app
 mvn initialize
 {code}
 
-{note}
-if you see a message similar to this:
+h4. Defining Plugin Dependencies
 
+All Grails plugins are published to a standard Maven repository located at [http://repo.grails.org/grails/plugins/]. When using the Maven plugin for Grails you must ensure that this repository is declared in your list of remote repositories:
+
+{code:xml}
+<repository>
+    <id>grails-plugins</id>
+    <name>grails-plugins</name>
+    <url>http://repo.grails.org/grails/plugins</url>
+</repository>
 {code}
-Resolving plugin JAR dependencies ...
-:: problems summary ::
-:::: WARNINGS
-        module not found: org.hibernate#hibernate-core;3.3.1.GA
+
+With this done you can declare plugin dependencies within your @pom.xml@ file:
+
+{code:xml}
+<dependency>
+    <groupId>org.grails.plugins</groupId>
+    <artifactId>database-migration</artifactId>
+    <version>1.1</version>
+    <scope>runtime</scope>
+    <type>zip</type>
+</dependency>
 {code}
 
-you need to add the plugins manually to application.properties:
+Note that the @type@ element must be set to @zip@.
+
+h4. Forked Grails Execution
+
+By default the Maven plugin will run Grails commands in-process, meaning that the Grails process occupies the same JVM as the Maven process. This can put strain on the Maven process for particularly large applications.
+
+In this case it is recommended to use forked execution. Forked execution can be configured in the @configuration@ element of the plugin:
 
 {code}
-plugins.hibernate=2.0.0
-plugins.tomcat=2.0.0
+<plugin>
+    <groupId>org.grails</groupId>
+    <artifactId>grails-maven-plugin</artifactId>
+    <version>${grails.version}</version>
+    <configuration>
+        <!-- Whether for Fork a JVM to run Grails commands -->
+        <fork>true</fork>
+    </configuration>
+    <extensions>true</extensions>
+</plugin>
 {code}
 
-then run
+With this configuration in place a separate JVM will be forked when running Grails commands. If you wish to debug the JVM that is forked you can add the @forkDebug@ element:
 
-{code}
-mvn compile
+{code:xml}
+    <!-- Whether for Fork a JVM to run Grails commands -->
+    <fork>true</fork>
+    <forkDebug>true</forkDebug>
 {code}
 
-and the hibernate and tomcat plugins will be installed.
-{note}
+If you need to customize the memory of the forked process the following elements are available:
 
-Now you have a Grails application all ready to go. The plugin integrates into the standard build cycle, so you can use the standard Maven phases to build and package your app:  @mvn clean@ ,  @mvn compile@ ,  @mvn test@ ,  @mvn package@ , @mvn install@ .
+* @forkMaxMemory@ - The maximum amount of heap (default 1024)
+* @forkMinMemory@ - The minimum amount of heap (default 512)
+* @forkPermGen@ - The amount of permgen (default 256)
 
-You can also use some of the Grails commands that have been wrapped as Maven goals:
 
-* @grails:create-controller@ - Calls the [create-controller|commandLine] command
-* @grails:create-domain-class@ - Calls the [create-domain-class|commandLine] command
-* @grails:create-integration-test@ - Calls the [create-integration-test|commandLine] command
-* @grails:create-pom@ - Creates a new Maven POM for an existing Grails project
-* @grails:create-script@ - Calls the [create-script|commandLine] command
-* @grails:create-service@ - Calls the [create-service|commandLine] command
-* @grails:create-taglib@ - Calls the [create-tag-lib|commandLine] command
-* @grails:create-unit-test@ - Calls the [create-unit-test|commandLine] command
-* @grails:exec@ - Executes an arbitrary Grails command line script
-* @grails:generate-all@ - Calls the [generate-all|commandLine] command
-* @grails:generate-controller@  - Calls the [generate-controller|commandLine] command
-* @grails:generate-views@ - Calls the [generate-views|commandLine] command
-* @grails:install-plugin@ - Calls the [install-plugin|commandLine] command
-* @grails:install-templates@ - Calls the [install-templates|commandLine] command
-* @grails:list-plugins@ - Calls the [list-plugins|commandLine] command
-* @grails:package@ - Calls the [package|commandLine] command
-* @grails:run-app@ - Calls the [run-app|commandLine] command
-* @grails:uninstall-plugin@ - Calls the [uninstall-plugin|commandLine] command
+h4. Multi Module Maven Builds
 
-For a complete, up to date list, run @mvn grails:help@
+The Maven plugin can be used to power multi-module Grails builds. The easiest way to set this is up is with the @create-multi-project-build@ command:
+
+{code}
+$ grails create-app myapp
+$ grails create-plugin plugin1
+$ grails create-plugin plugin2
+$ grails create-multi-project-build org.mycompany:parent:1.0
+{code}
 
-h4. Mavenizing an existing project
+Running @mvn install@ will build all projects together. To enable the 'grails' command to read the POMs you can modify @BuildConfig.groovy@ to use the POM and resolve dependencies from your Maven local cache:
 
-Creating a new project is great way to start, but what if you already have one? You don't want to create a new project and then copy the contents of the old one over. The solution is to create a POM for the existing project using this Maven command (substitute the version number with the grails version of your existing project):
 {code}
-mvn org.grails:grails-maven-plugin:1.3.2:create-pom -DgroupId=com.mycompany
+grails.project.dependency.resolution = {
+    ...
+    pom true
+    repositories {
+        ...
+        mavenLocal()    
+    }
+}
 {code}
-When this command has finished, you can immediately start using the standard phases, such as @mvn package@. Note that you have to specify a group ID when creating the POM.
 
-You may also want to set target JDK to Java 6; see above.
+By reading the @pom.xml@ file you can do an initial @mvn install@ from the parent project to build all plugins and install them into your local maven cache and then @cd@ into your project and use the regular @grails run-app@ command to run your application. All previously built plugins will be resolved from the local Maven cache.
 
 h4. Adding Grails commands to phases
 
 The standard POM created for you by Grails already attaches the appropriate core Grails commands to their corresponding build phases, so "compile" goes in the "compile" phase and "war" goes in the "package" phase. That doesn't help though when you want to attach a plugin's command to a particular phase. The classic example is functional tests. How do you make sure that your functional tests (using which ever plugin you have decided on) are run during the "integration-test" phase?
 
 Fear not: all things are possible. In this case, you can associate the command to a phase using an extra "execution" block:
+
 {code:xml}
 <plugin>
     <groupId>org.grails</groupId>
     <artifactId>grails-maven-plugin</artifactId>
-    <version>1.3.2</version>
+    <version>2.1.0.RC2</version>
     <extensions>true</extensions>
     <executions>
         <execution>
@@ -203,6 +273,7 @@ Fear not: all things are possible. In this case, you can associate the command t
 {code}
 
 This also demonstrates the @grails:exec@ goal, which can be used to run any Grails command. Simply pass the name of the command as the @command@ system property, and optionally specify the arguments with the @args@ property:
+
 {code}
 mvn grails:exec -Dcommand=create-webtest -Dargs=Book
 {code}
@@ -226,4 +297,4 @@ mvn grails:run-app
 
 h4. Raising issues
 
-If you come across any problems with the Maven integration, please raise a JIRA issue as a sub-task of [GRAILS-3547|http://jira.codehaus.org/browse/GRAILS-3547].
+If you come across any problems with the Maven integration, please raise a [JIRA issue||http://jira.grails.org/browse/MAVEN].

src/en/guide/testing/unitTesting/unitTestingTagLibraries.gdoc

@@ -46,7 +46,7 @@ class SimpleTagLibTests {
     void testHelloTag() {
         assert applyTemplate('<s:hello />') == 'Hello World'
         assert applyTemplate('<s:hello name="Fred" />') == 'Hello Fred'
-        assert applyTemplate('<s:bye author="${author}" />', [author: new Author(name: 'Fred')]) == 'Bye Fred'
+        assert applyTemplate('<s:bye author="\${author}" />', [author: new Author(name: 'Fred')]) == 'Bye Fred'
     }
 }
 {code}