The 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 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.
Next up is to configure your user name and password; see also Apache's git docs:
git config user.name "My Name Here" git config user.email firstname.lastname@example.org
Next, configure the
core.autocrlf so that line endings are normalized to LF (Unix style) in the rep; again see Apache's git page:
git config core.autocrlf auto
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, theisis-1.0.0
tag on the origin will appear underorigin/isis-1.0.0`.
One final configuration that we recommend is for
git pull to perform a rebase by default, rather than a merge. This results in a linear log history. If you want to explicitly have branches in the history, then you can always create a topic branch, discussed below:
git config branch.autosetuprebase always
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
master branch from the central repo, called
For further reading, see:
Install Maven 3.0.x, downloadable here.
MAVEN_OPTS environment variable:
MAVEN_OPTS=-Xms512m -Xmx1024m -XX:MaxPermSize=128m
You can use any IDE to work with Isis, but most of the Isis committers tend to use Eclipse.
Make sure you are using a version of Eclipse that includes both the
m2e feature (Maven integration) and the
eGit feature (Git integration). Both 3.8 (2011) and 4.2 (2012) have these features bundled as part of the Java and JEE editions; or you can always install using
Help > Install New Software.
Next thing to do is to import the Isis projects into your workspace. This is done using
File > Import >Project:
On the next page, specify the root directory where you cloned the Isis repo. Eclipse will recursively find all the projects that make up Isis:
Finish; Eclipse should automatically build the entire codebase.
In the Juno release and later, this is now done automatically.
The next thing to do is to configure eGit so that you can use git commands within Eclipse. This is done by selecting all the projects in the
Package Explorer, then right clicking
Team > Share Project:
On the next page, choose the
Use or create repository in parent folder of project checkbox:
Finish and you are done.
Isis provides a number of Eclipse templates to help ensure that code is formatted according to our standards:
Windows > Preferences > Java > Code Style > Code Templates
Windows > Preferences > Java > Code Style > Formatter
Windows > Preferences > Java > Code Style > Organize Imports
Windows > Preferences > Java > Code Style > Clean Up
In addition, you will probably want to import the Java editor templates, as described in the getting started section.
It's a good idea to configure Eclipse's editors so that they highlight any accidental use of tabs instead of spaces, using:
Windows > Preferences > General > Editor > Text Editors
If you are either contributing to the JDO Objectstore, or even if you simply intend to use the latest-n-greatest version and build from source, then you should also configure the DataNucleus plugin for Eclipse. This does the job of bytecode-enhancing your domain objects.
See this page for details on how to setup the plugin.
You will also see that the page describes how to configure the
isis-objectstore-jdo-applib domain project with the DataNucleus enhancer.
Now you've set up your development environment the next thing to do is to build Isis from the command line.
All edits are reviewed before going live, so feel free to do much more than fix typos or links. If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it. Don't be surprised if we like it so much we ask you for help with other pages :)NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.