Building Apache Isis
The Apache Isis source code lives in a git repo.
The easiest place to get hold of command-line git is probably the github download page.
On Windows, this also installs the rather good mSysGit Unix shell. We recommend that you enable git for both the mSysgit and the Windows command prompt:
Once git is installed, the two main command line tools to note are:
gitcommand line tool
gitkfor viewing the commit history
If using Mac, you might also want to check out Atlassian’s Sourcetree.
First, clone the Apache Isis repo:
git clone https://github.com/apache/isis.git
Next up is to configure your user name and password:
git config user.name "My Name Here" git config user.email email@example.com
Next, configure the
core.autocrlf so that line endings are normalized to LF (Unix style) in the rep; again see Apache’s git page:
on Windows, use:
git config core.autocrlf true
on Mac/Linux, use:
git config core.autocrlf input
The Windows setting means that files are converted back to CRLF on checkout; the Mac/Linux setting means that the file is left as LF on checkout.
We also recommend setting
core.safecrlf, which aims to ensure that any line ending conversion is repeatable.
Do this on all platforms:
git config core.safecrlf true
Note that these settings are supplemented in the repo by the
.gitattributes file and that explicitly specifies line handling treatment for most of the common file types that we have.
Next, we recommend you setup this a refspec so that you can distinguish remote tags from local ones.
To do that, locate the
[remote "origin"] section in your
.git/config and add the third entry shown below:
[remote "origin"] url = ... whatever ... fetch = ... whatever ... fetch = +refs/tags/*:refs/tags/origin/*
This will ensure that a
git fetch or
git pull places any remote tags under
For example, the
isis-1.0.0 tag on the origin will appear under
If you don’t use git outside of Apache, you can add the
--global flag so that the above settings apply for all repos managed by git on your PC.
Three commands of git that in particular worth knowing:
git help command
will open the man page in your web browser
will open up a basic GUI client to staging changes and making commits.
will open the commit history for all branches. In particular, you should be able to see the local
master, which branch you are working on (the
HEAD), and also the last known position of the
masterbranch from the central repo, called
You might also want to explore using a freely available equivalent such as Atlassian SourceTree.
For further reading, see:
Some of the tooling used to generate documentation uses Java 11.
Therefore install either/both of Java 8 JDK and Java 11 JDK. Note that the JRE is not sufficient.
If you intend to contribute back patches to Apache Isis, note that while you can develop using Java 11 or above within your IDE, be sure not to use any APIs more recent than Java 8.
If you are a committer that will be performing releases of Apache Isis, then you must configure the toolchains plugin so that releases can be built using Java 8.
This is done by placing the
toolchains.xml file in
Use the following file as a template, adjusting paths for your platform:
<?xml version="1.0" encoding="UTF8"?> <toolchains> <toolchain> <type>jdk</type> <provides> <version>1.8</version> (1) <vendor>openjdk</vendor> </provides> <configuration> <jdkHome>C:\Program Files\OpenJDK\openjdk-8u262-b10</jdkHome> (2) </configuration> </toolchain> </toolchains>
|1||The Apache Isis build is configured to search for the (
|2||adjust as necessary|
The Apache Isis parent
pom.xml activates this plugin whenever the
apache-release profile is enabled.
Install Maven 3.0.x, downloadable here.
MAVEN_OPTS environment variable:
export MAVEN_OPTS="-Xms512m -Xmx1024m"
To build the source code from the command line, simply go to the root directory and type:
mvn clean install
The first time you do this, you’ll find it takes a while since Maven needs to download all of the Apache Isis prerequisites.
Thereafter you can speed up the build by adding the
-o (offline flag).
To save more time still, we also recommend that you build in parallel.
(Per this blog post), you could also experiment with a number of JDK parameters that we’ve found also speed up Maven:
export MAVEN_OPTS="-Xms512m -Xmx1024m -XX:+TieredCompilation -XX:TieredStopAtLevel=1" mvn clean install -o -T1C
For the most part, though, you may want to rely on an IDE such as Eclipse to build the codebase for you. Both Eclipse and Idea (12.0+) support incremental background compilation.
When using Eclipse, a Maven profile is configured such that Eclipse compiles to
target-ide directory rather than the usual
You can therefore switch between Eclipse and Maven command line without one interfering with the other.
Additional artifacts can be selected for inclusion with the build:
mvn clean install -Dmodule-xxx -Dmodule-yyy ...
module-yyy correspond to profile names, as provided with the root
All Apache Isis Modules
Official Project Documentation
Demo Application (JavaFx)
Demo Application (Vaadin)
Demo Application (Wicket)
All Incubation Modules
The JavaFx Viewer
The Kroviz Client (standalone viewer)
The Vaadin Viewer
Legacy Packages (to ease migration)
Regression Tests (for the CI pipelines)
Tooling Ecosystem (Code Mining, Automated Docs, …)
You can also skip building the "essential" modules that are released, by adding the
For example, to just build the tooling module, use:
mvn clean install -Dmodule-tooling -Dskip.essential
To check, run:
mvn org.owasp:dependency-check-maven:aggregate -Dowasp
This will generate a single report under
The first time this runs can take 10~20 minutes to download the NVD data feeds.
To disable, either run in offline mode (add
--offline) or omit the
Apache Isis configures the jdeps maven plugin to check for any usage of internal JDK APIs. This is in preparation for Java 9 module system (Jigsaw) which will prevent such usage of APIs.
To check, run:
mvn clean install -Djdeps
This will fail the build on any module that currently uses an internal JDK API.
At the time of writing the