[[building-apache-causeway]]
= Building Apache Causeway

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:

== TL;DR

From the root project root run:

[source,bash]
----
mvn clean install
----

== Git

The Apache Causeway source code lives in a git repo.


=== Installation

The easiest place to get hold of command-line git is probably the http://git-scm.com/downloads[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:

image::building-apache-causeway/setting-up-git.png[width="350px"]

Once git is installed, the two main command line tools to note are:

* `git` command line tool
* `gitk` for viewing the commit history

If using Windows, note that github also have a dedicated https://help.github.com/articles/set-up-git[Windows client].
With a little http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx[hacking around], it can also be made to work with non-github repositories.

If using Mac, you might also want to check out Atlassian's http://www.atlassian.com/software/sourcetree/overview[Sourcetree].



==== Cloning the Apache Causeway repo

First, clone the Apache Causeway repo:

[source,bash]
----
git clone https://github.com/apache/causeway.git
----

==== Configuring Git

Next up is to configure your user name and password:

[source,bash,subs=+quotes]
----
git config user.name "__My Name Here__"
git config user.email _myusername@apache.org_
----

Next, configure the `core.autocrlf` so that line endings are normalized to LF (Unix style) in the rep; again see https://git-wip-us.apache.org/[Apache's git] page:


* on Windows, use: +
+
[source,bash]
----
git config core.autocrlf true
----

* on Mac/Linux, use: +
+
[source,bash]
----
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:

[source,bash]
----
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 &quot;origin&quot;]` section in your `.git/config` and add the third entry shown below:

[source,bash]
----
[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 `origin/xxx`.
For example, the `causeway-1.0.0` tag on the origin will appear under `origin/causeway-1.0.0`.

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.

=== Getting help

Three commands of git that in particular worth knowing:

* `git help _command_` +
+
will open the man page in your web browser

* `git gui` +
+
will open up a basic GUI client to staging changes and making commits.

* `gitk --all` +
+
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 `master` branch from the central repo, called `origin/master`.

You might also want to explore using a freely available equivalent such as link:https://www.sourcetreeapp.com/[Atlassian SourceTree].

For further reading, see:

* http://www.kernel.org/pub/software/scm/git/docs/git-config.html[git config man page]
* http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html[.gitattributes man page]
* http://git-scm.com/docs/gitattributes[.gitattributes git-scm.com docs]

== Installing Java

Apache Causeway v2 is compatible with Java 11 and above, and releases are xref:comguide:ROOT:cutting-a-release.adoc[cut] using Java 11, leveraging the link:http://maven.apache.org/plugins/maven-toolchains-plugin/[Maven toolchains plugin]).

Therefore install Java 11 JDK or newer.
Note that the JRE is _not_ sufficient.

[TIP]
====
If you intend to contribute back patches to Apache Causeway, 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 11.
====

// no longer required, I believe.
//
//=== Configure Maven toolchains plugin
//
//If you are a committer that will be performing releases of Apache Causeway, then you _must_ configure the
//link:http://maven.apache.org/plugins/maven-toolchains-plugin/[toolchains] plugin so that releases can be built using Java 11.
//
//This is done by placing the `toolchains.xml` file in `~/.m2` directory.
//Use the following file as a template, adjusting paths for your platform:
//
//[source,xml]
//----
//<?xml version="1.0" encoding="UTF8"?>
//<toolchains>
//    <toolchain>
//        <type>jdk</type>
//        <provides>
//            <version>1.8</version>            <!--.-->
//            <vendor>openjdk</vendor>
//        </provides>
//        <configuration>
//            <jdkHome>C:\Program Files\OpenJDK\openjdk-8u262-b10</jdkHome>    <!--.-->
//        </configuration>
//    </toolchain>
//</toolchains>
//----
//<.> The Apache Causeway build is configured to search for the (`1.8, openjdk`) JDK toolchain.
//<.> adjust as necessary
//
//The Apache Causeway parent `pom.xml` activates this plugin whenever the `apache-release` profile is enabled.

== Installing Maven

Install Maven 3.6.3 or later, downloadable http://maven.apache.org/download.html[here].

Set `MAVEN_OPTS` environment variable:

[source,bash]
----
export MAVEN_OPTS="-Xms512m -Xmx1024m"
----

== Building Apache Causeway

To build the source code from the command line, simply go to the root directory and type:

[source,bash]
----
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 Causeway 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 link:http://zeroturnaround.com/rebellabs/your-maven-build-is-slow-speed-it-up/[blog post]), you could also experiment with a number of JDK parameters that we've found also speed up Maven:

[source,bash]
----
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 `target` directory.
You can therefore switch between Eclipse and Maven command line without one interfering with the other.


=== Additional Build Profiles

Additional artifacts can be selected for inclusion with the build:

[source,bash]
----
mvn clean install -Dmodule-xxx -Dmodule-yyy ...
----

where `module-xxx` and `module-yyy` correspond to profile names, as provided with the root `pom.xml`.

.Custom Build Profiles
[cols="1m,2",options="header"]
|===

| Profile Name
| Description

| module-all
| All Apache Causeway Modules

| module-antora
| Official Project Documentation

Note that this also includes the Restful Objects and GraphQL viewers.

| module-incubator-all
| All Incubation Modules

| module-incubator-graphql
| The GraphQL Viewer

| module-incubator-javafx
| The JavaFX Viewer (version 3+ only)

| module-incubator-kroviz
| The Kroviz Client (standalone viewer, version 3+ only)

| module-regressiontests
| Regression Tests (for the CI pipelines)

|===

You can also skip building the "essential" modules that are released, by adding the `-Dskip.essential`.
For example, to just build the xxx module, use:

[source,bash]
----
mvn clean install -Dmodule-xxx -Dskip.essential
----



== Checking for Vulnerabilities

Apache Causeway configures the link:https://www.owasp.org/index.php/Main_Page[OWASP] link:https://www.owasp.org/index.php/OWASP_Dependency_Check[dependency check] link:http://jeremylong.github.io/DependencyCheck/dependency-check-maven/index.html[Maven plugin] to determine whether the framework uses libraries that are known to have security vulnerabilities.

To check, run:

[source,bash]
----
mvn org.owasp:dependency-check-maven:aggregate -Dowasp
----

This will generate a single report under `target/dependency-check-report.html`.

[NOTE]
====
The first time this runs can take 10~20 minutes to download the NVD data feeds.
====

To disable, either run in offline mode (add `-o` or `--offline`) or omit the `owasp` property.


