Below are some additional tips on using Gradle to your advantage and to help you learn the Gradle command line
Flags and Options
Use gradlew -h to see the various options available for running gradle commands.
By default, gradle outputs information related to the progress in building and which tasks it considers as up to date or skipped. If you don’t want to see this, or any other output about progress of the build, you’ll want to add the -q flag:
Set up an alias if you’re a command-line kind of person who can’t abide output to the screen.
If working offline, you will want to use the --offline option to prevent it from contacting the artifact server (You won’t have success if you do this for your first build.)
Or you can toggle offline mode in IntelliJ, as shown in the following screen shot:
If doing development in a single module, there is a command available to you that can be sort of a one-stop shopping experience:
This will build the jar files, and the .module file and then copy it to the build/deploy/modules directory, which will cause Tomcat to refresh.
Skipping Proteomics Binaries Download
We download some binary files from Artifactory for use with the MS2 module. These binaries are deposited in the build/deploy/bin directory of your local installation. Once downloaded, they won't be fetched again unless you remove the build/deploy/bin directory, such as by doing a cleanBuild.
If you are not working with the MS2 module, you may not want to spend the time to download these binaries. To skip the downloading of these binaries you can set the gradle property "excludeProteomicsBinaries" when building:
/path/to/gradlew deployApp -PexcludeProteomicsBinaries
For convenience, you can also include the excludeProteomicsBinaries property in your <user>/.gradle/gradle.properties file.
Restoring Proteomics Binaries
If you exclude them and later wish to include these binaries, first do a 'cleanBuild', then when you next 'deployApp' (without using the excludeProteomicsBinaries property on the command line or in your gradle.properties file) they will be downloaded.
Build tasks are available at a fairly granular level, which allows you to use just the tasks you need for your particular development process. The targeting is done by providing the Gradle path (Gradle paths use colons as separators instead of slashes in either direction) to the project as part of the target name. For example, to deploy just the wiki module, you would do the following from the root of the LabKey enlistment:
Note that Gradle requires only unique prefixes in the path elements, so you could achieve the same results with less typing as follows:
And when you mistype a target name it will suggest possible targets nearby. For example, if you type
Gradle responds with:
* What went wrong:
Task 'pick_pg' not found in project ':server'. Some candidates are: 'pickPg'.
Gradle's Helpful Tasks
Gradle provides many helpful tasks to advertise the capabilities and settings within the build system. Start with this and see where it leads you
Other very useful tasks for troubleshooting are
- projects - lists the set of projects included in the build
- dependencies - lists all dependencies, including transitive dependencies, for all the configurations for your build
Paths and Aliases
Placing the gradlew script in your path is not ideal in an environment where different directories/branches may use different versions of gradle (as you will invariably do if you develop on trunk and release branches). Instead, you can:
- Always run the gradlew command from the root of the enlistment using ./gradlew
- On Linux/Mac, use the direnv tool.
You may also want to create aliases for your favorite commands in Gradle. If you miss having the timestamp output at the end of your command, check out the tips in this issue
There are various things you can do to improve performance:
- Use targeted build steps to do just what you know needs to be done.
- Use the -a option on the command line to not rebuild project dependencies (though you should not be surprised if sometimes your changes do require a rebuild of dependencies that you're not aware of and be prepared to remove that -a option).
- Increase the number of parallel threads in use. This is done by setting the property org.gradle.workers.max in the root-level gradle.properties file. By default, this is set to 3. If you do not set this property, Gradle will attempt to determine the optimal number of threads to use. This may speed things up, but can also be memory-intensive, so you may need to increase the memory on the JVM gralde uses.
- You can add more memory to the JVM by setting the org.gradle.jvmargs property to something like this:
If you want to update your properties with either of these settings, We suggest that you put them in your <user>/.gradle/gradle.properties file so they apply to all gradle instances and so you won't accidentally check them in.
If you don't need the absolute latest code, and would be happy with the latest binary distribution, do the following to avoid the compilation steps altogether.
- Download the appropriate distribution zip/tar.gz file.
- Put it in a directory that does not contain another file with the same extension as the distribution (.tar.gz or .zip)
- Use the ./gradlew :server:cleanStaging :server:cleanDeploy :server:deployDistribution command, perhaps supplying a -PdistDir=/path/to/dist/directory property value to specify the directory that contains the downloaded distribution file and/or a -PdistType=zip property to specify that you're deploying form a zip file instead of a .tar.gz file.