The Command Line
Script Name Abbreviation
During Gr8Conf 2012 Europe I discovered Grails supports script name abbreviation. This means we don’t have to type a complete script name, but only enough to make the script identifiable by Grails. It is inspired by Gradle’s task name abbreviation feature. For example if we want to invoke the help script we only have to type the letter h. Or to invoke run-app we type rA. Notice we use uppercase characters for the letters after a hyphen in a script name. To invoke create-tag-lib we can type cTL.
If Grails cannot find a unique script name for the abbreviation we use we get a list of possible script names. We select the correct one to invoke the script. For example in the following output we see the options Grails shows when we type gen as a script name abbreviation:
This feature also works for script that we create ourselves or are added by plugins. For example if we create a script GrailsGoodness with the following content:
On the command-line or at the Grails prompt we can now use gG as a script name abbreviation and Grails will invoke the GrailsGoodness script:
Code written with Grails 2.04.
Original blog post written on June 14, 2012.
Shortcut to Open Test Reports in Interactive Console
We can use the open command in the interactive console in Grails to open files. For example to edit the default layout view we can typ in the console:
The application associated with GSP files starts and opens the file main.gsp.
So normally we have to pass actual filename with the complete path to the open command to open them. But Grails provides two shortcuts: test-report and dep-report. To see the output of our tests we can simply type open test-report:
Grails now opens the file target/test-reports/html/index.html.
The dep-report shortcut open the dependency report after we have run the dependency-report command:
Code written with Grails 2.0.
Original blog post written on March 08, 2012.
Run Gradle Tasks In Grails Interactive Mode
To start Grails in interactive mode we simply type grails on the command line. This starts Grails and we get an environment to run Grails commands like compile and run-app. Since Grails 3 the underlying build system has changed from Gant to Gradle. We can invoke Gradle tasks in interactive mode with the gradle command. Just like we would use Gradle from the command line we can run the same tasks, but this time when Grails is in interactive mode. Grails will use the Gradle version that belongs to the current Grails version.
We even get TAB completion for Gradle tasks.
In the next example we start Grails in interactive mode and run the Gradle task components:
Next we invoke gradle compile followed by TAB. We get all the Gradle tasks that start with compile:
Written with Grails 3.0.8.
Original blog post written on September 28, 2015.
See Information About Plugins
In Grails we can use the list-plugins command to get a list of all available plugins. The list returns only the plugins that are available for the Grails version we are using. So if we invoke this command in Grails 3 we get a different list than a Grails 2.x version. To get more detailed information, like website, source code URL and dependency definition we use the plugin-info command.
Let’s run the plugin-list command for Grails 3:
If we want more information about the spring-security-core plugin we invoke the following command:
If we would invoke the command in for example Grails 2.5.1 we get different results:
In Grails versions before Grails 3 we also have the command list-plugin-updates. This command will display if there are any version updates for the plugins installed in our application:
Written with Grails 3.0.7.
Original blog post written on September 22, 2015.
Get List Of Application Profiles
Grails 3 introduced the concept of application profiles to Grails. A profile contains the application structure, dependencies, commands and more to configure Grails for a specific type of application. The profiles are stored on the Grails Profile repository on Github. We can go there and see which profiles are available, but it is much easier to use the list-profiles command. With this command we get an overview of all the available profiles we can use to create a new application or plugin.
The list-profiles task is only available when we are outside a Grails application directory. So just like the create-app and create-plugin we can run list-profiles from a non-Grails project directory.
Once we know which profile we want to use we can use the name as value for the --profile option with the create-app command:
Written with Grails 3.0.8.
Original blog post written on September 28, 2015.
Getting More Information About A Profile
Since Grails 3.1 we can use the profile-info command to get more information about a profile. We see which commands are added to our project by the profile and which features can be chosen when we create a new application with the profile.
Suppose we want to know more about the rest-api profile then we invoke the profile-info command:
Written with Grails 3.1.
Original blog post written on January 29, 2016.
Using Features When Creating An Application
With the release of Grails 3.1 we can use features, defined in a profile, when we create a new application. Features will add certain dependencies to our Grails project, so we can start quickly. To see which features are available we use the profile-info command. This command lists available features for an application. We can choose the features we want to be included and pass them via the --features command line option of the create-app command.
When we look at the features available for the rest-api profile we see the following list:
Let’s create a new Grails application with the rest-api profile and use the mongodb, json-views and security features:
When we look at the contents of the generated build.gradle we can see dependencies for the features we have selected:
Written with Grails 3.1.
Original blog post written on January 29, 2016.
Create Report of URL Mappings
Since Grails 2.3 we can use the url-mappings-report command to get a nice report of the URL mappings we have defined in our application. Also implicit mappings created for example by using the resources attribute on a mapping definition are shown in the report. This report is very useful to see which URLs are exposed by your application and how they map to controllers.
Suppose we have the following grails-app/conf/UrlMappings.groovy with a couple of mappings:
When we run the following command $ grails url-mappings-report we get the following output:
Notice also mappings added by plugins like the mappings to dbdoc controller are shown.
Code written with Grails 2.3.
Original blog post written on November 18, 2013.
Compiling GSP from the Command-Line
Normally Groovy Server Pages (GSP) are compiled to class files when we create a WAR file of our application. If we want to compile the GSP without creating a WAR file we use the command-line argument ---gsp. Grails will compile the source code of our application and also the Groovy Server Pages. This way we can detect for examples faulty import statements in the GSP source code.
Code written with Grails 2.2.2.
Original blog post written on June 03, 2013.
Profile Script Tasks
If we want to know how long the execution of a Grails task takes we can enable profiling. If we enable profiling we can see for example how long it takes to compile the source code. We can enable the profiling information by setting the system property grails.script.profile with the value true.
Another way to enable profiling of the Grails tasks is to set the property grails.script.file with the value true in grails-app/conf/BuildConfig.groovy.
If we run a Grails script and profiling is enabled we see the information in the console output:
Code written with Grails 1.3.7.
Original blog post written on February 23, 2011.
No More Questions
Sometimes when we run Grails commands we get asked questions via user prompts. For example if we invoke $ grails create-domain-class Simple we get a message that it is good practice to use package names and the question “Do you want to continue? (y,n)”. We need to answer this question to continue, but what if we are not able to answer the question, for example if the script is run on a continuous integration server? We pass the argument --non-interactive to the grails command and now we don’t get a question and the script continues by using the default value for the answer. So in our example we can run $ grails create-domain-class Simple --non-interactive.
Written with Grails 1.2.
Original blog post written on March 12, 2010.
Create New Application without Wrapper
Since the latest Grails versions a Grails wrapper is automatically created when we execute the create-app command. If we don’t want the wrapper to be created we can use the command argument --skip-wrapper. If later we changed our mind and want the Grails wrapper we can simply run the wrapper command from our Grails application directory.
Let’s run the create-app command with the --skip-wrapper argument. If we check the contents of the created directory we see that the wrapper files are not created:
Written with Grails 2.4.4.
Original blog post written on November 25, 2014.
Enable Hot Reloading For Non-Development Environments
If we run our Grails 3 application in development mode our classes and GSP’s are automatically recompiled if we change the source file. We change our source code, refresh the web browser and see the results of our new code. If we run our application with another environment, like production or a custom environment, then the reloading of classes is disabled. But sometimes we have a different environment, but still want to have hot reloading of our classes and GSP’s. To enable this we must use the Java system property grails.reload.enabled and reconfigure the Gradle bootRun task to pass this system property.
Let’s change our Gradle build file and pass the Java system property grails.reload.enabled to the bootRun task if it is set. We use the constant Environment.RELOAD_ENABLED to reference the Java system property.
Suppose we have extra Grails environment with the name custom. We can still have hot reloading if we use the following command:
Or we use the Gradle bootRun task:
Written with Grials 3.0.9.
Original blog post written on November 20, 2015.
Generate ANT Build Script
In versions of Grails before version 1.2 we got an ANT script with Ivy support when we created a new application. With Grails 1.2 we don’t get the ANT script anymore automatically. But we can still generate the build file and Ivy configuration files, but we have to use a separate command: integrateWith. The complete command is:
Code written with Grails 1.2.
Original blog post written on March 19, 2010.
Generate Default .gitignore Or .hgignore File
We can use the integrateWith command with Grails to generate for example IDE project files and build system files. We specify via an extra argument the type of files to be generated. We can use this command also to create a .gitignore file with some default settings for files to be ignored in Grails projects.
In the root of our project we have now have a .gitignore file with the following contents:
If we would use Mercurial then we can generate a .hgignore file with the argument --hg:
The .hgignore file has the following contents:
Samples written with Grails 2.3.7.
Original blog post written on April 16, 2014.
Extending IntegrateWith Command
We can extend the integrate-with command in Grails to generate files for a custom IDE or build system. We must add a _Events.groovy file to our Grails projects and then write an implementation for the eventIntegrateWithStart event. Inside the event we must define a new closure with our code to generate files. The name of the closure must have the following pattern: binding.integrate_CustomIdentifier_. The value for CustomIdentifier can be used as an argument for the integrate-with command.
Suppose we want to extend integrate-with to generate a simple Sublime Text project file. First we create a template Sublime Text project file where we define folders for a Grails application. We create the folder src/ide-support/sublimetext and add the file grailsProject.sublimetext-project with the following contents:
Next we create the file scripts/_Events.groovy:
We are done and can now run the integrate-with command with the new argument sublimeText:
If we open the project in Sublime Text we see our folder structure for a Grails application:
Code written with Grails 2.3.7.
Original blog post written on April 16, 2014.
Using Wrapper for Running Grails Commands Without Grails Installation
Since Grails 2.1 we can create a Grails wrapper. The wrapper allows developer to run Grails commands in a project without installing Grails first. The wrapper concept is also available in other projects from the Groovy ecosystem like Gradle or Griffon. A wrapper is a shell script for Windows, OSX or Linux named grailsw.bat or grailsw and a couple of JAR files to automatically download a specific version of Grails. We can check in the shell scripts and supporting files into a version control system and make it part of the project. Developers working on the project simply check out the code and execute the shell script. If there is no Grails installation available then it will be downloaded.
To create the shell scripts and supporting files someone on the project must run the wrapper command for the first time. This developer must have a valid Grails installation. The files that are generated can then be added to version control and from then one developers can use the grailsw or grailsw.bat shell scripts.
In the root of the project we have two new files grailsw and grailsw.bat. Windows users can uss grailsw.bat and on other operating systems we use grailsw. Also a new directory wrapper is created with three files:
When we run the grailsw or grailsw.bat scripts for the first time we see how Grails is downloaded and installed into the $USER_HOME/.grails/wrapper directory. The following output shows that the file is downloaded and extracted when we didn’t run the grailsw script before:
When we want to use a new version of Grails one of the developers needs to run to run $ grails upgrade followed by $ grails wrapper with the new Grails version. Notice this developer needs to have a locally installed Grails installation of the version we want to create a wrapper for. The newly generated files can be checked in to version control and all developers on the project will have the new Grails version when they run the grails or grailsw.bat shell scripts.
We can change the download location of Grails to for example a company intranet URL. In the wrapper/ directory we see the file grails-wrapper.properties. The file has one property wrapper.dist.url, which by default refers to http://dist.springframework.org.s3.amazonaws.com/release/GRAILS/. We can change this to another URL, add the change to version control so other developers will get the change automatically. And when the grailsw shell script is executed the download location will be another URL. To set a different download URL when generating the wrapper we can use the command-line option –distributionUrl:
If we don’t like the default name for the directory to store the supporting files we can use the command-line option –wrapperDir. The files are then stored in the given directory and the grailsw and grailsw.bat shell scripts will contain the given directory name.
Written with Grails 2.2.0 and 2.2.1
Original blog post written on March 29, 2013.
Cleaning Up
When we use for example the compile or war command Grails will create files and stores them by default in the project’s working directory. The location of the project working directory can be customized in our grails-app/conf/BuildConfig.groovy configuration file. We remove the generated files with the Grails clean command. This command will remove all compiled class files, the WAR file, cached scripts and test reports. But this doesn’t remove all files in the project working directory. For example plugins or a temporary web.xml file, which are stored in the project working directory are not removed. We must use the clean-all command to also remove those files from the project working directory completely.
Let’s take a look at the default settings in our grails-app/conf/BuildConfig.groovy configuration file when we create a new Grails application:
After we run the war command we see the following contents in our target directory:
Let’s first run the clean command and check the contents of the target directory again:
Notice the target/work directory still exists. We now run clean-all and examine the contents of the target directory:
Now the work directory is removed as well.
We can also write our own scripts to for example only remove the generated WAR file with a clean command. With the following script we add the command clean-war to our application, which will delete the generated WAR file from our project:
We can use the targets cleanCompiledSources, cleanTestReports and cleanWarFile in our own scripts.
Code written with Grails 2.3.5
Original blog post written on February 03, 2014.
Using Aliases as Command Shortcuts
In Grails we can add aliases for standard Grails commands with the alias command. For example we want to use another name for a command or combine a command with arguments to a single alias. With the following command we create a start-app alias for the standard run-app command:
Now we can invoke $ grails start-app as an alternative for run-app. All aliases are stored in the file userHome/.grails/.aliases. This means the aliases we create are available for all Grails versions and applications of the current user. It is also good to notice than command arguments that start with - or -- are not saved as part of an alias. But for example the unit: argument for test-app can be part of an alias:
We can even specify test class patterns to be part of the alias. We then invoke the new alias with extra arguments -echoOut and -echoErr:
To delete an alias we can remove it from the file userHome/.grails/.aliases or use $ grails alias --delete=_alias_.
We can see which aliases are defined with the --list argument:
Code written with Grails 2.3.8.
Original blog post written on May 01, 2014.
Run Groovy Scripts in Grails Context
We can use the run-script command to run Groovy scripts within the context of a Grails application. We can pass one or more Groovy scripts as argument to the run-script command. The Grails environment will be configured and we can access the Spring application context, domain classes, Grails services and more. Basically everything we can do in the Grails console or shell can be saved as a Groovy script and run with the run-script command.
The following Groovy script shows some stats for a Grails application:
We can invoke the script with the following command:
Code written with Grails 2.4.0.
Original blog post written on May 22, 2014.
Add More Paths to the Stats Report
If we invoke $ grails stats for our Grails project we get to see the number of files and lines of code (LOC) for several Grails artifacts. For example we can see how many controllers, services and taglibs are in our project and how many lines of code is written for each.
We can add new source directories to the report. When the stats report is generated the StatsStart event is triggered. The default list of paths is passed as the argument of the event. We can subscribe to this event in our own Grails application. Because we get the list of paths as an argument, we can define our own path info and add it to the list. We add the paths grails-app/conf and grails-app/utils to be included in the stats report.
Now we can run the stats command again and we see the new paths in our report:
Code written with Grails 1.3.7.
Original blog post written on February 19, 2011.
Access Configuration in Grails Scripts
We can create our own scripts in Grails that can be executed from the command-line. To access values from the properties we have defined in grails-app/conf/Config.groovy we must start with adding the following line to the top of our script:
With this include we get access to the checkConfig task.
Next we must execute this task after the compile task to get a config variable in our script. The script variable config contains the values of our configuration defined in the Grails configuration files.
The following script contains some sample configuration properties for different environments.
Let’s create a new script Sample.groovy with the following command: $ grails create-script sample. We open the file and add:
If we execute our task with $ grails sample we get the following output:
And if we run $ grails test sample we get:
The original source for this information is Grails mailing list.
Code written with Grails 1.3.7.
Original blog post written on March 28, 2011.
Simple Script to Create WAR Files for Each Environment
We can create a new WAR file with the following Grails command:
This will make a new WAR file in the dist directory with the name test.war. We use the test environment for the settings.
With the following Groovy script we create a WAR file in the dist for each environment. We use application.properties to get the application name and version and use it to create the WAR filename.
Code written with Grails 1.2.
Original blog post written on January 24, 2010.