Difference between revisions of "Libra/Getting Started"

From Eclipsepedia

Jump to: navigation, search
(Create new Web Application Bundle)
 
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
= Getting Started  =
 
= Getting Started  =
== Overview ==
 
The Libra project enables you to use tools that integrate the existing WTP tooling and PDE tooling so that OSGi Enterprise applications can be developed with both tooling at the same time. It also provides you with tools for better experience in the [http://www.eclipse.org/equinox/server// Server-Side Equinox] scenario.
 
== Installation  ==
 
Currently Libra supports only Eclipse Indigo. As a prerequisite you need to install Eclipse IDE for Java EE Developers. After that install Libra from the [https://hudson.eclipse.org/hudson/view/WTP/job/libra/ws/development/org.eclipse.libra.repository/target/site/ update site]
 
  
The site contains:
+
== Installation and Use  ==
* OSGi Facet Feature
+
The Libra features can be installed from the [http://download.eclipse.org/releases/indigo/ p2 repository] of the Indigo Simultaenous Release (since [http://eclipse.org/webtools/development/news/3.3M6/libra.php Indigo M6]). As a prerequisite you may install [http://www.eclipse.org/downloads/packages/node/526 Eclipse IDE for Java EE Developers].
* WAR Products Core Feature
+
  
== Usage  ==
+
The update site contains:
* WAR Products Core Feature provides [http://wiki.eclipse.org/RAP/Equinox_WAR_products WAR deployment for Equinox based applications]<br/>
+
* '''OSGi Bundle Facet''' feature that introduces:
* OSGi Facet Feature introduces:
+
*# A new facet '''OSGi Bundle''' for Dynamic Web, JPA and Utility projects.  
*# A new facet "OSGi Bundle" for Dynamic Web, JPA and Utility projects.  
+
 
*# Wizard for converting WTP standard projects to OSGi Enterprise bundle projects:
 
*# Wizard for converting WTP standard projects to OSGi Enterprise bundle projects:
 
*#* Dynamic Web projects to Web Application Bundle projects
 
*#* Dynamic Web projects to Web Application Bundle projects
 
*#* JPA projects to Persistent Bundle projects
 
*#* JPA projects to Persistent Bundle projects
 
*#* Utility projects and simple Java projects to OSGi Bundle projects
 
*#* Utility projects and simple Java projects to OSGi Bundle projects
::Both options modify project's MANIFEST.MF in order to become a valid OSGi bundle.
+
::Both options modify project's '''MANIFEST.MF''' in order to become a valid OSGi bundle.
  
The facet may be enabled during project creation or after that from Properties page of the project.
+
The facet may be enabled during the project creation or after that from the '''Properties''' page of the project.
The wizard is available from project's context menu ''Configure > Convert to OSGi Bundle Projects...''
+
The wizard is available from project's context menu '''Configure > Convert to OSGi Bundle Projects...'''
<pre>Note that you may need to adjust your target platform accordingly.</pre>
+
 
 +
'''Note''' that you may need to adjust your target platform accordingly.
 +
 
 +
* '''WAR Products''' feature which provides [http://wiki.eclipse.org/RAP/Equinox_WAR_products WAR deployment for Equinox based applications]<br/>
 +
 
 +
[[Image:LibraInstall.png]]
 +
 
 +
== Create new Web Application Bundle ==
 +
 
 +
# Call the New Dymanic Web Project wizard: ''New > Project... > Web > Dynamic Web Project''
 +
# Enter the necessary project information like ''Project name'', ''Target runtime'', etc.
 +
# Add the ''OSGi Bundle'' facet in the Configuration:
 +
## Click on the ''Modify...'' button in the ''Configuration'' group.
 +
## Choose the ''OSGi Bundle'' facet in the ''Project Facets'' dialog and click OK.
 +
# Click ''Finish'' to create the Web Application Bundle project.
 +
 
 +
== Create new OSGi Bundle ==
 +
 
 +
# Call the New Faceted Project wizard: ''New > Project... > General > Faceted Project''
 +
# Enter the necessary project information like ''Project name''.
 +
# Click the ''Next'' button.
 +
# Select the ''OSGi Bundle'' and ''Java'' facets.
 +
# Click ''Finish'' to create the OSGi Bundle project.
  
 
= Obtaining Sources =
 
= Obtaining Sources =
 
You can find the sources available in [http://git.eclipse.org/c/libra/org.eclipse.libra.git/ Git repository]
 
You can find the sources available in [http://git.eclipse.org/c/libra/org.eclipse.libra.git/ Git repository]
<br>In order to synchronize them locally, you may use [http://www.eclipse.org/egit/ EGit]
 
  
= Builds =
+
In order to synchronize them locally, you may use the [http://www.eclipse.org/egit/ EGit] step-by-step procedure.
Libra build runs on build.eclipse.org via Hudson using:
+
* [http://maven.apache.org/download.html at least Maven 3.0.0]
+
* Tycho
+
  
Hudson: [https://hudson.eclipse.org/hudson/job/libra/ Libra@hudson.eclipse.org]
+
The [[EGit/User Guide]] provides detailed instruction how to work with EGit.
 +
 
 +
== Updating/Installing EGit ==
 +
 
 +
*Start your '''Eclipse IDE''' and navigate to '''Help-&gt;Install New Software-&gt;Add...'''
 +
*Enter the software update site [http://download.eclipse.org/egit/updates-nightly]
 +
*Select the '''Eclipse EGit (Incubation)''' and '''Eclipse JGit (Incubation)''' and choose '''Next>''' to finish the installation.
 +
During the installation you will be asked to accept the License Agreements.
 +
 
 +
[[Image:installEGit.jpg]]
 +
 +
== Identifying Yourself ==
 +
To identify yourself, follow these instructions [http://wiki.eclipse.org/EGit/User_Guide#Identifying_yourself/ these instructions]
 +
 +
== Setting up the Home Directory on Windows ==
 +
To set up the '''HOME''' directory, go through [http://wiki.eclipse.org/EGit/User_Guide#Setting_up_the_Home_Directory_on_Windows/ these steps]
 +
 +
== Configuring SSH in Eclipse ==
 +
To configure ssh, proceed [http://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration/ as follows].
 +
 +
== Clone Git Repository ==
 +
 
 +
* Open the '''Git Repository Exploring''' perspective and in the '''Git Repositories''' view choose the '''Clone a Git Repository''' toolbar button
 +
* In the '''URI''' field of the opened '''Clone Git Repository''' wizard enter the URI of the libra git repository: [git://git.eclipse.org/gitroot/libra/org.eclipse.libra.git] and choose '''Next'''
 +
 
 +
[[Image:CloneGitRepo.jpg]]
 +
 
 +
* Select the added repository and from its context menu choose '''Import Projects...'''
 +
* Expand the repository tree to '''Remote Tracking''' level, select the remote branch '''origin/master''' and from its context menu choose '''Create Branch...''' to create a new local branch
 +
 
 +
== Updating Sources ==
 +
To keep the sources up to date you have to [http://wiki.eclipse.org/EGit/User_Guide#Pulling_New_Changes_from_Upstream_Branch/ pull the new changes from the upstream branch].
 +
 
 +
= Build Infrastructure =
 +
The build is based on [http://maven.apache.org/download.html/ Maven] (at least 3.0.0) and Tycho, executed on the Hudson server, hosted at Eclipse Foundation.
 +
 
 +
There are two Hudson jobs available for Libra:
 +
* [https://hudson.eclipse.org/hudson/job/libra/ libra] - for building the '''master''' git branch.
 +
* [https://hudson.eclipse.org/hudson/job/libra-indigo/ libra-indigo] - for building the '''indigo''' git branch.
  
 
== Maven Build Sequence ==
 
== Maven Build Sequence ==
Line 39: Line 89:
 
[~/org.eclipse.libra/development/org.eclipse.libra.releng] $ mvn clean install
 
[~/org.eclipse.libra/development/org.eclipse.libra.releng] $ mvn clean install
 
</pre>
 
</pre>
 +
'''Note''' that you may need to configure your proxy settings
  
== How to reproduce a build to a certain change list ==
+
= Proposing and Committing a Patch =
[http://wiki.eclipse.org/EGit/User_Guide#Fetching_a_change_from_a_Gerrit_Code_Review_Server Fetch to the specific change] and build with Maven as specified above.
+
The patch file contains a description of changes of a set of resources which can be automatically applied to another eclipse workspace or git repository.
 +
If you want to propose or commit a patch you need to know that the Eclipse update hook will examine the Committer's entries of an incoming push. All the committer's entries have to be made by the committer performing the push, otherwise the push will fail. Furthermore, your committer ID, or the committer e-mail address registered with your committer account at the Eclipse Foundation must be present in the Committer Email record. For more information on that restriction see: [http://wiki.eclipse.org/Git#Notes_on_DVCS this] page.  
  
= How to propose and how to commit a patch =
+
== Proposing a Patch ==  
The process for proposing and committing a patch is similar to [http://wiki.eclipse.org/Git#Notes_on_DVCS this] one. For more information, see the below described procedures.
+
If you want commit a change on a local feature or bugfix branch and then to export this change into a patch file, follow the steps below:
== How to propose a patch ==  
+
If you want to propose a patch, follow these three quick steps to do that:
+
 
# Open a [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Libra bug]
 
# Open a [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Libra bug]
# [http://wiki.eclipse.org/EGit/User_Guide#Patches Create a patch]
+
#* Specify the bug component (General; OSGi Facet or WAR)
# Attach the patch to the bug
+
#* Complete the fields about the product version, bug severity, type of your hardware, operating systems and write a summary and description of the patch
 
+
# Open the '''History view''' of your '''Eclipse IDE''' and choose ''' Create Patch...''' (''The patch file will contain the difference between the commit and its parent in the history view. Note that the filter of the history view applies also for patch creation.'')
== How to commit a patch ==
+
# Start the '''Patch Wizard''', select the location of the patch and choose '''Next''' (''The name of the patch file is created from the first line of the commit message.'')
 +
#Change the patch format, if necessary.
 +
# Attach the patch created to the bug
 +
# Submit the bug
 +
 +
== Committing a Patch ==
 
To commit a patch, proceed as follows:
 
To commit a patch, proceed as follows:
# [http://wiki.eclipse.org/EGit/User_Guide#Patches Apply the proposed patch]
+
# Apply the proposed patch using the '''Patch Wizard'''
 
# Test the patch
 
# Test the patch
 
# Commit the patch
 
# Commit the patch
 
# [http://wiki.eclipse.org/EGit/User_Guide#Push_Upstream Setup push configuration] with the following push URL: <pre>ssh://committer_id@git.eclipse.org/gitroot/libra/org.eclipse.libra.git</pre>
 
# [http://wiki.eclipse.org/EGit/User_Guide#Push_Upstream Setup push configuration] with the following push URL: <pre>ssh://committer_id@git.eclipse.org/gitroot/libra/org.eclipse.libra.git</pre>
# Push the patch
+
# Push the patch and see its change number in order to be able to inspect it
 +
 
 +
== Reproducing a Build to a Certain Change List ==
 +
[http://wiki.eclipse.org/EGit/User_Guide#Fetching_a_change_from_a_Gerrit_Code_Review_Server Fetch to the specific change] and build with Maven as described above.
 +
 
 +
= Send us feedback =
  
= Get in touch =
 
 
== Mailing list ==
 
== Mailing list ==
 
[https://dev.eclipse.org/mailman/listinfo/libra-dev https://dev.eclipse.org/mailman/listinfo/libra-dev]
 
[https://dev.eclipse.org/mailman/listinfo/libra-dev https://dev.eclipse.org/mailman/listinfo/libra-dev]
 +
 
== Bugzilla ==
 
== Bugzilla ==
 
[https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Libra https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Libra]
 
[https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Libra https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Libra]
 +
 
== Forum ==
 
== Forum ==
 
[http://www.eclipse.org/forums/eclipse.libra http://www.eclipse.org/forums/eclipse.libra]
 
[http://www.eclipse.org/forums/eclipse.libra http://www.eclipse.org/forums/eclipse.libra]

Latest revision as of 09:53, 16 January 2013

Contents

[edit] Getting Started

[edit] Installation and Use

The Libra features can be installed from the p2 repository of the Indigo Simultaenous Release (since Indigo M6). As a prerequisite you may install Eclipse IDE for Java EE Developers.

The update site contains:

  • OSGi Bundle Facet feature that introduces:
    1. A new facet OSGi Bundle for Dynamic Web, JPA and Utility projects.
    2. Wizard for converting WTP standard projects to OSGi Enterprise bundle projects:
      • Dynamic Web projects to Web Application Bundle projects
      • JPA projects to Persistent Bundle projects
      • Utility projects and simple Java projects to OSGi Bundle projects
Both options modify project's MANIFEST.MF in order to become a valid OSGi bundle.

The facet may be enabled during the project creation or after that from the Properties page of the project. The wizard is available from project's context menu Configure > Convert to OSGi Bundle Projects...

Note that you may need to adjust your target platform accordingly.

LibraInstall.png

[edit] Create new Web Application Bundle

  1. Call the New Dymanic Web Project wizard: New > Project... > Web > Dynamic Web Project
  2. Enter the necessary project information like Project name, Target runtime, etc.
  3. Add the OSGi Bundle facet in the Configuration:
    1. Click on the Modify... button in the Configuration group.
    2. Choose the OSGi Bundle facet in the Project Facets dialog and click OK.
  4. Click Finish to create the Web Application Bundle project.

[edit] Create new OSGi Bundle

  1. Call the New Faceted Project wizard: New > Project... > General > Faceted Project
  2. Enter the necessary project information like Project name.
  3. Click the Next button.
  4. Select the OSGi Bundle and Java facets.
  5. Click Finish to create the OSGi Bundle project.

[edit] Obtaining Sources

You can find the sources available in Git repository

In order to synchronize them locally, you may use the EGit step-by-step procedure.

The EGit/User Guide provides detailed instruction how to work with EGit.

[edit] Updating/Installing EGit

  • Start your Eclipse IDE and navigate to Help->Install New Software->Add...
  • Enter the software update site [1]
  • Select the Eclipse EGit (Incubation) and Eclipse JGit (Incubation) and choose Next> to finish the installation.

During the installation you will be asked to accept the License Agreements.

InstallEGit.jpg

[edit] Identifying Yourself

To identify yourself, follow these instructions these instructions

[edit] Setting up the Home Directory on Windows

To set up the HOME directory, go through these steps

[edit] Configuring SSH in Eclipse

To configure ssh, proceed as follows.

[edit] Clone Git Repository

  • Open the Git Repository Exploring perspective and in the Git Repositories view choose the Clone a Git Repository toolbar button
  • In the URI field of the opened Clone Git Repository wizard enter the URI of the libra git repository: [2] and choose Next

CloneGitRepo.jpg

  • Select the added repository and from its context menu choose Import Projects...
  • Expand the repository tree to Remote Tracking level, select the remote branch origin/master and from its context menu choose Create Branch... to create a new local branch

[edit] Updating Sources

To keep the sources up to date you have to pull the new changes from the upstream branch.

[edit] Build Infrastructure

The build is based on Maven (at least 3.0.0) and Tycho, executed on the Hudson server, hosted at Eclipse Foundation.

There are two Hudson jobs available for Libra:

  • libra - for building the master git branch.
  • libra-indigo - for building the indigo git branch.

[edit] Maven Build Sequence

Complete build sequence for a clean build (assuming $M2_HOME/bin is on the path and local Maven repository at ~/.m2/repository):

[~/org.eclipse.libra/development/org.eclipse.libra.releng] $ mvn clean install

Note that you may need to configure your proxy settings

[edit] Proposing and Committing a Patch

The patch file contains a description of changes of a set of resources which can be automatically applied to another eclipse workspace or git repository. If you want to propose or commit a patch you need to know that the Eclipse update hook will examine the Committer's entries of an incoming push. All the committer's entries have to be made by the committer performing the push, otherwise the push will fail. Furthermore, your committer ID, or the committer e-mail address registered with your committer account at the Eclipse Foundation must be present in the Committer Email record. For more information on that restriction see: this page.

[edit] Proposing a Patch

If you want commit a change on a local feature or bugfix branch and then to export this change into a patch file, follow the steps below:

  1. Open a bug
    • Specify the bug component (General; OSGi Facet or WAR)
    • Complete the fields about the product version, bug severity, type of your hardware, operating systems and write a summary and description of the patch
  2. Open the History view of your Eclipse IDE and choose Create Patch... (The patch file will contain the difference between the commit and its parent in the history view. Note that the filter of the history view applies also for patch creation.)
  3. Start the Patch Wizard, select the location of the patch and choose Next (The name of the patch file is created from the first line of the commit message.)
  4. Change the patch format, if necessary.
  5. Attach the patch created to the bug
  6. Submit the bug

[edit] Committing a Patch

To commit a patch, proceed as follows:

  1. Apply the proposed patch using the Patch Wizard
  2. Test the patch
  3. Commit the patch
  4. Setup push configuration with the following push URL:
    ssh://committer_id@git.eclipse.org/gitroot/libra/org.eclipse.libra.git
  5. Push the patch and see its change number in order to be able to inspect it

[edit] Reproducing a Build to a Certain Change List

Fetch to the specific change and build with Maven as described above.

[edit] Send us feedback

[edit] Mailing list

https://dev.eclipse.org/mailman/listinfo/libra-dev

[edit] Bugzilla

https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Libra

[edit] Forum

http://www.eclipse.org/forums/eclipse.libra