Skip to content
This repository has been archived by the owner on Jan 21, 2024. It is now read-only.

Development Environment

Jump to bottom
Paul Withers edited this page Sep 9, 2019 · 9 revisions

The project uses GitFlow and Maven, which may be new to developers. But it's not just a case of downloading the project and opening it. There are two other projects required for setting up the environment - XPages SDK to map to a Domino target platform and the Domino plugins as a p2 repository so Maven can use them. The following is adapted from an OpenNTF Blog from November 2014.

  1. You will need a Java SDK. Oracle licensing has changed. You should use OpenJ9, which is the basis also of the Domino Java JRE. There is a version of Java 8 available. During installation, ensure the option to set JAVA_HOME environment variable is ticked, if this is the first Java version installation you're doing.
**Did I Get This Right?**

You can check by, after installing, opening up a new command prompt window and running the command SET JAVA_HOME. If it returns a filepath, the environment variable is set. If it says the environment variable is not defined, it needs setting.

How Do I Fix This?

Re-running the installer should allow you to change the options, including setting this environment variable. Alternatively, you can set it manually (it's widely documented on the internet).

  1. You will need a version of Git that includes the AVH Edition of GitFlow (https://github.com/petervanderdoes). It is included in Git for Windows as of 2.6.4 - in SourceTree, Tools > Options, Git tab, "Git Version" at the bottom will show you that. For other platforms, see installation instructions.

  2. You will also need Maven. For building the Extension Library, it's possible to build in Eclipse if you wish, but Maven build commands are very straightforward. But Maven is needed to create the Domino plugins as a p2 repository. These cannot be circulated by OpenNTF. Download and install from the Maven site.

  3. Strongly recommended is using a local Domino server. The Community Edition is free, start [here](Try today for 30 days at no cost and join us in the next era of rapid application development.]. Download and install.

  4. This step may be improved in time. Go to the generate-domino-update-site repo on OpenNTF's Stash. Clone the master branch (the "download" button in the left-hand menu below the folder button). The instructions are in the repo's README, but to put in plainer English:

  • In a command line, "cd" to the generate-domino-update-site folder which contains the pom.xml.
  • Issue the command mvn install to build the repo and the code we'll be using in the next command.
  • Issue the third command which runs a jar file. The Dsrc parameter set to the folder of your folder, which contains the notes.ini. The Ddest parameter is where you want to write the output to. Remember this, we'll need it later. I use C:\UpdateSite on Windows. Example command: mvn org.openntf.p2:generate-domino-update-site:generateUpdateSite -Dsrc="C:\Program Files\IBM\Domino" -Ddest="C:\UpdateSite"

  1. Install Eclipse for RCP and RAP Developers. The good thing about Eclipse is you can install multiple versions and since the blog was first written in 2014 Eclipse is now an installer on Windows. I'd strongly recommend the latest version.

  2. Start up Eclipse, go to Help > Eclipse Marketplace.... In the dialog, search for XPages. You will be able to install the XPages SDK plugin into Eclipse.

  3. Configure Eclipse for XPages. This requires pointing to your environment, in Windows > Preferences.

  • In the XPages SDK preference page, point to your Domino server environment. If you tick "Automatically create JRE for..." you'll get a JRE created.
  • In the Java > Installed JREs preference page, tick the relevant environment. This is what Eclipse will compile when saving Java code, and will use the JAR files available on the Domino server.
  • In the Plugin Development > Target Platform preference page, create a new target definition using "Add..." button. The templates don't work (I can't see any reason or see what's changed in Eclipse to stop them working). Start with "Nothing", it's very easy. On the Locations tab, point to the p2 repository created in step 4, which I saved to C:\UpdateSite. With Domino 10.0.1 it should then say you have 189 plug-ins available. On the Environment tab set the Java Runtime Environment to the JRE created by XPage SDK, XPages Domino JRE. To build successfully, we need both the JRE and the p2-enabled Domino JARs.

  1. Fork this repo to your own GitHub. Use the feature branch corresponding to the current Domino version as your starting point. The format is server version (e.g. 10.0.1) + "v" + minimum FP version required + "" + version number, e.g. 10.0.1_v00_01.

  2. Pull down a local repository from your GitHub repository. Most Domino developers use SourceTree for interaction with GitHub. You can clone a repository and point to the URL of your GitHub repository.

  3. Import the plugin projects into Eclipse. There is a significant difference for importing any plugins that use Maven (they're easy to spot because they will include a pom.xml in each plugin). You need to select File > Import, then choose Maven > Existing Maven Projects.

  4. When prompted to setup Maven plugin connectors, do so. These are the tycho plugins required for Eclipse to kick off the maven build process.

  5. To build, just right-click the com.ibm.xsp.extlib.parent project and select Run As > Maven Install. All projects in the Extension Library will be built directly in Eclipse.

ADDENDUM notes.jar is a restricted jar file. So if it's not already been changed, you will need to go to Window > Preferences and go to the Java > Compiler > Errors/Warnings and in the Deprecated and restricted API section change Forbidden reference (access rules) from Error to at the highest Warning.

See the separate contributing.md page for details on how to submit pull requests in the preferred way.

Clone this wiki locally