Latest revision as of 07:06, 14 October 2014

General Requirements

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.

Obtaining Sources

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 .project and .classpath files.

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!

Using 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 .project and 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

Use core.autocrlf=input. 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.

Open 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 org.eclipse.skalli.target:

• skalli.launch this is the launch configuration you want to use in most cases.
• skalli-nobootdelegation.launch is configured with osgi.compatibility.bootdelegation=false to 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.glassfish Jetty cannot compile our JSP pages with this option set. You have to either patch org.apache.taglibs.standard.glassfish (adding the missing imports javax.xml.parsers, org.xml.sax and org.xml.sax.helpers to 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 jetty/logs.

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 workdir/storage/Project.

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 java-version in 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 org.eclipse.skalli.product/target/repository. In that case, org.eclipse.skalli.product/target/products contains the ready-to-use Skalli distributions (running on Equinox/Jetty).

We maintain an integration build at Eclipse, where the latest build artifacts can be downloaded from.

Run Tests

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/.

Within Eclipse

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.

Within Eclipse

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.:

Contributing Patches

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.

General Guidelines

• 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 <your.email@example.org>

Website

The Skalli website is located in a CVS repository on the Eclipse Foundation's servers.

• File > Import > CVS > Projects from CVS
• Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/org.eclipse
• Use module skalli (from www)
• Finish