Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Skalli/Contributor Guide"

(Updated the "Run Skalli in Eclipse" guide)
(Refined. Added description of testArg parameter.)
 
(34 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= Development IDE Configuration =
+
= General Requirements =
  
Skalli has Java 5.0 as a minimum requirement. It is recommended to use latest Eclipse release, classic edition is sufficient for development, but JavaEE edition is recommended due to JSP support. As Skalli source code is hosted in git, it is recommended to use EGit plugin too.
+
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.
 
+
Note: As of 2011-05-10, Indigo release 3.7M7 is working well. Install EGit 0.12.1 from included software site at "Indigo - http://download.eclipse.org/releases/indigo".
+
  
 
= Obtaining Sources  =
 
= Obtaining Sources  =
  
Skalli is hosted in Git. You can browse the repository in [http://git.eclipse.org/c/skalli/org.eclipse.skalli.git/tree/ gitweb].
+
Skalli is hosted in Git. You can browse the repository in [http://git.eclipse.org/c/skalli/org.eclipse.skalli.git/tree/ gitweb], or retrieve the source code with
 
+
You can get the source code via git commandline tool
+
  
 
<pre style="width: 50em;">git clone git://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git
 
<pre style="width: 50em;">git clone git://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git
 
</pre>
 
</pre>
  
or cloning a repository using EGit from URI <code>git://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git</code>.
+
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:
 +
 
 +
<pre style="width: 50em;">git clone http://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git
 +
</pre>
  
 
[[Image:skalli_egit_clone.png]]
 
[[Image:skalli_egit_clone.png]]
  
Clone from <code>master</code> branch and specify remote branch as <code>origin/master</code>.
+
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 [[Skalli/Contributor_Guide#EOL_properties|line delimiter conventions]] carefully before cloning the Skalli repository.  
  
Now import all projects into your workspace. <code>Import > Git > Projects from Git ></code> Select your cloned repo <code>> Import existing projects > Select all projects > Finish</code>. You will import 29 projects (as of 2011-04-26).
+
Import all projects into your workspace: <code>Import > Git > Projects from Git</code>. Select your cloned repository and continue with <code>Next > Import Existing Projects</code>. Select all projects and start the import with <code>Finish</code>. All Skalli projects are plain bundle projects and have checked in <code>.project</code> and <code>.classpath</code> files.
  
 
[[Image:skalli_egit_import_projects.png]]
 
[[Image:skalli_egit_import_projects.png]]
  
  
Note: there will be compile errors, as some patches are needed for successful compilation.
+
== 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!
  
= Howto: Make Skalli Build in Eclipse (as of 2011-06-22)  =
+
With the Git property <code>core.autocrlf</code> 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.
  
After you cloned Skalli from Git you should see a couple of build errors. Due to the ongoing IP process for Skalli, we are not allowed to provide all necessary 3rd-party libraries as part of our source code (or in Eclipse Orbit) yet. Therefore, you need to download the missing bundles by your own and copy them into the folder <code>org.eclipse.skalli.target/target-platform-3rdparty</code> so that the target platform resolver can find them.
+
For a detailed explanation of <code>core.autocrlf</code> compare the book [http://progit.org/book/ Pro Git], chapter [http://progit.org/book/ch7-1.html Git Configuration], or check the Git man pages. Note, you can always use <code>git config --get core.autocrlf</code> to find out your settings.
  
'''1. Download Missing 3rd-Party Libraries'''
+
=== Recommendations for Windows Users ===
 +
We strongly recommend to set <code>core.autocrlf=false</code> for the time being if you use EGit: <code>core.autocrlf</code> simply is [https://bugs.eclipse.org/bugs/show_bug.cgi?id=301775 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!
  
The following 3rd-party libraries are needed for Skalli:
+
Using <code>core.autocrlf=false</code>, unfortunately, is not fail safe either! First of all, ensure that your Eclipse is configured to use <code>Unix</code> line delimiters (see <code>Preferences > General > Workspace > New text file line delimiter</code>). 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 <code>.project</code> and <code>build.properties</code> files with CRLF line delimiters. In such a case, please manually convert the line delimiters with <code>File > Convert Line Delimiters To</code> to Unix style before committing.
<pre>org.restlet version="2.0.0.RC4"
+
org.restlet.ext.servlet version="2.0.0.RC4
+
org.restlet.ext.xstream version="2.0.0.RC4
+
org.codehaus.jettison.jettison version="1.2.0"
+
org.apache.lucene.lucene-core version="3.0.2"
+
org.apache.lucene.lucene-highlighter version="3.0.2"
+
org.apache.lucene.lucene-queries version="3.0.2"
+
com.thoughtworks.xstream version="1.3.1"
+
org.custommonkey.xmlunit version="1.2.0"
+
org.xmlpull version="1.1.4.c"
+
com.vaadin version="6.4.0"
+
osgi.enterprise version="4.2.0"
+
org.eclipse.gemini.jpa version="1.0.0.RC1"
+
org.eclipse.gemini.jpa.weaving version="1.0.0.RC1"
+
org.eclipse.gemini.dbaccess.derby version="1.0.0.M1-incubation"
+
</pre>  
+
  
Some of them are available as OSGi bundles already and can be downloaded directly from the vendor or [http://repo2.maven.org/maven2 Maven Central], respectively:
+
'''Please take care that all contributed changes contain ''only'' LF line delimiters!'''
+
* [http://maven.restlet.org/org/restlet/jse/org.restlet/2.0-RC4/ org.restlet]
+
* [http://maven.restlet.org/org/restlet/jee/org.restlet.ext.servlet/2.0-RC4/ org.restlet.ext.servlet]
+
* [http://maven.restlet.org/org/restlet/jse/org.restlet.ext.xstream/2.0-RC4/ org.restlet.ext.xstream]
+
* [http://repo2.maven.org/maven2/org/codehaus/jettison/jettison/1.2/ org.codehaus.jettison.jettison]
+
* [http://repo2.maven.org/maven2/com/vaadin/vaadin/6.4.0/ com.vaadin]
+
* [http://www.eclipse.org/downloads/download.php?file=/gemini/dbaccess/r1.0/milestones/gemini-dbaccess-1.0.0.M1-incubation.zip org.eclipse.gemini.dbaccess.derby and osgi.enterprise]
+
* [http://www.eclipse.org/downloads/download.php?file=/gemini/jpa/r1.0/milestones/gemini-jpa-1.0.0.RC1.zip org.eclipse.gemini.jpa and org.eclipse.gemini.jpa.weaving]
+
  
XStream, XMLUnit and XMLPull do not provide OSGi bundles, but you can use those from SpringSource:
+
=== Recommendations for MAC/UNIX Users ===
 +
Use <code>core.autocrlf=input</code>. 
 +
This should ensure that source files in the local working directory use native line endings and that committed sources contain only LF.
  
* [http://ebr.springsource.com/repository/app/bundle/version/detail?name=com.springsource.com.thoughtworks.xstream&version=1.3.1 com.thoughtworks.xstream]
+
= Building Skalli in Eclipse =
* [http://ebr.springsource.com/repository/app/bundle/version/detail?name=com.springsource.org.custommonkey.xmlunit&version=1.2.0 org.custommonkey.xmlunit]
+
* [http://ebr.springsource.com/repository/app/bundle/version/detail?name=com.springsource.org.xmlpull&version=1.1.4.c org.xmlpull]
+
  
For Lucene there are no suitable bundles available at SpringSource (only for older releases), but you can use those attached to [https://bugs.eclipse.org/bugs/show_bug.cgi?id=346411 Bug 346411]:
+
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.
  
* [https://bugs.eclipse.org/bugs/attachment.cgi?id=196095 org.apache.lucene.lucene*]
+
Open <code>org.eclipse.skalli.target/skalli.target</code> 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.
  
'''2. Set the Target Platform'''
+
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: <code>Project > Clean...</code>.
  
Open <code>org.eclipse.skalli.target/skalli-for-eclipse.target</code> in the Eclipse target editor. Wait a moment till 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.
+
= Running Skalli in Eclipse =
  
Click the link "Set as Target Platform" in the upper right corner of the editor. This will rebuild all projects in the workspace.  
+
Skalli provides pre-configured launch configurations in the bundle <code>org.eclipse.skalli.target</code>:
 +
* <code>skalli.launch</code>  this is the launch configuration you want to use in most cases.
 +
* <code>skalli-nobootdelegation.launch</code>  is configured with <code>osgi.compatibility.bootdelegation=false</code> to detect missing imports statements for <code>javax.*</code> packages. Equinox and other OSGi containers behave slightly different in the handling of <code>javax.*</code> packages (see [http://wiki.eclipse.org/Equinox_Boot_Delegation Equinox Box Delegation]). Note, however that due to a [https://bugs.eclipse.org/bugs/show_bug.cgi?id=347704 bug] in <code>org.apache.taglibs.standard.glassfish</code> Jetty cannot compile our JSP pages with this option set. You have to either patch <code>org.apache.taglibs.standard.glassfish</code> (adding the missing imports <code>javax.xml.parsers</code>, <code>org.xml.sax</code> and <code>org.xml.sax.helpers</code> to the bundle's manifest), or wait for glassfish to fix the problem.
  
'''3. Add a missing class from VAADIN: <code>com.vaadin.ui.CustomField</code>'''
+
Both launch configurations are using Equinox as OSGi container and Jetty as web container implementation. Required Jetty configuration files are provided in the folder <code>org.eclipse.skalli.target/jetty/etc</code>. Log files will be stored in <code>jetty/logs</code>.
  
After setting the target platform and rebuilding you should still see some compile errors, e.g. in the bundle <code>org.eclipse.skalli.view</code>. This is due to a missing class, <code>com.vaadin.ui.CustomField</code>, which is quite heavily used in Skalli, but unfortunatelly not yet part of the Vaadin distribution.
+
The Jetty working directory is expected to be in <code>org.eclipse.skalli.target/workdir</code>. Skalli stores project data, customization information etc. in subdirectories of <code>workdir/storage</code>. By default, you will find some example projects in <code>workdir/storage/Project</code>.
  
Therefore, unless we are allowed to include that class in our own source code, you have to download it by your own from the project's SVN repository at Google Code: [http://customfield.googlecode.com/svn-history/r5/trunk/src/com/vaadin/ui/CustomField.java CustomField.java]. Please use version 0.8.2 of that class since package names have been renamed from version 0.9.0 on.
+
[http://localhost:8080 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 [[Skalli/User_Guide#Configuration|configure]] the instance. Click on ''All Projects'' to get an overview about the example projects provided with the source code.
  
Copy this file to <code>org.eclipse.skalli.view/src/main/java/com/vaadin/ui/CustomField.java</code>.
+
= Building Skalli with Maven/Tycho =
  
Now all Skalli bundles should compile sucessfully.
+
Skalli can be built with Maven/Tycho [http://maven.apache.org/download.html release 3.0.3] or above. By default the build is performed with source/target compliance for Java 6. You might adapt the property <code>java-version</code> in <code>org.eclipse.skalli.parent/pom.xml</code> if you want to build for a different java version.  
  
= Run Skalli in Eclipse =
+
Dependency resolution is based on the same target platform definition as used for the PDE toolset in Eclipse. Simply run <code>mvn clean install</code> on the root directory of the Skalli project tree.
  
Skalli provides preconfigured launch configurations in the bundle <code>org.eclipse.skalli.target</code>:
+
Currently Skalli exports the following features:
* <code>skalli.launch</code>  this is the launch configuration you want to use in most cases.
+
<pre>
* <code>skalli-nobootdelegation.launch</code>  is configured with <code>osgi.compatibility.bootdelegation=false</code> to detect missing imports statements for <code>javax.*</code> packages. Equinox and other OSGi containers behave slightly different in the handling of <code>javax.*</code> packages (see [http://wiki.eclipse.org/Equinox_Boot_Delegation Equinox Box Delegation]). Note, however that due to a [https://bugs.eclipse.org/bugs/show_bug.cgi?id=347704 bug] in <code>org.apache.taglibs.standard.glassfish</code> Jetty cannot compile our JSP pages with this option set. You have to either patch <code>org.apache.taglibs.standard.glassfish</code> (adding the missing imports <code>javax.xml.parsers</code>, <code>org.xml.sax;version</code> and <code>org.xml.sax.helpers</code> to the bundle's manifest), or wait for glassfish to fix the problem.
+
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
 +
</pre>
  
Both launch configurations are using Equinox as OSGi container and Jetty as RFC66-enabled web container implementation. Required Jetty configuration files are provided in the folder <code>jetty/etc</code>. Log files will be stored in <code>jetty/logs</code>.
+
<code>org.eclipse.skalli.feature</code> contains only the Skalli bundles and can be used to compose target platforms for writing extensions. <code>org.eclipse.skalli.source.feature</code> contains the corresponding Skalli source code. <code>org.eclipse.skalli.orbit.feature</code> contains third party libraries from the Eclipse orbit project. <code>org.eclipse.skalli.eclipse.feature</code> provides additional libraries from other Eclipse projects like Equinox and Gemini JPA. <code>org.eclipse.skalli.jetty.feature</code> is a subset of the Jetty bundles repository and contains the minimal set of Jetty bundles to run Skalli. <code>org.eclipse.skalli.testing.feature</code> finally provides the <code>testutil</code> bundle useful for writing Skalli tests.
  
The Jetty working directory is expected to be in <code>org.eclipse.skalli.target/workdir</code>. This directory contains only a <code>README</code> file by default. Skalli will store project data, customization etc. in the folder <code>workdir/storage</code>.
+
The bundles repository can be found in <code>org.eclipse.skalli.p2/target/repository</code> 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 <code>org.eclipse.skalli.product/target/repository</code>.
 +
In that case, <code>org.eclipse.skalli.product/target/products</code> contains the ready-to-use Skalli distributions (running on Equinox/Jetty).
  
Jetty will run by default on port 8080. So start a browser to URL [http://localhost:8080 http://localhost:8080], and you should see a login dialog to authenticate. The default user configured is "admin", password "admin". Then you are able to create projects, edit projects, search projects etc. The created projects are stored as XML files in <code>org.eclipse.skalli.target/workdir/storage/Project</code>.
+
We maintain an [https://hudson.eclipse.org/hudson/job/skalli integration build] at Eclipse, where the latest build artifacts can be [https://hudson.eclipse.org/hudson/job/skalli/lastSuccessfulBuild/  downloaded] from.
  
= Build =
+
= Run Tests  =
  
Skalli builds run on build.eclipse.org via Hudson using
+
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 [http://seleniumhq.org/ Selenium] test suite is provided.
* [http://maven.apache.org/download.html at least Maven 3.0.0]
+
  
Hudson
+
In order to run the unit tests in Maven, simply execute
* [https://hudson.eclipse.org/hudson/job/skalli Skalli@hudson.eclipse.org]
+
  
 +
<pre>$ mvn clean install</pre>
  
TODO: mvn build actually does not work due to missing patches and a target definition using a location of type directory.
+
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.
  
 +
<pre>$ mvn clean install -DtestArgs=...</pre>
  
= Run Tests =
+
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.
  
TODO: explain how to run tests in Eclipse, using Maven. Meanwhile use:
+
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.
  
<pre>
+
== Run Selenium Tests ==
$ mvn clean install  
+
 
 +
'''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'':
 +
<pre>$ mvn clean install -P selenium
 +
</pre>
 +
 
 +
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'':
 +
<pre>$ mvn clean install -P gerrit
 +
</pre>
 +
 
 +
'''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 &gt; plugins &gt; plugin &gt; configuration'':
 +
<pre> &lt;systemProperties&gt;
 +
    &lt;testHost&gt;&lt;!-- enter your host --&gt;&lt;/testHost&gt;
 +
    &lt;testAdminAccount&gt;&lt;!-- enter your account --&gt;&lt;/testAdminAccount&gt;
 +
    &lt;testPort&gt;&lt;!-- enter the port --&gt;&lt;/testPort&gt;
 +
    &lt;testPrivatekeyFile&gt;&lt;!-- enter path to private key file --&gt;&lt;/testPrivatekeyFile&gt;
 +
    &lt;testPassphrase&gt;&lt;!-- enter the passphrase for the key file --&gt;&lt;/testPassphrase&gt;
 +
&lt;/systemProperties&gt;
 
</pre>
 
</pre>
 +
 +
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<br> ===
 +
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.:<br>
 +
 +
[[Image:Launch config.gif]]
  
 
= Contributing Patches =
 
= Contributing Patches =
  
Contributors a welcome to provide patches according to the [http://www.eclipse.org/legal/committerguidelines.php Eclipse Committer Due Diligence Guidelines]. In short: Create an issue on [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Skalli bugs.eclipse.org], create a patch (please use <code>git format-patch</code> whenever possible because that makes it easier for us to integrate patches), and attach it to the bug entry. Make sure to follow the guidelines set forth below.
+
Contributors are welcome to provide patches according to the [http://www.eclipse.org/legal/committerguidelines.php Eclipse Committer Due Diligence Guidelines]. Before your contribution can be accepted by the project, you need to create and electronically sign the [http://www.eclipse.org/legal/CLA.php Eclipse Foundation Contributor License Agreement (CLA)].
 +
 
 +
We strongly prefer contributions via [https://git.eclipse.org/r/p/skalli/org.eclipse.skalli Gerrit].
 +
 
 +
Make sure to follow the guidelines set forth below.
  
 
=== General Guidelines ===
 
=== General Guidelines ===
Line 130: Line 160:
 
*Provide tests for your new features/bug fixes.
 
*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!
 
*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 ===
 
=== Commit Message Guidelines ===
Line 143: Line 174:
  
 
Originally, the commit dialog would automatically check off all
 
Originally, the commit dialog would automatically check off all
files in the dialog. This behaviour contradicts a user's expectation
+
files in the dialog. This behavior contradicts a user's expectation
 
because their selection in the workbench is completely ignored. The
 
because their selection in the workbench is completely ignored. The
 
code has been corrected to only preselect what the user has actually
 
code has been corrected to only preselect what the user has actually

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

Skalli egit clone.png

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.

Skalli egit import projects.png


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

Launch config.gif

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

Back to the top