Customize the Build

2024-03-29

This topic is under construction for the 24.3 (March 2024) release of LabKey Server. For current documentation of this feature, click here.

The LabKey Server module build process is designed to be flexible, consistent, and customizable. The process is driven by a manifest file that dictates which module directories to build. Module directories are listed either individually or using wildcards.

A few of the options this enables:

  • Modify your build manifest files to remove modules that you never use, speeding up your build.
  • Add your custom module directories to an existing build location (e.g., /server/modules) to automatically include them in the standard build.
  • Create a custom manifest file. See 'local_settings.gradle' below for an example.
After changing any of these files, we recommend that you sync gradle, by clicking the (refresh) icon in IntelliJ's Gradle projects panel.

Topics:

settings.gradle (Include and Exclude Modules)

By default, the standard build tasks use the manifest file "/settings.gradle". You can edit this file to customize the modules that are built. settings.gradle includes a mix of wildcards and individually listed modules.

Common syntax includes variations on lists of "includedModules" and "excludedModules".

Wildcard Example

The following builds every module under the localModules directory that is contained in an app directory. Note that app is the parent of the module directories, not the module directory itself.

def excludedModules = ["inProgress"]
// The line below includes all modules under the localModules directory that are contained in a directory "app".
// The modules are subdirectories of app, not app itself.
BuildUtils.includeModules(this.settings, rootDir, [**/localModules/**/app/*], excludedModules);

Module Directory Example

The following builds every module directory in "server/modules", except those listed as excludedModules:

def excludedModules = ["inProgress"]
// The line below includes all modules in the server/modules directory (except the ones indicated as to be excluded)
BuildUtils.includeModules(this.settings, rootDir, [BuildUtils.SERVER_MODULES_DIR], excludedModules);

Individual Module Example

The following adds the 'dataintegration' module to the build.

// The line below is an example of how to include a single module
include ":server:modules:dataintegration"

Custom Module Manifests

You can also create custom module manifest files. For example, the following manifest file 'local_settings.gradle' provides a list of individually named modules:

local_settings.gradle

include ':server:bootstrap'
include ':server:modules:commonAssays:ms2'
include ':server:modules:commonAssays:luminex'
include ':server:modules:platform:announcements'
include ':server:modules:platform:api'
include ':server:modules:platform:assay'
include ':server:modules:platform:audit'
include ':server:modules:platform:core'
include ':server:modules:platform:devtools'
include ':server:modules:platform:experiment'
include ':server:modules:platform:filecontent'
include ':server:modules:platform:internal'
include ':server:modules:platform:issues'
include ':server:modules:platform:list'
include ':server:modules:platform:mothership'
include ':server:modules:platform:pipeline'
include ':server:modules:platform:query'
include ':server:modules:platform:search'
include ':server:modules:platform:study'
include ':server:modules:platform:wiki'
include ':server:modules:targetedms'
include ':server:testAutomation:modules:dumbster'
include ':server:testAutomation:modules:pipelinetest'

The following uses the custom manifest file in the build:

gradlew -c local_settings.gradle deployApp

gradle/settings files

Instead of supplying a local settings file and using the -c option, you can put your setting file in the <LABKEY_HOME>/gradle/settings directory and use the moduleSet property to tell Gradle to pick up this settings file. The property value should be the basename of the settings file you wish to you. For example,

gradlew -PmoduleSet=all
will cause Gradle to incorporate the file <LABKEY_HOME>/gradle/settings/all.gradle to define the set of projects (modules) to include.

Skip a Module

You may choose to exclude certain modules from your Gradle configuration via the property excludedModules, introduced with Gradle plugins version 1.43.0. This property is handy if you want to include a set of modules defined via a moduleSet but need to exclude a select one or two, or even a full directory of modules. The value for this property should be a comma-separated string, where each element of that string can be one of the following

  • a directory name (e.g., 'commonAssays')
  • an unambiguous name for the enlistment directory of the module (e.g., 'flow')
  • the full gradle path to the module (e.g., ':server:modules:commonAssays:flow').
For example, the following command will exclude all the modules in the commonAssays directory:
gradlew -PmoduleSet=all -PexcludedModules=commonAssays
To exclude the flow assay, you could use either
gradlew -PmoduleSet=all -PexcludedModules=flow
or
gradlew -PmoduleSet=all -PexcludedModules=:server:modules:commonAssays:flow
If you want to exclude both the flow and nab assays, you could use either
gradlew -PmoduleSet=all -PexcludedModules=flow,nab
or, for example,
gradlew -PmoduleSet=all -PexcludedModules=nab,:server:modules:commonAssays:flow

This property can also be set in a gradle.properties file (for example, in your home directory's .gradle/gradle.properties file) in case you know you always want to exclude configuring and building some modules that are included in an enlistment.

excludedModules=:server:modules:commonAssays:nab

The excludeModules property is applied in the settings file, so it causes the project for the module to be excluded from gradle's configuration entirely.

The skipBuild property is deprecated and does not work well if you also are declaring dependencies in the module you wish to skip building. Prefer the excludedModules property instead. The build targets can be made to ignore a module if you define the property skipBuild for this project. You can do this by adding a gradle.properties file in the project's directory with the following content:

skipBuild

Note that we check only for the presence of this property, not its value.

The skipBuild property will cause the project to be included by gradle, so it would show up if you ran the "gradle projects" command, but it will remain largely not configured.

Undeploy a Module

When you have been building with a module and want to remove it completely, you should add it to an "excludedModules" list in your settings.gradle file and also need to use the unDeploy task in the module's directory.

For example, to remove the "dumbster" module you would add it to either "excludedModules" or "excludedExternalModules" (depending on where it is located in your enlistment) and before rebuilding, go to where it is installed and execute:

gradlew undeployModule

Related Topics