Before learning more about how to use gradle cleaning in this topic, familiarize yourself with the details of the build process here:
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.
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 is 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
open a ticket on your support portal 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, relative to your <LK_ENLISTMENT> location.
| Directory Type | Path
(relative to <LK_ENLISTMENT>) | 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: <LK_ENLISTMENT>/build/staging
- Removes the deploy directory: <LK_ENLISTMENT>/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
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: <LK_ENLISTMENT>/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: <LK_ENLISTMENT>/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 (<LK_ENLISTMENT>/build/staging) and then the deployment (<LK_ENLISTMENT>/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: <LK_ENLISTMENT>/build/staging/modules/myModule.module
- Removes module's deploy directory and deployed .module file: <LK_ENLISTMENT>/build/deploy/modules/myModule.module and <LK_ENLISTMENT>/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: <LK_ENLISTMENT>/build/modules/myModule
- Removes staged module file: <LK_ENLISTMENT>/build/staging/modules/myModule.module
- Removes module's deploy directory and deployed .module file: <LK_ENLISTMENT>/build/deploy/modules/myModule.module and <LK_ENLISTMENT>/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
