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.
For file-based modules, add the following plugins to your build.gradle file:build.gradle
apply plugin: 'java'
apply plugin: 'org.labkey.fileModule'
For Java modules, add the following plugins:build.gradle
apply plugin: 'java'
apply plugin: 'org.labkey.module'
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:
- 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:
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):
Sample files for download:
- build.gradle - a sample build file for a stand-alone module
- standaloneModule.tgz - 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
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 'apiCompile' configuration of the LabKey module. This is in keeping with the Module Architecture
for LabKey modules.
compile project(path: ":server:optionalModules:workflow", configuration: 'apiCompile')
The example below adds a dependency on the wiki module:
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:
Here we use the 'external' configuration instead of the compile configuration to indicate that these libraries should be included in the lib directory of the .module file that is created for this project. The 'compile' 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 one of the directories referenced in the settings.gradle file (server/modules, server/customModules, server/optionalModules, externalModules, and the various existing subdirectories within externalModules), 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
- 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: