Gradle: How to Add Modules: /Documentation

Gradle: How to Add Modules

Adding a Module: Basic Process

The basic workflow for building and deploying your own module within the LabKey source tree goes as follows:

Apply plugins in the module's build.gradle file.
Declare dependencies in build.gradle (if necessary).
Include the module in your build manifest file (if necessary).
Sync Gradle.
Deploy the module to the server.

Details for file-based modules vs. Java modules are described below.

Apply Plugins

File-based Modules

For file-based modules, add the following plugins to your build.gradle file:

build.gradle

apply plugin: 'java'
apply plugin: 'org.labkey.fileModule'

Or, as of gradlePluginsVersion 1.22.0 (and LabKey version 21.1):

plugins {
   id 'org.labkey.build.fileModule'
}

Java Modules

For Java modules, add the following plugins:

build.gradle

apply plugin: 'java'
apply plugin: 'org.labkey.module'

Or, as of gradlePluginsVersion 1.22.0 (and LabKey version 21.1):

plugins {
   id 'org.labkey.build.module'
}

Stand-alone Modules

For modules whose source resides outside the LabKey Server source repository, you must provide your own gradle files, and other build resources, inside the module. The required files are:

settings.gradle - The build manifest where plugin repositories can be declared and project name is set
build.gradle - The build script where plugins are applied, tasks, are added, dependencies are declared, etc. .
module.properties - Module-scoped properties, see module.properties Reference
module.template.xml - The build system uses this file in conjunction with module.properties to create a deployable properties file at /config/module.xml.

You will also probably want to put a gradle wrapper in your module. You can do this by using the gradle wrapper from the LabKey distribution with the following command in your module's directory:

/path/to/labkey/enlistment/gradlew wrapper

This will create the following in the directory where the command is run:

gradlew - The Gradle wrapper linux shell script. You get this when you install the Gradle wrapper.
gradlew.bat - The Windows version of the Gradle wrapper. You get this when you install the Gradle wrapper.
gradle - directory containing the properties and jar file for the wrapper

If you do not have a LabKey enlistment or access to another gradle wrapper script, you will first need to install gradle in order to install the wrapper.

The module directory will be laid out as follows. Note that this directory structure is based on the structure you get from createModule (except for module.template.xml, gradlew):

MODULE_DIR
│   build.gradle
├───gradle
│   └───wrapper
│           gradle-wrapper.jar
│           gradle-wrapper.properties
│   gradlew
│   gradlew.bat
│   module.properties
│   module.template.xml
│
├───resources
│   ├───schemas
│   ├───web
│   └───...
│
│   settings.gradle
│
└───src
    └───...

Sample files for download:

build.gradle - a sample build file for a stand-alone module
standalone module - a simple stand-alone module with minimal content from which you can create a module file to be deployed to a LabKey server

Also see Tutorial: Hello World Java Module.

Declare Dependencies

When your module code requires some other artifacts like a third-party jar file or another LabKey module, declare a dependency on that resource inside the build.gradle file. The example below adds a dependency to the workflow module. Notice that the dependency is declared for the 'apiJarFile' configuration of the LabKey module. This is in keeping with the architecture used for LabKey Modules.

dependencies
{
    implementation project(path: ":server:modules:workflow", configuration: 'apiJarFile')
}

The example below adds a dependency on the wiki module:

dependencies {
    BuildUtils.addLabKeyDependency(project: project, config: "modules", depProjectPath: BuildUtils.getPlatformModuleProjectPath(project.gradle, "wiki"), depProjectConfig: "published", depExtenstion: "module")
}

The example below adds dependencies on two external libraries:

dependencies
{
   external 'commons-httpclient:commons-httpclient:3.1'
   external 'org.apache.commons:commons-compress:1.13'
}

Here we use the 'external' configuration instead of the implementation configuration to indicate that these libraries should be included in the lib directory of the .module file that is created for this project. The 'implementation' configuration extends this LabKey-defined 'external' configuration.

There are many other examples in the server source code, for example:

For a detailed topic on declaring dependencies, see Gradle: Declare Dependencies.

Include the module in your build manifest file

With the default settings.gradle file in place, there will often be no changes required to incorporate a new module into the build. By placing the module in server/modules, it will automatically be picked up during the initialization phase. If you put the new module in a different location, you will need to modify the settings.gradle file to include this in the configuration.

For example adding the following line to your build manifest file incorporates the helloworld module into the build. For details see Customize the Build.

include ':localModules:helloworld'

Sync Gradle

In IntelliJ, on the Gradle projects panel, click Refresh all gradle projects.

Deploy the Module

In your module's directory, call the following gradle task to build and deploy it:

path/to/gradlew deployModule

LabKey Support

LabKey Support