Before learning more about how to use gradle cleaning in this topic, familiarize yourself with the details of the build process here:

• Build LabKey from Source

Understanding the progression of the build will help you understand how to do the right amount of cleanup in order to switch contexts or fix problems.

• Building and Cleaning
• Application Cleaning
• Module Cleaning

Gradle is generally very good about keeping track of when things have changed and so you can, and should, get out of the habit of wiping things clean and starting from scratch because it just takes more time. If you find that there’s some part of the process that does not recognize when its inputs have changed or its outputs are up-to-date, please file a bug or post to the developer support board so we can get that corrected.

The gradle tasks also provide much more granularity in cleaning. Generally, for each task that produces an artifact, we try to have a corresponding cleaning task that removes that artifact. This leads to a plethora of cleaning tasks, but there are only a few that you will probably ever want to use.

In this topic we summarize the most commonly useful cleaning tasks, indicating what the outcome of each task is and providing examples of when you might use each.

Building and Cleaning

This table summarizes the commands used to create and remove the various directories. Note that the cleaning behavior reflected here is accurate as of version 1.2 of the gradlePlguins.

Directory Type	Path (relative to <LABKEY_HOME>)	Added to by...	Removed from by...	Deleted by...
Source	server/modules/<module>	you	you	you
JavaScript Dependencies	server/modules/<module>/node_modules	:server:modules:<module>:deployModule :server:modules:<module>:npmInstall npm install	N/A	:server:modules:<module>:cleanNodeModules cleanNodeModules
Build	build	Any build step	Any cleaning step	cleanBuild
Module build	build/modules/<module>	module	N/A	:server:modules:<module>:clean
Staging	build/staging	:server:deployApp :server:modules:<module>:deployModule	:server:modules:<module>:undeployModule	:server:cleanStaging :server:cleanDeploy
Deploy	build/deploy	:server:deployApp :server:modules:<module>:deployModule	:server:modules:<module>:undeployModule	:server:cleanDeploy

Application Cleaning

cleanDeploy

Running 'gradlew cleanDeploy' removes the build/deploy directory. This will also stop the tomcat server if it is running.

Result:

• Stops Tomcat
• Removes the staging directory: <LABKEY_HOME>/build/staging
• Removes the deploy directory: <LABKEY_HOME>/build/deploy

Use when:

• Removing a set of modules from your LabKey instance (i.e., after updating settings.gradle to remove some previously deployed modules)
• Troubleshooting a LabKey server that appears to have built properly

cleanStaging

Running 'gradlew cleanStaging' removes the build/staging directory. This does not affect the running server.

Result:

• Removes the staging directory: <LABKEY_HOME>/build/staging

Use when:

• Using a version of gradle plugins earlier than 1.2 and you need to clean out a deployment (i.e., use it in conjunction with cleanDeploy). For versions of the plugin later than 1.2, you should not need to call this task.

cleanBuild

Running 'gradlew cleanBuild' removes the build directory entirely, requiring all of the build steps to be run again. This will also stop the tomcat server if it is running. This is the big hammer that you should avoid using unless there seems to be no other way out.

This is generally not what you want or need to do since Gradle's up-to-date checks should be able to determine when things need to be rebuilt. The one exception to this rule is that when the LabKey version number is incremented with each monthly release, you need to do a cleanBuild to get rid of all artifacts with the previous release version in their names.

Result:

• Stops Tomcat
• Removes the build directory: <LABKEY_HOME>/build

Use when:

• Updating LabKey version number in the gradle.properties file in an enlistment
• All else fails

Module Cleaning

The most important tasks for cleaning modules follow. The example module name used here is "MyModule".

:server:modules:myModule:clean

Removes the build directory for the module. This task comes from the standard Gradle lifecycle, and is generally followed by a deployModule or deployApp command.

Result:

• Removes myModule's build directory: <LABKEY_HOME>/build/modules/myModule
• Note that this will have little to no effect on a running server instance. It will simply cause gradle to forget about all the building it has previously done so the next time it will start from scratch.

Use when:

• Updating dependencies for a module
• Troubleshooting problems building a module

:server:modules:myModule:undeployModule

Removes all artifacts for this module from the staging and deploy directories. This is the opposite of deployModule. deployModule copies artifacts from the build directories into the staging (LABKEY_HOME/build/staging) and then the deployment (LABKEY_HOME/build/deploy) directories, so undeployModule removes the artifacts for this module from the staging and deployment directories. This will cause a restart of a running server since Tomcat will recognize that the deployment directory is changed.

Result:

• Removes staged module file: <LABKEY_HOME>/build/staging/modules/myModule.module
• Removes module’s deploy directory and deployed .module file: <LABKEY_HOME>/build/deploy/modules/myModule.module

and <LABKEY_HOME>/build/deploy/modules/myModule

• Restarts Tomcat.

Use when:

• There were problems at startup with one of the modules that you do not need in your LabKey server instance
• Always use when switching between feature branches because the artifacts created in a feature branch will have the feature branch name in their version number and thus will look different from artifacts produced from a different branch. If you don’t do the undeployModule, you’ll likely end up with multiple versions of your .module file in the deploy directory and thus in the classpath, which will cause confusion.

:server:modules:myModule:reallyClean

Removes the build directory for the module as well as all artifacts for this module from the staging and deploy directories. Use this to remove all evidence of your having built a module. Combines undeployModule and clean to remove the build, staging and deployment directories for a module.

Result:

• Removes myModule's build directory: <LABKEY_HOME>/build/modules/myModule
• Removes staged module file: <LABKEY_HOME>/build/staging/modules/myModule.module
• Removes module’s deploy directory and deployed .module file: <LABKEY_HOME>/build/deploy/modules/myModule.module

and <LABKEY_HOME>/build/deploy/modules/myModule

• Tomcat restarts

Use when:

• Removing a module that is in conflict with other modules
• Troubleshooting a build problem for a module

Related Topics

• Build LabKey from Source
• Troubleshoot Development Machines