- •1.1. About this user guide
- •2.1. Features
- •2.2. Why Groovy?
- •3.1. Getting Started
- •4.1. Prerequisites
- •4.2. Download
- •4.3. Unpacking
- •4.4. Environment variables
- •4.5. Running and testing your installation
- •4.6. JVM options
- •5.1. Working through problems
- •5.2. Getting help
- •6.1. Projects and tasks
- •6.2. Hello world
- •6.3. A shortcut task definition
- •6.4. Build scripts are code
- •6.5. Task dependencies
- •6.6. Dynamic tasks
- •6.7. Manipulating existing tasks
- •6.8. Shortcut notations
- •6.9. Extra task properties
- •6.10. Using Ant Tasks
- •6.11. Using methods
- •6.12. Default tasks
- •6.13. Configure by DAG
- •6.14. Where to next?
- •7.1. The Java plugin
- •7.2. A basic Java project
- •7.3. Multi-project Java build
- •7.4. Where to next?
- •8.1. What is dependency management?
- •8.2. Declaring your dependencies
- •8.3. Dependency configurations
- •8.4. External dependencies
- •8.5. Repositories
- •8.6. Publishing artifacts
- •8.7. Where to next?
- •9.1. A basic Groovy project
- •9.2. Summary
- •10.1. Building a WAR file
- •10.2. Running your web application
- •10.3. Summary
- •11.1. Executing multiple tasks
- •11.2. Excluding tasks
- •11.3. Task name abbreviation
- •11.4. Selecting which build to execute
- •11.5. Obtaining information about your build
- •11.7. Summary
- •12.1. Task Tree
- •12.2. Favorites
- •12.3. Command Line
- •12.4. Setup
- •13.1. Enter the daemon
- •13.2. Reusing and expiration of daemons
- •13.3. Usage and troubleshooting
- •13.4. Daemon properties
- •14.1. Directory creation
- •14.2. Gradle properties and system properties
- •14.3. Configuring the project using an external build script
- •14.4. Configuring arbitrary objects
- •14.5. Configuring arbitrary objects using an external script
- •14.6. Caching
- •15.1. Configuring the build environment via gradle.properties
- •15.2. Accessing the web via a proxy
- •16.1. The Gradle build language
- •16.2. The Project API
- •16.3. The Script API
- •16.4. Declaring variables
- •16.5. Some Groovy basics
- •17.1. Defining tasks
- •17.2. Locating tasks
- •17.3. Configuring tasks
- •17.4. Adding dependencies to a task
- •17.5. Adding a description to a task
- •17.6. Replacing tasks
- •17.7. Skipping tasks
- •17.8. Skipping tasks that are up-to-date
- •17.9. Task rules
- •17.10. Summary
- •18.1. Locating files
- •18.2. File collections
- •18.3. File trees
- •18.4. Using the contents of an archive as a file tree
- •18.5. Specifying a set of input files
- •18.6. Copying files
- •18.7. Using the Sync task
- •18.8. Creating archives
- •19.1. Choosing a log level
- •19.2. Writing your own log messages
- •19.3. Logging from external tools and libraries
- •19.4. Changing what Gradle logs
- •20.1. Using Ant tasks and types in your build
- •20.2. Importing an Ant build
- •20.3. Ant properties and references
- •21.1. Applying plugins
- •21.2. What plugins do
- •21.3. Conventions
- •21.4. More on plugins
- •22.1. Language plugins
- •22.2. Experimental language plugins
- •22.3. Integration plugins
- •22.4. Software development plugins
- •22.5. Base plugins
- •22.6. Third party plugins
- •23.1. Usage
- •23.2. Source sets
- •23.3. Tasks
- •23.4. Project layout
- •23.5. Dependency management
- •23.6. Convention properties
- •23.7. Working with source sets
- •23.8. Javadoc
- •23.9. Clean
- •23.10. Resources
- •23.11. CompileJava
- •23.12. Test
- •23.14. Uploading
- •24.1. Usage
- •24.2. Tasks
- •24.3. Project layout
- •24.4. Dependency management
- •24.5. Convention properties
- •24.6. Source set properties
- •24.7. CompileGroovy
- •25.1. Usage
- •25.2. Tasks
- •25.3. Project layout
- •25.4. Dependency Management
- •25.5. Convention Properties
- •25.6. Source set properties
- •25.7. Fast Scala Compiler
- •26.1. Usage
- •26.2. Tasks
- •26.3. Project layout
- •26.4. Dependency management
- •26.5. Convention properties
- •26.7. Customizing
- •27.1. Usage
- •27.2. Tasks
- •27.3. Project layout
- •27.4. Dependency management
- •27.5. Convention properties
- •27.8. Using custom descriptor file
- •28.1. Usage
- •28.2. Tasks
- •28.3. Project layout
- •28.4. Dependency management
- •28.5. Convention properties
- •29.1. Usage
- •29.2. Tasks
- •29.3. Project layout
- •29.4. Dependency management
- •29.5. Configuration
- •30.1. Usage
- •30.2. Tasks
- •30.3. Project layout
- •30.4. Dependency management
- •30.5. Configuration
- •31.1. Usage
- •31.2. Tasks
- •31.3. Dependency management
- •31.4. Configuration
- •32.1. Usage
- •32.2. Tasks
- •32.3. Dependency management
- •32.4. Configuration
- •33.1. Usage
- •33.2. Tasks
- •33.3. Dependency management
- •33.4. Configuration
- •34.1. Usage
- •34.2. Analyzing Multi-Project Builds
- •34.3. Analyzing Custom Source Sets
- •34.4. Setting Custom Sonar Properties
- •34.5. Tasks
- •35.1. Usage
- •35.2. Implicitly applied plugins
- •35.3. Tasks
- •35.4. Dependency management
- •35.5. Convention object
- •36.1. Usage
- •36.2. Tasks
- •36.3. Configuration
- •36.4. Customizing the generated files
- •37.1. Usage
- •37.2. Tasks
- •37.3. Configuration
- •37.4. Customizing the generated files
- •37.5. Further things to consider
- •38.1. Usage
- •38.2. Tasks
- •38.3. Project layout
- •38.4. Dependency management
- •38.5. Convention properties
- •38.6. Source set properties
- •39.1. Usage
- •39.2. Tasks
- •39.3. Project layout
- •39.4. Dependency management
- •39.5. Convention properties
- •40.1. Usage
- •40.2. Tasks
- •40.3. Project layout
- •40.4. Dependency management
- •40.5. Convention properties
- •41.1. Usage
- •42.1. Usage
- •42.2. Tasks
- •42.3. Convention properties
- •42.4. Including other resources in the distribution
- •43.2. Dependency management overview
- •43.3. Dependency configurations
- •43.4. How to declare your dependencies
- •43.5. Working with dependencies
- •43.6. Repositories
- •43.7. How dependency resolution works
- •43.8. The dependency cache
- •43.9. Strategies for transitive dependency management
- •44.1. Introduction
- •44.2. Artifacts and configurations
- •44.3. Declaring artifacts
- •44.4. Publishing artifacts
- •44.5. More about project libraries
- •45.1. Usage
- •45.2. Tasks
- •45.3. Dependency management
- •45.4. Convention properties
- •45.5. Convention methods
- •45.6. Interacting with Maven repositories
- •46.1. Usage
- •46.2. Signatory credentials
- •46.3. Specifying what to sign
- •46.4. Publishing the signatures
- •46.5. Signing POM files
- •47.1. Usage
- •47.2. Source code locations
- •47.3. Compiling
- •47.4. Configuring the compiler
- •47.5. Working with shared libraries
- •47.6. Dependencies
- •47.7. Publishing
- •48.1. Build phases
- •48.2. Settings file
- •48.3. Multi-project builds
- •48.4. Initialization
- •48.5. Configuration and execution of a single project build
- •48.6. Responding to the lifecycle in the build script
- •49.1. Cross project configuration
- •49.2. Subproject configuration
- •49.3. Execution rules for multi-project builds
- •49.4. Running tasks by their absolute path
- •49.5. Project and task paths
- •49.6. Dependencies - Which dependencies?
- •49.7. Project lib dependencies
- •49.8. Multi-Project Building and Testing
- •49.9. Property and method inheritance
- •49.10. Summary
- •50.1. Packaging a task class
- •50.2. Writing a simple task class
- •50.3. A standalone project
- •51.1. Packaging a plugin
- •51.2. Writing a simple plugin
- •51.3. Getting input from the build
- •51.4. Working with files in custom tasks and plugins
- •51.5. A standalone project
- •51.6. Maintaining multiple domain objects
- •52.1. Inherited properties and methods
- •52.2. Injected configuration
- •52.3. Build sources in the buildSrc project
- •52.4. Running another Gradle build from a build
- •52.5. External dependencies for the build script
- •52.6. Ant optional dependencies
- •52.7. Summary
- •53.1. Basic usage
- •53.2. Using an init script
- •53.3. Writing an init script
- •53.4. External dependencies for the init script
- •54.1. Configuration
- •54.2. Unix file permissions
- •54.3. Environment variable
- •55.1. Introduction to the Tooling API
- •55.2. Tooling API and the Gradle Build Daemon
- •55.3. Quickstart
- •A.1. Sample customBuildLanguage
- •A.2. Sample customDistribution
- •A.3. Sample customPlugin
- •A.4. Sample java/multiproject
- •B.1. Groovy script variables
- •B.2. Configuration and execution phase
- •C.1. Deprecated command-line options
- •C.2. Daemon command-line options:
- •C.3. System properties
- •C.4. Environment variables
- •D.1. IntelliJ
- •D.2. Eclipse
- •D.3. Using Gradle without IDE support
14.2.1. Checking for project properties
You can access a project property in your build script simply by using its name as you would use a variable. In case this property does not exists, an exception is thrown and the build fails. If your build script relies on optional properties the user might set for example in a gradle.properties file, you need to check for existence before you can access them. You can do this by using the method hasProperty('propertyName') which returns true or false.
14.3. Configuring the project using an external build script
You can configure the current project using an external build script. All of the Gradle build language is available in the external script. You can even apply other scripts from the external script.
Example 14.3. Configuring the project using an external build script
build.gradle
apply from: 'other.gradle'
other.gradle
println "configuring $project" task hello << {
println 'hello from other script'
}
Output of gradle -q hello
> gradle -q hello
configuring root project 'configureProjectUsingScript' hello from other script
14.4. Configuring arbitrary objects
You can configure arbitrary objects in the following very readable way.
Page 74 of 343
Example 14.4. Configuring arbitrary objects build.gradle
task configure << {
pos = configure(new java.text.FieldPosition(10)) { beginIndex = 1
endIndex = 5
}
println pos.beginIndex println pos.endIndex
}
Output of gradle -q configure
> gradle -q configure 1 5
14.5. Configuring arbitrary objects using an external script
You can also configure arbitrary objects using an external script.
Example 14.5. Configuring arbitrary objects using a script
build.gradle
task configure << {
pos = new java.text.FieldPosition(10) // Apply the script
apply from: 'other.gradle', to: pos println pos.beginIndex
println pos.endIndex
}
other.gradle
beginIndex = 1; endIndex = 5;
Output of gradle -q configure
> gradle -q configure 1 5
Page 75 of 343
14.6. Caching
To improve responsiveness Gradle caches all compiled scripts by default. This includes all build scripts, initialization scripts, and other scripts. The first time you run a build for a project, Gradle creates a .gradle directory in which it puts the compiled script. The next time you run this build, Gradle uses the compiled script, if the script has not changed since it was compiled. Otherwise the script gets compiled and the new version is stored in the cache. If you run Gradle with the --recompile-scripts option, the cached script is discarded and the script is compiled and stored in the cache. This way you can force Gradle to rebuild the cache.
[5] Teamcity or Bamboo are for example CI servers which offer this functionality.
Page 76 of 343
15
The Build Environment
15.1. Configuring the build environment via gradle.properties
Gradle provides several options that make it easy to configure the Java process that will be used to execute your build. While it's possible to configure these in your local environment vi GRADLE_OPTS or JAVA_OPTS, certain settings like jvm memory settings, java home, daemon on/off can be more useful if they can versioned with the project in your VCS so that the entire team can work with consistent environment. Setting up a consistent environment for your build is as simple as placing those settings into a gradle.properties file. The configuration is applied in following order (in case an option is configured in multiple locations the last one wins):
from gradle.properties located in project build dir.
from gradle.properties located in gradle user home.
from system properties, e.g. when -Dsome.property is used in the command line.
The following properties can be used to configure the Gradle build environment:
org.gradle.daemon
When set to true the Gradle daemon is to run the build. For local developer builds this is our favorite property. The developer environment is optimized for speed and feedback so we nearly always run Gradle jobs with the daemon. We don't run CI builds with the daemon (i.e a long running process) as the CI environment is optimized for consistency and reliability.
org.gradle.java.home
Specifies the java home for the Gradle build process. The value can be set to either jdk or j location, however, depending on what does your build do, jdk is safer. Reasonable default is used if the setting is unspecified.
org.gradle.jvmargs
Specifies the jvmargs used for the daemon process. The setting is particularly useful for tweaking memory settings. At the moment the default settings are pretty generous with regards to memory.
Page 77 of 343