| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <title>Building Apache Isis :: Apache Isis</title> |
| <link rel="canonical" href="https://isis.apache.org/conguide/2.0.0-M3/building-apache-isis.html"> |
| <meta name="generator" content="Antora 2.2.0"> |
| <link rel="stylesheet" href="../../_/css/site.css"> |
| <link rel="stylesheet" href="../../_/css/site-custom.css"> |
| <link href="https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,700,700i|Raleway:300,400,500,700,800|Montserrat:300,400,700" rel="stylesheet"> |
| <link rel="home" href="https://isis.apache.org" title="Apache Isis"> |
| <link rel="next" href="building-docs-and-website.html" title="Building Docs and Website"> |
| <link rel="prev" href="contributing.html" title="Contributing"> |
| </head> |
| <body class="article"> |
| <header class="header"> |
| <nav class="navbar"> |
| <div class="navbar-brand"> |
| <a class="navbar-item" href="https://isis.apache.org"> |
| <span class="icon"> |
| <img src="../../_/img/isis-logo-48x48.png"></img> |
| </span> |
| <span>Apache Isis</span> |
| </a> |
| <button class="navbar-burger" data-target="topbar-nav"> |
| <span></span> |
| <span></span> |
| <span></span> |
| </button> |
| </div> |
| <div id="topbar-nav" class="navbar-menu"> |
| <a class="navbar-end"> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Quick Start</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Starter Apps</span> |
| <a class="navbar-item" href="../../docs/latest/starters/helloworld.html">Hello World</a> |
| <a class="navbar-item" href="../../docs/latest/starters/simpleapp.html">Simple App</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Demos & Tutorials</span> |
| <a class="navbar-item" href="../../docs/latest/demo/about.html">Demo App</a> |
| <a class="navbar-item" href="https://danhaywood.gitlab.io/isis-petclinic-tutorial-docs/petclinic/1.16.2/intro.html">Petclinic (tutorial)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Resources</span> |
| <a class="navbar-item" href="../../docs/latest/resources/cheatsheet.html">Cheatsheet</a> |
| <a class="navbar-item" href="../../docs/latest/resources/icons.html">Icons</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Guides</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Development</span> |
| <a class="navbar-item" href="../../setupguide/latest/about.html">Setup Guide</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Core</span> |
| <a class="navbar-item" href="../../userguide/latest/about.html">User Guide</a> |
| <a class="navbar-item" href="../../refguide/latest/about.html">Reference Guide</a> |
| <a class="navbar-item" href="../../testing/latest/about.html">Testing Guide</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Libraries</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">For Use in Apps</span> |
| <a class="navbar-item" href="../../subdomains/latest/about.html">Subdomain Libraries</a> |
| <a class="navbar-item" href="../../valuetypes/latest/about.html">Value Types</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Integrate between Apps</span> |
| <a class="navbar-item" href="../../mappings/latest/about.html">Bounded Context Mapping Libraries</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Other</span> |
| <a class="navbar-item" href="../../incubator/latest/about.html">Incubator</a> |
| <a class="navbar-item" href="../../legacy/latest/about.html">Legacy</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Components</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Viewers</span> |
| <a class="navbar-item" href="../../vw/latest/about.html">Wicket UI</a> |
| <a class="navbar-item" href="../../vro/latest/about.html">Restful Objects (REST)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Security</span> |
| <a class="navbar-item" href="../../security/latest/about.html">Security Guide</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Persistence</span> |
| <a class="navbar-item" href="../../pjdo/latest/about.html">DataNucleus (JDO)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Extensions</span> |
| <a class="navbar-item" href="../../extensions/latest/about.html">Extensions Catalog</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Support</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Contact</span> |
| <a class="navbar-item" href="../../docs/latest/support/slack-channel.html">Slack</a> |
| <a class="navbar-item" href="../../docs/latest/support/mailing-list.html">Mailing Lists</a> |
| <a class="navbar-item" href="https://issues.apache.org/jira/browse/ISIS">JIRA</a> |
| <a class="navbar-item" href="https://stackoverflow.com/questions/tagged/isis">Stack Overflow</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Releases</span> |
| <a class="navbar-item" href="../../docs/latest/downloads/how-to.html">Downloads</a> |
| <a class="navbar-item" href="../../relnotes/latest/about.html">Release Notes</a> |
| <a class="navbar-item" href="../../docs/latest/archive/1-x.html">Archive (1.x)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Framework</span> |
| <a class="navbar-item" href="../../conguide/latest/about.html">Contributors' Guide</a> |
| <a class="navbar-item" href="../../comguide/latest/about.html">Committers' Guide</a> |
| <a class="navbar-item" href="../../core/latest/about.html">Core Design</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">ASF</a> |
| <div class="navbar-dropdown"> |
| <a class="navbar-item" href="http://www.apache.org/">Apache Homepage</a> |
| <a class="navbar-item" href="https://www.apache.org/events/current-event">Events</a> |
| <a class="navbar-item" href="https://www.apache.org/licenses/">Licenses</a> |
| <a class="navbar-item" href="https://www.apache.org/security/">Security</a> |
| <a class="navbar-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| <a class="navbar-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| <hr class="navbar-divider"/> |
| <a class="navbar-item" href="https://whimsy.apache.org/board/minutes/Isis.html">PMC board minutes</a> |
| </div> |
| </div> |
| <a class="navbar-item" href="../../docs/latest/about.html"> |
| <span class="icon"> |
| <img src="../../_/img/home.png"></img> |
| </span> |
| </a> |
| </div> |
| </div> |
| </nav> |
| </header> |
| <div class="body "> |
| <div class="nav-container" data-component="conguide" data-version="2.0.0-M3"> |
| <aside class="nav"> |
| <div class="panels"> |
| <div class="nav-panel-pagination"> |
| <a class="page-previous" rel="prev" href="contributing.html" title="Contributing"><span></span></a> |
| <a class="page-next" rel="next" |
| href="building-docs-and-website.html" title="Building Docs and Website"><span></span></a> |
| <!-- |
| page.parent doesn't seem to be set... |
| <a class="page-parent disabled" rel="prev" href="" title="Contributing"><span></span></a> |
| --> |
| </div> |
| <div class="nav-panel-menu is-active" data-panel="menu"> |
| <nav class="nav-menu"> |
| <h3 class="title"><a href="about.html">Contributors' Guide</a></h3> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="contributing.html">Contributing</a> |
| </li> |
| <li class="nav-item is-current-page" data-depth="1"> |
| <a class="nav-link" href="building-apache-isis.html">Building Apache Isis</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="building-docs-and-website.html">Building Docs and Website</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="#asciidoc-syntax.adoc">Asciidoc Syntax</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="agilej.html">AgileJ</a> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="git/about.html">Git Cookbook</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </div> |
| <div class="nav-panel-explore" data-panel="explore"> |
| <div class="context"> |
| <span class="title">Contributors' Guide</span> |
| <span class="version">2.0.0-M3</span> |
| </div> |
| <ul class="components"> |
| <li class="component"> |
| <span class="title"> </span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../docs/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">BC Mappings Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../mappings/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Committers' Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../comguide/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component is-current"> |
| <span class="title">Contributors' Guide</span> |
| <ul class="versions"> |
| <li class="version is-current is-latest"> |
| <a href="about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Design Docs</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../core/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Extensions Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../extensions/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Incubator Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../incubator/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">JDO/DataNucleus</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../pjdo/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Legacy Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../legacy/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Reference Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../refguide/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Release Notes</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../relnotes/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Restful Objects Viewer</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../vro/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Security Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../security/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Setup Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../setupguide/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Subdomains Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../subdomains/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Testing Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../testing/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">User Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../userguide/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Value Types Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../valuetypes/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Wicket Viewer</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../vw/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </aside> |
| </div> |
| <main role="main"> |
| <div class="toolbar" role="navigation"> |
| <button class="nav-toggle"></button> |
| <a href="../../docs/2.0.0-M3/about.html" class="home-link"></a> |
| <nav class="breadcrumbs" aria-label="breadcrumbs"> |
| <ul> |
| <li><a href="about.html">Contributors' Guide</a></li> |
| <li><a href="building-apache-isis.html">Building Apache Isis</a></li> |
| </ul> |
| </nav> |
| <div class="edit-this-page"><a href="https://github.com/apache/isis/edit/2.0.0-M3/antora/components/conguide/modules/ROOT/pages/building-apache-isis.adoc">Edit</a></div> |
| </div> |
| <article class="doc"> |
| <a name="section-top"></a> |
| <h1 class="page">Building Apache Isis</h1> |
| <div class="sect1"> |
| <h2 id="git"><a class="anchor" href="#git"></a>Git</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The Apache Isis source code lives in a git repo.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="installation"><a class="anchor" href="#installation"></a>Installation</h3> |
| <div class="paragraph"> |
| <p>The easiest place to get hold of command-line git is probably the <a href="http://git-scm.com/downloads">github download page</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <a class="image" href="_images/building-apache-isis/setting-up-git.png"><img src="_images/building-apache-isis/setting-up-git.png" alt="setting up git" width="350px"></a> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Once git is installed, the two main command line tools to note are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>git</code> command line tool</p> |
| </li> |
| <li> |
| <p><code>gitk</code> for viewing the commit history</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If using Windows, note that github also have a dedicated <a href="https://help.github.com/articles/set-up-git">Windows client</a>. With a little <a href="http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx">hacking around</a>, it can also be made to work with non-github repositories.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If using Mac, you might also want to check out Atlassian’s <a href="http://www.atlassian.com/software/sourcetree/overview">Sourcetree</a>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="cloning-the-apache-isis-repo"><a class="anchor" href="#cloning-the-apache-isis-repo"></a>Cloning the Apache Isis repo</h4> |
| <div class="paragraph"> |
| <p>First, clone the Apache Isis repo:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">git clone https://github.com/apache/isis.git</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="configuring-git"><a class="anchor" href="#configuring-git"></a>Configuring Git</h4> |
| <div class="paragraph"> |
| <p>Next up is to configure your user name and password:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">git config user.name "<em>My Name Here</em>" |
| git config user.email <em>myusername@apache.org</em></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Next, configure the <code>core.autocrlf</code> so that line endings are normalized to LF (Unix style) in the rep; again see <a href="https://git-wip-us.apache.org/">Apache’s git</a> page:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>on Windows, use:<br></p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">git config core.autocrlf true</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>on Mac/Linux, use:<br></p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">git config core.autocrlf input</code></pre> |
| </div> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>We also recommend setting <code>core.safecrlf</code>, which aims to ensure that any line ending conversion is repeatable. Do this on all platforms:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">git config core.safecrlf true</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that these settings are supplemented in the repo by the <code>.gitattributes</code> file and that explicitly specifies line handling treatment for most of the common file types that we have.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Next, we recommend you setup this a refspec so that you can distinguish remote tags from local ones. To do that, locate the <code>[remote "origin"]</code> section in your <code>.git/config</code> and add the third entry shown below:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">[remote "origin"] |
| url = ... whatever ... |
| fetch = ... whatever ... |
| fetch = +refs/tags/*:refs/tags/origin/*</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will ensure that a <code>git fetch</code> or <code>git pull</code> places any remote tags under <code>origin/xxx</code>. For example, the <code>isis-1.0.0</code> tag on the origin will appear under <code>origin/isis-1.0.0</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you don’t use git outside of Apache, you can add the <code>--global</code> flag so that the above settings apply for all repos managed by git on your PC.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="getting-help"><a class="anchor" href="#getting-help"></a>Getting help</h3> |
| <div class="paragraph"> |
| <p>Three commands of git that in particular worth knowing:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>git help <em>command</em></code><br></p> |
| <div class="paragraph"> |
| <p>will open the man page in your web browser</p> |
| </div> |
| </li> |
| <li> |
| <p><code>git gui</code><br></p> |
| <div class="paragraph"> |
| <p>will open up a basic GUI client to staging changes and making commits.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>gitk --all</code><br></p> |
| <div class="paragraph"> |
| <p>will open the commit history for all branches. In particular, you should be able to see the local <code>master</code>, which branch you are working on (the <code>HEAD</code>), and also the last known position of the <code>master</code> branch from the central repo, called <code>origin/master</code>.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>You might also want to explore using a freely available equivalent such as <a href="https://www.sourcetreeapp.com/">Atlassian SourceTree</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For further reading, see:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="http://www.kernel.org/pub/software/scm/git/docs/git-config.html">git config man page</a></p> |
| </li> |
| <li> |
| <p><a href="http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html">.gitattributes man page</a></p> |
| </li> |
| <li> |
| <p><a href="http://git-scm.com/docs/gitattributes">.gitattributes git-scm.com docs</a></p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="installing-java"><a class="anchor" href="#installing-java"></a>Installing Java</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Apache Isis is compatible with Java 7 and Java 8. For every-day use, the framework is usually compiled against Java 8.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Releases however are <a href="../../comguide/2.0.0-M3/cutting-a-release.html" class="page">cut</a> using Java 7, leveraging the <a href="http://maven.apache.org/plugins/maven-toolchains-plugin/">Maven toolchains plugin</a>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Therefore install either/both of Java 7 JDK and Java 8 JDK. Note that the JRE is <em>not</em> sufficient.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>If you intend to contribute back patches to Apache Isis, note that while you can develop using Java 8 within your IDE, |
| be sure not to use any Java 8 APIs.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="configure-maven-toolchains-plugin"><a class="anchor" href="#configure-maven-toolchains-plugin"></a>Configure Maven toolchains plugin</h3> |
| <div class="paragraph"> |
| <p>If you are a committer that will be performing releases of Apache Isis, then you <em>must</em> configure the |
| <a href="http://maven.apache.org/plugins/maven-toolchains-plugin/">toolchains</a> plugin so that releases can be built using |
| Java 7.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This is done by placing the <code>toolchains.xml</code> file in <code>~/.m2</code> directory. Use the following file as a template, |
| adjusting paths for your platform:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF8"?> |
| <toolchains> |
| <toolchain> |
| <type>jdk</type> |
| <provides> |
| <version>1.8</version> |
| <vendor>oracle</vendor> |
| </provides> |
| <configuration> |
| <jdkHome>/usr/lib64/jvm/jdk1.8.0_65</jdkHome> |
| <!-- |
| <jdkHome>c:\Program Files\Java\jdk1.8.0_65</jdkHome> |
| --> |
| </configuration> |
| </toolchain> |
| <toolchain> |
| <type>jdk</type> |
| <provides> |
| <version>1.7</version> <i class="conum" data-value="1"></i><b>(1)</b> |
| <vendor>oracle</vendor> |
| </provides> |
| <configuration> |
| <jdkHome>/usr/lib64/jvm/jdk1.7.0_79</jdkHome> |
| <!-- |
| <jdkHome>c:\Program Files\Java\jdk1.7.0_79</jdkHome> |
| --> |
| </configuration> |
| </toolchain> |
| </toolchains></code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>The Apache Isis build is configured to search for the (<code>1.7, oracle</code>) JDK toolchain.</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The Apache Isis parent <code>pom.xml</code> activates this plugin whenever the <code>apache-release</code> profile is enabled.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="installing-maven"><a class="anchor" href="#installing-maven"></a>Installing Maven</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Install Maven 3.0.x, downloadable <a href="http://maven.apache.org/download.html">here</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Set <code>MAVEN_OPTS</code> environment variable:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">export MAVEN_OPTS="-Xms512m -Xmx1024m"</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="building-all-of-apache-isis"><a class="anchor" href="#building-all-of-apache-isis"></a>Building all of Apache Isis</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>To build the source code from the command line, simply go to the root directory and type:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mvn clean install</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The first time you do this, you’ll find it takes a while since Maven needs to download all of the Apache Isis prerequisites.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Thereafter you can speed up the build by adding the <code>-o</code> (offline flag). To save more time still, we also recommend that you build in parallel. (Per this <a href="http://zeroturnaround.com/rebellabs/your-maven-build-is-slow-speed-it-up/">blog post</a>), you could also experiment with a number of JDK parameters that we’ve found also speed up Maven:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">export MAVEN_OPTS="-Xms512m -Xmx1024m -XX:+TieredCompilation -XX:TieredStopAtLevel=1" |
| mvn clean install -o -T1C</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When using Eclipse, a Maven profile is configured such that Eclipse compiles to <code>target-ide</code> directory rather than the usual <code>target</code> directory. You can therefore switch between Eclipse and Maven command line without one interfering with the other.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="checking-for-vulnerabilities"><a class="anchor" href="#checking-for-vulnerabilities"></a>Checking for Vulnerabilities</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Apache Isis configures the <a href="https://www.owasp.org/index.php/Main_Page">OWASP</a> <a href="https://www.owasp.org/index.php/OWASP_Dependency_Check">dependency check</a> <a href="http://jeremylong.github.io/DependencyCheck/dependency-check-maven/index.html">Maven plugin</a> to determine whether the framework uses libraries that are known to have security vulnerabilities.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To check, run:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mvn org.owasp:dependency-check-maven:aggregate -Dowasp</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will generate a single report under <code>target/dependency-check-report.html</code>.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The first time this runs can take 10~20 minutes to download the NVD data feeds.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>To disable, either run in offline mode (add <code>-o</code> or <code>--offline</code>) or omit the <code>owasp</code> property.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="checking-for-use-of-internal-jdk-apis"><a class="anchor" href="#checking-for-use-of-internal-jdk-apis"></a>Checking for use of internal JDK APIs</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Apache Isis configures the <a href="https://maven.apache.org/plugins-archives/maven-jdeps-plugin-3.0.0/">jdeps maven plugin</a> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To check, run:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mvn clean install -Djdeps</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will fail the build on any module that currently uses an internal JDK API.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>At the time of writing the <code>isis-core-schema</code> module fails the build.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| </article> |
| <aside class="article-aside toc" role="navigation"> |
| <p class="toc-title">On this page</p> |
| <div id="article-toc"></div> |
| </aside> |
| </main> |
| </div> |
| <footer class="footer"> |
| <div class="content"> |
| <div class="copyright"> |
| <p> |
| Copyright © 2010~2020 The Apache Software Foundation, licensed under the Apache License, v2.0. |
| <br/> |
| Apache, the Apache feather logo, Apache Isis, and the Apache Isis project logo are all trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| <div class="revision"> |
| <p>Revision: SNAPSHOT</p> |
| </div> |
| </div> |
| </footer> |
| <script src="../../_/js/site.js"></script> |
| <script async src="../../_/js/vendor/highlight.js"></script> |
| <script src="../../_/js/vendor/jquery-3.4.1.min.js"></script> |
| <script src="../../_/js/vendor/jquery-ui-1.12.1.custom.widget-only.min.js"></script> |
| <script src="../../_/js/vendor/jquery.tocify.min.js"></script> |
| |
| <script> |
| $(function() { |
| $("#article-toc").tocify( { |
| showEffect: "slideDown", |
| hashGenerator: "pretty", |
| hideEffect: "slideUp", |
| selectors: "h2, h3", |
| scrollTo: 120, |
| smoothScroll: true, |
| theme: "jqueryui", |
| highlightOnScroll: true |
| } ); |
| }); |
| </script> |
| </body> |
| </html> |
