How to build the OpenDominoAPI

This is a short description how to build the OpenNF Domino API. It describes how to:

• install Eclipse
• checkout a branch
• build the ODA with Maven

Installing Required Software

This section is for beginners; you can skip this if you already have a working Eclipse installation.

1. Install Eclipse Kepler or above

• Download Eclipse (Luna, IDE for Java Developers recommended)
• Extract the ZIP file to D:\OpenNTF\eclipse (or any other folder you want)
• Open Eclipse, specify a workspace directory (e.g. D:\OpenNTF\workspace)

There is no XPages SDK required anymore. You also don't need a Notes/Domino installation anymore if you just want to compile the plugin.

2. Install GIT

• Download GIT for Windows

3. Install Maven

• Download Maven (binary-zip)
• Extract the content of the ZIP file to D:\OpenNTF\maven (or any other folder you want) There should be a D:\OpenNTF\maven\bin folder now
• Add this folder to your Windows PATH environment variable

4. Install Java JDK

• JRE is not sufficient for building, so download a JDK (JDK-7 is prefered)
• Set the JAVA_HOME environment variable to the JDK path

5. Check Installation

• Open a "Git Bash" and check if the following commands are working:
  • git
  • echo $JAVA_HOME should report a path like C:\Program Files\Java\jdk1.8.0_40
  • mvn

6. Optional: Install Sourcetree

• Download SourceTree (or any other GIT tool)
• Install SourceTree: You do not need to create a Bitbucket account or add a SSH key in this step.
• Add a new project archive
• Source URL: https://github.com/OpenNTF/org.openntf.domino.git
  • Note: currently, the master branch is not Maven-ized. Choose one of the other branches, such as nathan, paul_new, or jesse
• Dest Path: D:\OpenNTF\org.openntf.domino
• (Optional) Add additonal remote origins: (e.g. https://github.com/rpraml/org.openntf.domino)
• Check out a working commit -- TODO --

Now you can start to build.

TODO: Describe how

Importing Projects Into Eclipse

Select 'File' > 'Import' > 'Maven' > 'Existing Maven Projects'. Select the folder D:\OpenNTF\org.openntf.domino. Import all maven projects. If some projects are greyed out, delete those from your Eclipse workspace first.

Recommended: Use [groupId].[artifactId] as "Name Template" EVERY time when importing Maven Projects.

TODO: The following steps must be reviewed, they are probably obsolete Downloading and Configuring the IBM Domino Update Site

To build the project, Maven requires access to Domino plugins in a usable format. IBM has provided a downloadable update site on OpenNTF to serve this need. To set it up, download the latest release and extract it to a known path on your computer, such as D:\OpenNTF\IBMUpdateSite.

Next, configure your local Maven settings.xml to specify a property in the current profile named notes-platform that points to this directory (the one containing artifacts.jar). For example:

<?xml version="1.0"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>main</id>
            <properties>
                <notes-platform>file:///D:/OpenNTF/IBMUpdateSite</notes-platform>
            </properties>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>main</activeProfile>
    </activeProfiles>
</settings>

This settings file is located in the .m2 directory of your home directory. Using Eclipse, it can be accessed from a link in the Preferences:

If you did not install the XPages SDK as above, you will also need to configure Eclipse to point to this update site in the Target Platform. This can be accomplished by editing the current Target Platform (or creating a new active one) and adding the downloaded folder as a "Directory" type location:

Required Java Versions and Environments

Currently, several components of the API require Java 6 to compile and will throw compilation errors relating to abstract methods if compiled with a newer version. On Windows, the JRE that ships with Notes and Domino (found in the jvm folder in the Notes/Domino installation directory) will suit. On Mac OS X, Apple's Java runtime is Java 6 and will still function on recent OS releases.

If you did not install the XPages SDK as above, you will also need to create a JRE named specifically XPages Domino JRE, pointing to the Java 6 runtime:

Additionally, this runtime should be marked as the default Execution Environment for JavaSE-1.6:

When running the Maven build from the command line, it is similarly important to run Maven using the Java 6 JRE. For example (on Mac OS X):

$ export JAVA_HOME=/System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
$ mvn install

Building and Accessing the API

Once the build environment is configured, the API can be built and packaged by running a Maven install, either from the command line via mvn install or via the "Run As" menu when right-clicking the domino project in Eclipse:

If the build is successful, an update site suitable for importing into an Update Site NSF or installing in Designer directly will be available as:

• org.openntf.domino/domino/org.openntf.domino.updatesite/target/site

Note: it is important to not build using the normal Eclipse mechanism of opening the site.xml file in the update site and using the "Build" button. Unfortunately, this is a limitation of Eclipse's interaction with Maven.

Eclipse Maven Errors

In a fresh Eclipse installation, after importing the Maven projects, it is possible that it will complain about missing lifecycle connectors. To fix this, hover over each error it mentions in the pom.xml files and choose the quick fix that searches for lifecycle connectors, then follow the installation process.