- 1 General Requirements
- 2 Obtaining Sources
- 3 Building Skalli in Eclipse
- 4 Running Skalli in Eclipse
- 5 Building Skalli with Maven/Tycho
- 6 Run Tests
- 7 Contributing Patches
- 8 Website
Skalli has Java 6 as a minimum requirement. It is recommended to use the latest Eclipse release for development. The classic edition is sufficient for developing Skalli, but we recommend the JavaEE edition due to its JSP support. As Skalli source code is hosted in Git, it is recommended to install and use the EGit plugin (shipped with Eclipse since release 3.7/Indigo), too.
Skalli is hosted in Git. You can browse the repository in gitweb, or retrieve the source code with
git clone git://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git
Of course, you might use the Git client shipped with Eclipse ("EGit") for that, too. If Git's own protocol is blocked by your firewall, use HTTP protocol instead:
git clone http://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git
Note, in Skalli we use Unix line delimiters (LF) by default. If you are working on Windows and want to contribute, please read the following section about our line delimiter conventions carefully before cloning the Skalli repository.
Import all projects into your workspace:
Import > Git > Projects from Git. Select your cloned repository and continue with
Next > Import Existing Projects. Select all projects and start the import with
Finish. All Skalli projects are plain bundle projects and have checked in
Line Delimiter Conventions
All Skalli files should use LF as line delimiters (Unix style), since merging files with mixed line delimiters in Git can be a real nightmare!
With the Git property
core.autocrlf one can define, which line delimiter conversions Git should apply when checking out or commiting text files. Sounds great in theory, but works not so well in practise. At least if you are using Windows, and especially Egit on Windows.
For a detailed explanation of
core.autocrlf compare the book Pro Git, chapter Git Configuration, or check the Git man pages. Note, you can always use
git config --get core.autocrlf to find out your settings.
Recommendations for Windows Users
We strongly recommend to set
core.autocrlf=false for the time being if you use EGit:
core.autocrlf simply is not supported yet by EGit, so that you inevitably will end up with CRLF line delimiters in your commits all the time. The situation is slightly better if you are using a Git shell, but keep reading!
core.autocrlf=false, unfortunately, is not fail safe either! First of all, ensure that your Eclipse is configured to use
Unix line delimiters (see
Preferences > General > Workspace > New text file line delimiter). This will ensure LF line delimiters for most of your text files, e.g. for Java source files, but not for all of them. For example, when creating a new plugin project, the PDE editor insists on creating the
build.properties files with CRLF line delimiters. In such a case, please manually convert the line delimiters with
File > Convert Line Delimiters To to Unix style before committing.
Please take care that all contributed changes contain only LF line delimiters!
Recommendations for MAC/UNIX Users
This should ensure that source files in the local working directory use native line endings and that committed sources contain only LF.
Building Skalli in Eclipse
After you cloned Skalli from the Git repository and imported all projects you should see a couple of build errors. This is normal, since third-party dependencies will not be resolved unless you specify a target platform.
org.eclipse.skalli.target/skalli.target with the Eclipse target editor. Wait a moment until all locations are resolved. Since the target platform contains some bundles from the Eclipse distribution and a complete Jetty runtime, it may take some time.
Click the link "Set as Target Platform" in the upper right corner of the editor. This will rebuild all projects in the workspace. Now all Skalli bundles should compile successfully. If not, try a clean build:
Project > Clean....
Running Skalli in Eclipse
Skalli provides pre-configured launch configurations in the bundle
skalli.launchthis is the launch configuration you want to use in most cases.
skalli-nobootdelegation.launchis configured with
osgi.compatibility.bootdelegation=falseto detect missing imports statements for
javax.*packages. Equinox and other OSGi containers behave slightly different in the handling of
javax.*packages (see Equinox Box Delegation). Note, however that due to a bug in
org.apache.taglibs.standard.glassfishJetty cannot compile our JSP pages with this option set. You have to either patch
org.apache.taglibs.standard.glassfish(adding the missing imports
org.xml.sax.helpersto the bundle's manifest), or wait for glassfish to fix the problem.
Both launch configurations are using Equinox as OSGi container and Jetty as web container implementation. Required Jetty configuration files are provided in the folder
org.eclipse.skalli.target/jetty/etc. Log files will be stored in
The Jetty working directory is expected to be in
org.eclipse.skalli.target/workdir. Skalli stores project data, customization information etc. in subdirectories of
workdir/storage. By default, you will find some example projects in
http://localhost:8080 should present the Skalli login screen. The default user configured is "admin", password "admin". This user has administrative rights and is able to edit all projects and configure the instance. Click on All Projects to get an overview about the example projects provided with the source code.
Building Skalli with Maven/Tycho
Skalli can be built with Maven/Tycho release 3.0.3 or above. By default the build is performed with source/target compliance for Java 6. You might adapt the property
org.eclipse.skalli.parent/pom.xml if you want to build for a different java version.
Dependency resolution is based on the same target platform definition as used for the PDE toolset in Eclipse. Simply run
mvn clean install on the root directory of the Skalli project tree.
Currently Skalli exports the following features:
org.eclipse.skalli.feature org.eclipse.skalli.source.feature org.eclipse.skalli.orbit.feature org.eclipse.skalli.jetty.feature org.eclipse.skalli.eclipse.feature org.eclipse.skalli.testing.feature
org.eclipse.skalli.feature contains only the Skalli bundles and can be used to compose target platforms for writing extensions.
org.eclipse.skalli.source.feature contains the corresponding Skalli source code.
org.eclipse.skalli.orbit.feature contains third party libraries from the Eclipse orbit project.
org.eclipse.skalli.eclipse.feature provides additional libraries from other Eclipse projects like Equinox and Gemini JPA.
org.eclipse.skalli.jetty.feature is a subset of the Jetty bundles repository and contains the minimal set of Jetty bundles to run Skalli.
org.eclipse.skalli.testing.feature finally provides the
testutil bundle useful for writing Skalli tests.
The bundles repository can be found in
org.eclipse.skalli.p2/target/repository after a successful Maven build. It contains only the Skalli bundles but no dependencies. If you build Skalli with the profile -Pbuild-product, an additional p2 repository with all necessary orbit dependencies is provided in
In that case,
org.eclipse.skalli.product/target/products contains the ready-to-use Skalli distributions (running on Equinox/Jetty).
Most Skalli bundles have an accompanying test fragment (convention: name of the parent bundle plus suffix .test), which contains unit and plugin unit tests, respectively. For the UI bundles a Selenium test suite is provided.
In order to run the unit tests in Maven, simply execute
$ mvn clean install
All unit tests are executed automatically, except the Gerrit and Selenium tests (how to run them as part of the Maven build, see below). If you need to pass additional parameters to the tycho-surefire plugin, e.g. proxy settings, provide them via the testArgs property.
$ mvn clean install -DtestArgs=...
Within Eclipse use the launch configurations provided in the test bundles (e.g. org.eclipse.skalli.core.test.launch in the org.eclipse.skalli.core.test bundle). Note, all tests run in an embedded OSGi runtime, so executing them as plain JUnit tests instead of as JUnit Plugin-in tests will fail.
The required test content is provided in the directory storage of bundle org.eclipse.skalli.testutil, which also contains utility stuff for writing tests for Skalli. This bundle is exported in the feature org.eclipse.skalli.testing.feature. If you are going to write your own extensions for Skalli, you should add this feature to your target platform.
Run Selenium Tests
Note: The Selenium tests are easily broken and not very stable.
From Command Line
The Selenium module is extracted into a separate profile and thus is not part of the ordinary reactor build. To run these tests you need to specify the profile selenium:
$ mvn clean install -P selenium
The test suite will use your locally installed Firefox.
Restriction: An already running instance of Skalli is expected in the background, so you need to launch Skalli first with /org.eclipse.skalli.selenium/skalli_selenium.launch. This instance is configured to take the necessary test content from /org.eclipse.skalli.selenium/testdata/.
To run the Selenium tests within Eclipse use /org.eclipse.skalli.selenium/org.eclipse.skalli.selenium.launch. Again, these tests expect an already running instance of Skalli in the background, so you need to launch a Skalli instance first with /org.eclipse.skalli.selenium/skalli_selenium.launch.
Run Gerrit Tests
From Command Line
The Gerrit test module is extracted into a separate profile and thus is not a part of the ordinary reactor build. To run these tests you need to specify the profile gerrit:
$ mvn clean install -P gerrit
Important Note: The Gerrit tests need a running Gerrit instance (preferably a test instance, since the tests create a lot of Gerrit projects). On this Gerrit instance you must create a user with administrator rights and upload suitable SSH credentials. Afterwards you need to update the POM file in the org.eclipse.skalli.gerrit.test project, i.e. you need to replace the placeholders for the connection parameters in build > plugins > plugin > configuration:
<systemProperties> <testHost><!-- enter your host --></testHost> <testAdminAccount><!-- enter your account --></testAdminAccount> <testPort><!-- enter the port --></testPort> <testPrivatekeyFile><!-- enter path to private key file --></testPrivatekeyFile> <testPassphrase><!-- enter the passphrase for the key file --></testPassphrase> </systemProperties>
The path to the private key file should be a path relative to the bundle root. For example, you might copy the key file as id_rsa to /org.eclipse.skalli.gerrit.test/src/main/java/org/eclipse/skalli/gerrit/client/internal/. Then the corresponding parameter would be src/main/java/org/eclipse/skalli/gerrit/client/internal/id_rsa. Copy the corresponding public key file of the Gerrit instance (e.g. id_rsa.public) to the same directory.
To run Gerrit tests within Eclipse use /org.eclipse.skalli.gerrit.test/org.eclipse.skalli.gerrit.test.launch. Again, you need to modify it first by adding the connection parameters as VM arguments, e.g.:
Contributors are welcome to provide patches according to the Eclipse Committer Due Diligence Guidelines. Before your contribution can be accepted by the project, you need to create and electronically sign the Eclipse Foundation Contributor License Agreement (CLA).
We strongly prefer contributions via Gerrit.
Make sure to follow the guidelines set forth below.
- Make small commits, as small as reasonable. This makes them easy to review.
- Each commit should have a commit message (see details below) that explains very clearly what the commit sets out to achieve.
- The scope of a commit should be clear and easy to understand for others. Do not put different features/bug fixes/ideas into one and the same commit!
- Split larger features into multiple commits if that makes them easier to understand. Create an issue in bugs.eclipse.org/skalli to track the parts.
- Provide tests for your new features/bug fixes.
- Format your source code according to the formatting standards of the project prior to committing or providing a patch. All bundles come with project-specific formatter settings. Apply them!
- Use Unix Line Endings (LF). Do not use Windows line endings (CRLF) or others!
Commit Message Guidelines
- The commit message header should fit on one line and should start with an uppercase letter
- The commit message have newline characters after every 60-70 characters.
- If a Gerrit Change-Id is available (for example when re-submitting to the same change), it should be added in the format below
- If there is an associated bug number in Bugzilla about it, it should come right before Gerrit's Change-Id entry (if available) or towards the end.
- A "Signed-off-by" should be added to the end of the commit message (see example below).
- The first sentence should be a clear and concise description about the change.
- Enter a newline before providing a more detailed description about the change.
Fix the commit dialog to respect the workbench's selection Originally, the commit dialog would automatically check off all files in the dialog. This behavior contradicts a user's expectation because their selection in the workbench is completely ignored. The code has been corrected to only preselect what the user has actually selected. Bug: 12345 Change-Id: I71ac4844ab9d2f848352eba9252090c586b4146a Signed-off-by: Your Name <email@example.com>
The Skalli website is located in a CVS repository on the Eclipse Foundation's servers.
- File > Import > CVS > Projects from CVS
- Select URL :pserver:firstname.lastname@example.org/cvsroot/org.eclipse
- Use module skalli (from www)