Git

The Isis source code lives in a git repo.

Installation

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:

git command line tool
gitk for viewing the commit history

If using Windows, note that github also have a dedicated Windows client. With a little 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 Sourcetree.

Cloning the Isis repo

First, clone the Isis repo.

If you are a committer, then clone from the Apache read/write repo:

git clone https://git-wip-us.apache.org/repos/asf/isis.git

If you are not a committer, please see the contributing page for details on which repo to clone from.

Configuring Git

Next up is to configure your user name and password; see also Apache’s git docs:

git config user.name "<i>My Name Here</i>"
git config user.email <i>myusername@apache.org</i>

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 origin/xxx. For example, the`isis-1.0.0`tag on the origin will appear under`origin/isis-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 Atlassian SourceTree.

For further reading, see:

Installing Maven

Install Maven 3.0.x, downloadable here.

Set MAVEN_OPTS environment variable:

MAVEN_OPTS=-Xms512m -Xmx1024m -XX:MaxPermSize=256m

Previously we suggested 128m for the MaxPermSize, but that would no longer seem to be sufficient.

Building all of Isis

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 Isis prerequisites.

Thereafter you can speed up the build by adding the -o (offline flag):

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.