#

## Hacking JEuclid

### Prerequisites

To work with the JEuclid source, you will need to download and install

- Subversion

- Maven

- Sun or Apple Java SDK >= 1.6 (others are untested)

- Eclipse (optional) or NetBeans (optional)

- Maven 2.x Plug-in for Eclipse (required if you use Eclipse)

- Maven 2.x Plug-in for NetBeans (required if you use NetBeans)

If you have commit access, the following extra plug-ins for eclipse are highly recommended:

- Subclipse

- Eclipse Checkstyle Plugin

- Eclipse TestNG Plugin

### Building the source

You can access the source code as described on the JEuclid repository site.

Once you have the code available, use Maven to build and package the code. Here are the most common commands:

- `mvn install` will compile, test, bundle, and install JEuclid locally. Use this command if you are not sure what else to use

- `mvn scm:update` will retrieve the newest version from the source repository

- `mvn clean` will remove the target directories, forcing a clean build

- `mvn compile site` will create the updated website, so you can check the reports

- `mvn test` will compile and run the tests

First time builders may have to install the "support" package before any of the other modules can be compiled. This package contains dependencies for all builds, such as the checkstyle configuration, and some fonts.

The results of these commands can be found in the `target/` directory of each module.

The most notable artifacts are in `jeuclid/target` `jeuclid-...-distribution.zip` (binary distribution) and `jeuclid-...-osx.zip` (OS X application bundle).

If you get an out of memory error during build, you need to adjust the memory available to maven. You can do this by setting the `MAVEN_OPTS` environment variable to `-Xmx512m`

### Preparing a patch

To create a patch, please execute `mvn scm::diff`. The resulting patch will be saved as `jeuclid.diff`. Please rename your patch before submitting it through issue tracking.

When you create a patch please:

- Add a test if possible (in directory `src/test/java/net/sourceforge/jeuclid/` for the module)

- Provide a short entry for the changelog in `src/changes/changes.xml` (main module)

- Try to follow the coding style

Please note: By submitting a patch, you agree to publish it under the same license as the rest of JEuclid (ASLv2).

### Coding Rules

The coding guidelines are given as a set of Checkstyle rules. Please run checkstyle with `mvn checkstyle:checkstyle` and view the results in `target/target/checkstyle-result.xml` or `target/site/checkstyle.html`. The ruleset is listed on the Checkstyle results page and explained on the Checkstyle Standard Checks page.

You can generate a set of reports on your coding style by calling `mvn site` and viewing the result in the `target/site` directory. You should try not to introduce any new violations.

### Developers

Your should login to SVN with your sourceforge username and password. It should ask you for it the first time you try to submit

When you add new Java files, please set the property `svn:keywords` to `Revision Date Id`. You can do this automatically on Unix by running the `svnproperties.sh` script.

For some features you'll need to tell maven about your sourceforge account. You can to that by adding the following to your `~/.m2/settings.xml` file (if this file does not exist, create it with these contents). Replace `YOUR_SF_ID` with your sourceforge username, and `/path/to/ssh/id_dsa` with the path to your SSH id file.

    <settings xmlns="http://maven.apache.org/POM/4.0.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                          http://maven.apache.org/xsd/settings-1.0.0.xsd">
      <servers>
        <server>
          <id>sourceforgejeuclid</id>
          <username>YOUR_SF_ID,jeuclid</username>
          <privateKey>/path/to/ssh/id_dsa</privateKey>
          <filePermissions>664</filePermissions>
          <directoryPermissions>775</directoryPermissions>
        </server>
      </servers>
    </settings>