Development Setup Instructions
We use Eclipse
- as our development environment of Buildship and
- as our target platform against which we compile and run Buildship.
This page describes the steps to set up Eclipse such that it can be used for development of Buildship.
In order to provide an easy-to-setup and consistent working environment for development, we use Oomph, the new default Eclipse installer. Oomph is a model-based tool to install custom Eclipse distributions. The model instructs Oomph to set up the environment such that
- the JDK is aligned to the project
- the target platform is set
- the Buildship git repository is cloned and imported into the workspace
- the code formatter settings are customized
1. Install Oomph
The latest version of Oomph is available at the project's wiki page. Download and extract the binary that matches your environment. When you start Oomph, click the Advanced Mode icon. You should then see the screen below. Select Eclipse IDE for Eclipse committers. Check if the VM and the Bundle pool have proper values. Then click Next.
2. Configure the Buildship model
The Buildship setup model is available in the Oomph project catalog under the GitHub projects, just select it and hit next.
3. Specify installation properties
On the properties screen you have to specify the environment-specific variables:
- the location of the custom Eclipse distribution
- the location of workspace and the git clone
- the JDK
- the target platform against the project is compiled
When done, the configuration should like the screen below. Click Next and Finish to start the installation.
Note that if you to run the installer multiple times, Oomph might remember some of the preferences. To make all variables visible, enable the Show all variables checkbox.
4. Start the IDE
Once the installer finishes, the IDE will start up automatically. There are a few setup tasks running on startup (importing projects, setting up preferences). Wait for these to finish before doing anything! Once finished, you should see the workspace below.
Change the target platform
The target platform selected during the installation can be changed, even if it is a bit hidden. In the main menu, click Help > Perform Setup tasks then click Back. Select the Show all variables checkbox and change the Buildship Target Platform to the desired version. Click Next and Finish, then wait for the target platform to download. Once finished, the source code will be compiled against the new target platform.
Manual setup (deprecated)
Getting the source code
The project and its source code is hosted on GitHub:
Apply the following command to get a clone of the source code:
git clone firstname.lastname@example.org:eclipse/buildship.git
Navigate into the created buildship directory and set the git username and email address:
git config user.name "johnsmith" git config user.email "email@example.com"
And make sure to properly map the part before the domain of your email address in TeamCity under My Settings & Tools >> General >> Version Control Username Settings >> Default for all of the Git roots.
From now on, when you commit to the buildship project through Git, the change will be properly associated with your user in TeamCity. You can verify that the setup is correct by seeing your full name next to each commit.
In order to avoid extra commits in the Git history after merging local changes with remote changes, apply the rebase strategy when pulling in the remote changes. By applying the update alias listed below, you can conveniently pull in the remote changes from master without ending up with ‘merge branch’ commits in the Git history later on.
git config --global alias.update=“pull --rebase origin master” git update
Importing the source code into Eclipse
The source code consists of a single root project and several sub-projects nested within it. You can use the generic Eclipse 'Import Existing Projects' wizard. Select the root folder buildship and check the option 'Search for nested projects'. Select all com.gradleware.* projects. You can then press Finish.
Setting the target platform
After importing all the projects into Eclipse, there will be some build errors due to code references to missing plugins. To add these missing plugins to Eclipse, open the tooling-e45.target file (or the one matching your desired target platform version) located in the project root folder and click Set as Target Platform in the top-right corner. This will fix all compilation issues. Note that this might take a while since the entire SDK for the specified Eclipse version will be downloaded.
Running the tests in Eclipse
To run the complete set of core tests from inside Eclipse, right-click on the org.eclipse.buildship.core.test package and choose Run As >> JUnit Plug-In-Test. Individual tests can be run the same way.
To run the complete set of ui tests from inside Eclipse, right-click on the org.eclipse.buildship.ui.test package and choose Run As >> Run Configurations.... In the shown dialog, create a new JUnit Plug-In-Test run configuration. Select the Test tab and ensure that the Run in UI thread checkbox is unchecked, then click Run (Buildship uses SWTBot tests, which must be run in a non-UI thread). When running the UI tests in the future, click on the org.eclipse.buildship.ui.test package and choose Run As >> JUnit Plug-In-Test since the run configurations are saved. Individual tests can be run the same way.
Tracing can be enabled in the Tracing tab of the Run Configurations... dialog.
Running the Build
To run the full build, execute
The final P2 repository will be created in the
org.eclipse.buildship.site/build/repository directory. If
the target platform had not been downloaded previously, it will appear in the ~/.tooling/eclipse/targetPlatforms folder.
To run the build without running the tests, exclude the
./gradlew build -x eclipseTest
To have full build ids in the name of the generated jars and in the manifest files, set the
build.invoker property to ci:
./gradlew build -Pbuild.invoker=ci
The available target platforms are defined in the root project's build.gradle file, under the eclipseBuild node.
By default, the build runs against target platform version 45. To build against a different target platform version,
you can set the
eclipse.version Gradle project property:
./gradlew build -Peclipse.version=44
Buildship is continuously built on our Continuous Integration Server.
All issues related to Buildship are recorded in Bugzilla.
The following workflow is applied to all Buildship issues tracked in Bugzilla:
- The reporter creates the issue.
- Once the issue is understood by the committers and the issue is about to be fixed, the state is set to assigned.
- After the issue is fixed and a snapshot version with the fix is released, the state is changed to resolved.
- The committer waits for a few days for the reporter to set the state to verified.
- Once verification is received or no feedback is received, the committer sets the state to closed.