This document describes the development environment and the development / release process for the Sculptor project:
- Source Code
- Development process
- Release process
To develop Sculptor you need local installations of the following tools:
- git (1.8 or newer)
- git workflow extension git-flow
- Java JDK (1.7 or newer)
- Maven (3.2.1 or newer)
- Eclipse (4.3 or newer) with Xtext (2.7.2 or newer)
- (optional) GraphViz (2.2.8 or newer)
The installation and configuration of these tools is described in Sculptors installation guide.
Maven Repository Manager
To improve development experience it’s recommended to install a Maven repository manager like Sonatype Nexus. Instead letting the Sculptors Maven build access the external Maven repositories directly the repository manager is used as a proxy. This proxy greatly reduces the network access because all Maven artifacts are only retrieved once and then managed by the local repository manager.
After the successfully installation (as described in Sculptors installation guide) some additional configurations are necessary.
Eclipse text file encoding
Sculptors code generator templates are implemented with Xtext template expressions. These templates are using special tag brackets (guillemets), for which the characters
00BB) are used. The downside with the guillemets used in the templates is that you will have to have a consistent encoding (here
So it’s necessary to set the default encoding in Eclipse to ISO-8859-1 via “Preferences > General > Workspace > Text file encoding > ISO-8859-1”.
As mentioned here this encoding is used in the development of Xtext as well.
The Maven “settings.xml” needs some customizations. This file may be found (depending on your OS) in:
- *nix and Mac:
C:\Documents and Settings\$USER$\.m2
In this file we have to make the following modifications:
Maven repository manager
<profiles> <profile> <id>nexus</id> <mirrors> <!--This sends all request for the dummy URL http://central to the local Nexus instance --> <mirror> <id>nexus</id> <mirrorOf>central</mirrorOf> <url>http://localhost:8081/nexus/content/groups/public/</url> </mirror> </mirrors> <!-- Enable redirection of Maven Central to local Nexus via mirror with dummy URL http://central --> <repositories> <repository> <id>central</id> <url>http://central</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>true</enabled></snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>central</id> <url>http://central</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>true</enabled></snapshots> </pluginRepository> </pluginRepositories> </profile> </profiles> <activeProfiles> <!--make the profile active all the time --> <activeProfile>nexus</activeProfile> </activeProfiles>
Usage of the local repository manager can be (temporarily) turned-off by disabling the coresponding Maven profile via the commandline option
Eclipse p2 repository mirror
To use the local Eclipse p2 repository mirror (created by the Sculptor build via Eclipse Tycho) for requests to the external Eclipse p2 repositories an additional Maven profile with corresponding
<mirror/> settings are necessary, e.g.
<profiles> <profile> <id>p2-mirror</id> <mirrors> <mirror> <!-- This sends requests to p2 repositories to local mirror --> <id>mirror</id> <mirrorOf>p2.eclipse,p2.eclipse.xtext,p2.xtext-utils</mirrorOf> <url>"location of your Sculptor repository clone"/devtools/eclipse-mirror/.p2-mirror/</url> <layout>p2</layout> <mirrorOfLayouts>p2</mirrorOfLayouts> </mirror> </mirrors> </profile> </profiles> <activeProfiles> <!--make the profile active all the time --> <activeProfile>p2-mirror</activeProfile> </activeProfiles>
The repository IDs listed in the
Usage of the local p2 repository mirror can be (temporarily) turned-off by disabling the coresponding Maven profile via the commandline option
Deployment to GitHub
For deploying the Eclipse plugin to GitHub the GitHub user credentials have to be defined in the
<servers/> section, e.g.
<servers> <server> <id>github</id> <username>your-username</username> <password>your-password</password> </server> </servers>
The server ID is referenced by the GitHub site-maven-plugin used in the
Deployment to Sonatype OSS Repository Hosting Service
For deploying the Maven plugin to Sonatypes OSS Repository Hosting (OSSRH) service the Sonatype user credentials have to be defined in the
<servers/> section, e.g.
<servers> <server> <id>sonatype-nexus-snapshots</id> <username>your-username</username> <password>your-password</password> </server> <server> <id>sonatype-nexus-staging</id> <username>your-username</username> <password>your-password</password> </server> </servers>
The server IDs are referenced by the distribution repositories defined the Sonatype
oss-parent POM referenced in the
Passphrase for code signing via GPG Maven plugin
For signing the Maven artifacts via the maven-gpg-plugin during the release build a Maven profile with the GPG passphrase has to be defined in the
<profiles/> section, e.g.
<profile> <id>release-gpg-passphrase</id> <activation> <property> <name>performRelease</name> <value>true</value> </property> </activation> <properties> <gpg.passphrase>your-passphrase</gpg.passphrase> </properties> </profile>
$ git clone git://github.com/sculptor/sculptor.git $ cd sculptor
The following is a brief overview of the main Maven modules of Sculptors source code:
devtoolsFolder with projects used for local development, e.g.
eclipse-mirrorwith the local Eclipse p2 repository mirror.
sculptor-eclipseThe aggregator project holding the Eclipse projects with the Eclipse p2 mirror, the meta model, the DSL model with its UI and unit tests, the feature and the p2 mirror.
sculptor-generatorThe aggregator project holding the implementation of the code generator.
sculptor-cartridgesThe aggregator project holding the implementation of the code generator cartridges.
sculptor-frameworkThe aggregator project holding the implementation of the Sculptor runtime library.
sculptor-mavenThe aggregator project holding the Maven plugin, the Maven archetypes and the Maven repository.
sculptor-examplesThe aggregato project holding a few examples which are using Scupltor, eg. the ones used in the tutorials.
After executing a Maven build from the commandline the corresponding projects in Eclipse have to be refreshed manually! Thereafter you should not have any red crosses (problems) in Eclipse. Sometimes, validation errors in code generation files (.xtend) must be cleaned manually as well. This an be done with a “clean build” (using “Project > Clean…”) of the corresponding Eclipse project.
The following chapters are describing the different aspects of Sculptors Maven-based build process.
Creation of local Eclipse p2 repository mirror
To improve the development experience the needed external Eclipse p2 repositories are “mirrored” via Eclipse Tycho. The mirroring process is activated by using the Maven profile
mvn initialize -Pmirror
The initial mirroring process takes hours!!! After the build is finished then the mirror can be found in the folder “devtools/eclipse-mirror/.p2-mirror/”.
Make sure that the Maven profile used for the local Eclipse p2 repository mirror is added to the Maven “settings.xml”.
Installation of custom Eclipse IDE
By using Eclipse Tycho it’s possible to create a customized Eclipse installation. The installation process is activated by using the Maven profile
mvn verify -Pide
After the build is finished then the Eclipse installation can be found in the folder “devtools/eclipse-ide/target/products/org.sculptor.ide/
Build the whole project
Without specifying any Maven profile the whole project is built:
mvn clean install
Build parts of the project
By specifying one or more from the following Maven profiles certain parts of the project are built:
eclipseSculptor Eclipse plugin
mavenSculptor Maven plugin and archetypes
allThe whole Sculptor project (same as specifying no profile)
E.g. to built the Maven stuff and the examples only then the following commands are used:
mvn clean install -Pmaven,example
The project uses the gitflow workflow. So development of small features is done in the branch “develop”. Larger features are implemented within a feature branch (created via
git flow feature start some-new-feature).
After finishing the new feature the feature branch is merged with “develop” via
git flow feature finish some-new-feature.
Non-committers are not merging the feature branch with “develop” (within their forked repository) but pushing the feature branch to their GitHub repository and opening a pull request. After the pull request gets accepted the feature is merged in the “develop” branch of the Sculptor repository. From here the merged “develop” branch (with the feature) can be pulled in the forked repository.
The branch “master” is used for released code and the corresponding release tags only!
Sculptors release artifacts are hosted at different locations:
- Sculptors Eclipse plugins p2 repository is hosted on GitHub in the folder “updates” of Sculptors website repository.
- Sculptors Maven plugin and archeytpes are hosten on Maven Central.
To release Sculptors Eclipse plugin and the Maven plugins (including the archetypes) we don’t use the (official) Maven release plugin but Atlassians Maven JGitFlow Plugin is used. It is based on and is a replacement for the maven-release-plugin enabling support for git-flow style releases via Maven.
Due to JGitFlows missing support for the Eclipse config files
feature.xml (it only updates the version numbers in Maven POMs) we’re using the Tycho versions plugin for this.
So Sculptors release process is as follows:
- create a release branch and updates pom(s) with the release version via
mvn jgitflow:release-start -P!all -DreleaseVersion=<RELEASE_VERSION>
- update the Eclipse config files with the release version via
mvn tycho-versions:set-version -P!all -DnewVersion=<RELEASE_VERSION>and commit the modified files
- runs a Maven build (deploy or install), merges the release branch, updates pom(s) with the development version via
mvn jgitflow:release-finish -DdevelopmentVersion=<DEVLOPMENT_VERSION>
- update the Eclipse config files with the development version via
mvn tycho-versions:set-version -P!all -DnewVersion=<DEVLOPMENT_VERSION>and commit the modified files
To automate this process the script file
release.sh is available. This script requires as arguments the release version and the next development version (without the suffix “-SNAPSHOT”), e.g.
./release.sh 3.0.0 3.0.1.
The following chapters are describing the deployment of the Eclipse plugin and the Maven plugin during the release build (executed via
Deployment of Eclipse p2 repository to GitHub
Make sure that your Maven “settings.xml” contains the correct GitHub user credentials.
Deployment of Maven artifacts to Sonatypes OSS
To deploy artifacts to Maven Central the artifacts have to be staged on Sonatypes OSS Repository first. This is described in Sonatype OSS Maven Repository Usage Guide. The details of Sculptors access to this repository are outlined in the ticket OSSRH-5507).
Make sure that your Maven “settings.xml” contains the correct Sonatype user credentials.
Troubleshooting release finish
If the release script aborts with an error during execution of the Maven plugin
maven-jgitflow-plugin:release-finish (as described in the corresponding ticket MJF-129) then the release process has to be finished manually:
- Use Git Flow to finish the release via
git flow release finish <release name>.
- Push the release tag created by Git Flow to the GitHub repository via
git push --tags.
Change the version number in the
developbranch to the next development version via
mvn tycho-versions:set-version -P!all -DnewVersion=<release version> mvn tycho-versions:set-version -P!all -DnewVersion=<next development version>-SNAPSHOT git commit -a -m "updates POMs and MANIFST.MFs for development of version <next development version>-SNAPSHOT"
Publishing the staged release on Maven Central
After successfully finishing the release process Sculptors release artifacts are staged on Sonatypes OSS Maven Repository https://oss.sonatype.org/. To publish the artifacts on Maven Central the following has to be done: