Build system
Contents
Detailed insight in the standard XP build system
We recommend using Enonic CLI to control your builds by default. |
Gradle
By default, XP projects use Gradle as the main build tool. This is a highly flexible Java-based utility that builds on the popular Maven project tools and code repository structures. Enonic provides a Gradle plugin that greatly simplifies the build process. If you used the starter-vanilla project to initialize your project, you will have all the basic tools you need to get going.
Dependencies
The build.gradle
file located at your project root defines all the dependencies to other libraries.
There are three standard scopes (keywords) used in the dependency list
-
Compile (default gradle scope, compiles library and adds it to class path - standard for pure Java libraries)
-
Include (XP custom scope that merges the content of the library and its dependencies with your project - any code in your project overwrites the library files)
-
Webjar (Extracts the content of the specified Webjar - https://www.webjars.org/ - placing it into the assets folder, using the version number as root folder)
Environment variables
The XP Home folder contains directories specific to a single XP instance. The home folder can be copied to multiple locations for developers working on multiple isolated projects. Enonic XP uses, by default, the home
folder within your distribution as XP Home.
Enonic XP uses, by default, the JDK/JRE within your distribution or the location of your Java installation is used as Java Home. Gradel uses, by default, the location of your Java installation is used as Java Home
If you wish to change this behaviour, the following environment variables can be defined:
- XP_HOME
-
Defines the location of the home folder
- JAVA_HOME
-
Defines the location of Java
To set these variables use one of the following approaches:
- Linux/MacOS
export XP_HOME=/path/to/home export JAVA_HOME=/path/to/xp-distro/jdk
- Windows
set XP_HOME=c:\path\to\home set JAVA_HOME=c:\path\to\xp-distro\jdk
Gradle Wrapper
The Gradle Wrapper is a file located in your projects root: gradlew
for Linux/MacOS and gradle.bat
for Windows.
The wrapper will download all necessary files to run Gradle and execute project specific build commands.
Building
Enonic CLI’s enonic project build
command automatically wraps and invokes the Gradle Wrapper.
With environment variables set, you may use Gradle directly to get the job done:
From your project folder root execute the following command:
- Enonic CLI
-
enonic project build
- OSX/Linux
-
./gradlew build
- Windows
-
gradlew.bat build
The build will place any output artifacts in the project’s build/libs/ folder.
Deploying
To builds and deploy an app to your XP Home, make sure XP_HOME is defined and execute the following command
- Enonic CLI
-
enonic project deploy
- Linux/MacOS
-
./gradlew deploy
- Windows
-
gradlew.bat deploy
The artifact is copied into the following location: $XP_HOME/deploy
, where XP will automatically pick it up.
XP apps deployed via file (locally) are presented with a small blue icon in the Applications tool in XP Admin. |
Development Mode
As the name implies, development mode is intended only for development use and should not be used in production. Doing so would cause both security and performance issues. |
Enonic XP can be run in a special mode known as development mode. In this mode, XP will try to detect changes to your project source files, including JavaScript controllers and registered XML schemas. It does this by reading these files directly from their source locations instead of from the application .jar
file.
Because of the way XP reads source files directly in development mode, it has a few limitations:
-
Files that require any sort of compilation (including transpilation) are not detected unless you run a build process on the side. For instance, if you use TypeScript or JavaScript features that XP doesn’t support, these files won’t be picked up by default. To have XP detect them, run a separate build process on the side, such as either a continuous build or a webpack build.
XP uses the Nashorn JavaScript engine for executing JavaScript. For an overview over what JavaScript features Nashorn supports, see this feature table. If development mode does not work for you, try using continuous build mode instead.
Development mode also disables some of XP’s caching mechanisms. To make the development workflow as smooth as possible, XP tries to invalidate caches for your static assets. This is to prevent you from getting stale resources so that what you see in the browser is always as up to date as possible.
To activate development mode, use one of the following commands to start your sandbox:
- Enonic CLI
-
enonic sandbox start --dev
- Linux/MacOS
-
$XP_INSTALL/bin/server.sh dev
- Windows
-
$XP_INSTALL/bin/server.sh dev
Continuous building
Gradle also supports a continuous build mode. In continuous build mode, Gradle will monitor your project assets for changes and run a task you specify when something changes.
Continuous builds come in handy when the changes you’re working on require a full compile and redeploy, such as when you’re working with Java or need to build/compile client-side assets with an external build tool (such as webpack).
If you don’t need a full compile or don’t need to run external build tools, you may be better served by using XP’s development mode.
To use continuous Gradle tasks, specify your task and pass the --continuous
option. The following examples use the deploy
task, but you can also use any other defined Gradle tasks:
- Enonic CLI
-
enonic project gradle deploy --continuous
- Linux/MacOS
-
./gradlew deploy --continuous
- Windows
-
gradlew.bat deploy --continuous