Jump to: navigation, search

Difference between revisions of "Common Build Infrastructure/Getting Started/Build In Eclipse"

(Required settings)
(updated copy + more examples than just GEF)
Line 1: Line 1:
 
{{:DocumentationGuidelines/DraftHeader}}
 
{{:DocumentationGuidelines/DraftHeader}}
  
The process to run a build in Eclipse is getting ever easier.
+
To run a build with Athena, you need to do four things:
  
=== Fetch workspace projects ===
+
# Fetch required build projects into your workspace.
#Download a .psf file, such as [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.dash.commonbuilder.releng/psf/gef.psf?root=Technology_Project&view=co gef.psf]
+
# Close the org.eclipse.releng.basebuilder project.
#Open Eclipse, and do <code>File > Import > Team > Team Project Set</code>. Browse for the .psf file you downloaded above, and import it. You should end up with three new workspace projects.
+
# Fetch required releng project into your workspace.
##org.eclipse.releng.basebuilder
+
# Configure build.properties to suit your system's needs.
##org.eclipse.dash.common.releng
+
# Run build.xml
##org.eclipse.gef.releng
+
#Download [http://downloads.sourceforge.net/ant-contrib/ant-contrib-1.0b2-bin.zip ant-contrib.jar 1.0b2] and put it into <code>org.eclipse.dash.common.releng/lib/ant-contrib.jar</code>.
+
  
{{warning| Ant Contrib 1.0b3 | Ant Contrib 1.0b3 is not supported or recommended. Athena will download the correct jar if you tell it to in the build.properties file.}}
+
=== Fetch build projects ===
 +
 
 +
At minimum, you will need these two projects in your workspace (or elsewhere on disk):
 +
 
 +
* org.eclipse.releng.basebuilder (contains Eclipse Platform, PDE + tools/scripts needed to build)
 +
* org.eclipse.dash.common.releng (contains tools/scripts to communicate & extend PDE)
 +
* your.projects.name.here.releng (contains configurations and settings to drive PDE for building and testing)
 +
 
 +
The simplest way to get the first two projects is to download this [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.dash.common.releng/psfs/athena.cvs.psf?revision=1.1&root=Technology_Project athena.cvs.psf].
 +
 
 +
Next, open Eclipse, and do <code>File > Import > Team > Team Project Set</code>. Browse for the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.dash.common.releng/psfs/athena.cvs.psf?revision=1.1&root=Technology_Project athena.cvs.psf] file you downloaded above, and import it. You should end up with two new workspace projects.
 +
 
 +
=== Close the basebuilder project ===
 +
 
 +
Because the basebuilder project is used OUTSIDE of eclipse, it does not need to be open, or to have everything properly compiled, to function. In particular, due to licensing reasons, there is at least one jar (ie., j2ee.jar or javamail.jar) which is required to have everything in the project compile. This cannot be included in the project because it is not available under an EPL-compatible license.
 +
 
 +
The workaround is therefore to put the jar into the project by hand, or to simply close the project and ignore the compilation errors.
 +
 
 +
=== Fetch releng project ===
 +
<table style="float:right; border: 1px dashed #000080">
 +
<tr><th>Sample Athena Releng Projects</th><tr>
 +
<tr><td>
 +
* [http://dev.eclipse.org/viewcvs/index.cgi/pde/visualization/org.eclipse.pde.visualization.releng/ Eclipse - PDE - Visualization]
 +
 
 +
* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.ecoretools/releng/?root=Modeling_Project Eclipse Modeling - EMF - Ecore Tools]
 +
* [http://dev.eclipse.org/svnroot/modeling/org.eclipse.gmt.modisco/releng/trunk/org.eclipse.gmt.modisco.releng/ Eclipse Modeling - GMT - MoDisco]
 +
 
 +
* [http://dev.eclipse.org/viewcvs/index.cgi/sourceediting/development/athena/org.eclipse.wst.xsl.releng/?root=WebTools_Project Eclipse Web Tools - XSL Tools]
 +
 
 +
* [http://dev.eclipse.org/svnroot/technology/org.eclipse.linuxtools/releng/trunk/org.eclipse.linuxtools.releng/ Eclipse Technology - Linux Tools]
 +
 
 +
* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.gef.releng/?root=Technology_Project Eclipse Tools - GEF]
 +
 
 +
* [http://anonsvn.jboss.org/repos/jbosstools/trunk/jmx/releng/ JBoss Tools - JMX Console]
 +
* [http://anonsvn.jboss.org/repos/jbosstools/trunk/bpel/releng/ JBoss Tools - BPEL Editor]
 +
* [http://anonsvn.jboss.org/repos/jbosstools/trunk/jbpm/releng/ JBoss Tools - jBPM Tools]
 +
</td></tr></table>
 +
 
 +
To fetch your project's releng folder, you will need to know where it is located in CVS or SVN. Some examples to try are at right:
 +
 
 +
Note that some projects include a <code>psfs/</code> folder within their releng project to facilitate checking out sources, as in step 1 above.
 +
 
 +
If you do not have a .releng project for your own code, you can create one based on the above examples.
  
 
=== Configure build.properties ===
 
=== Configure build.properties ===
  
Open <code>org.eclipse.gef.releng/build.properties</code> and edit to suit your needs.  
+
Open <code>your.project.releng/build.properties</code> and edit to suit your needs. There may be examples available for Windows, Linux, and MacOSX to help you get started. You can either copy from the .example file into build.properties, or point <code>build.xml</code> at the alternate build.properties.example.* file, like this:
 +
<table><tr><td>
 +
<property file="build.properties.example.linux" />
 +
</td></tr></table>
  
 
==== Required settings ====
 
==== Required settings ====
  
 
The following properties must be set:
 
The following properties must be set:
 
+
<table><tr><td>
 
  projectid=technology.foo
 
  projectid=technology.foo
 
  zipPrefix=MyFoo
 
  zipPrefix=MyFoo
Line 28: Line 71:
 
  testFeatureToBuildID=org.eclipse.foo.test
 
  testFeatureToBuildID=org.eclipse.foo.test
  
  # if project is incubating, insert "-incubation" string into all generated zip file names; otherwise omit this
+
  # if project is incubating, insert "-incubation" into
 +
# generated zip file names; otherwise omit
 
  incubation=-incubation
 
  incubation=-incubation
  
  # set path and version of JVM to use; must set a variable for each Bundle-RequiredExecutionEnvironment (BREE) used in plugins
+
  # set path and version of JVM to use; must set a variable for  
 +
# each Bundle-RequiredExecutionEnvironment (BREE) used in plugins
 
  JAVA_HOME=/path/to/java/home
 
  JAVA_HOME=/path/to/java/home
 
  JAVA14_HOME=/path/to/java/home
 
  JAVA14_HOME=/path/to/java/home
 
  JAVA50_HOME=/path/to/java/home
 
  JAVA50_HOME=/path/to/java/home
 
  JAVA60_HOME=/path/to/java/home
 
  JAVA60_HOME=/path/to/java/home
 +
</td></tr></table>
  
 
Define binary dependencies using <code>dependencyURLs</code> and/or <code>repositoryURLs</code>. For more examples, see [[Common_Build_Infrastructure/Defining_Binary_Dependencies|Defining Binary Dependencies]]:
 
Define binary dependencies using <code>dependencyURLs</code> and/or <code>repositoryURLs</code>. For more examples, see [[Common_Build_Infrastructure/Defining_Binary_Dependencies|Defining Binary Dependencies]]:
 
+
<table><tr><td>
  dependencyURLs=http://download.eclipse.org/eclipse/downloads/drops/R-3.5.1-200909170800/eclipse-SDK-3.5.1-linux-gtk.tar.gz,http://path/to/other/required.zip
+
  repositoryURLs=\
 +
  http://download.eclipse.org/athena/repos/eclipse-Update-R-3.5.1-200909170800.zip
 +
IUsToInstall=\
 +
  org.eclipse.sdk.feature.group+org.eclipse.sdk.ide
 +
 +
dependencyURLs=\
 +
  http://path/to/some/required-SDK.zip
 +
</td></tr></table>
  
 
Define what steps to perform. To run tests w/o building first, see [[Common_Build_Infrastructure/Testing|Testing]]:
 
Define what steps to perform. To run tests w/o building first, see [[Common_Build_Infrastructure/Testing|Testing]]:
 
+
<table><tr><td>
 
  #default: buildUpdate,buildTests,generateDigests,testLocal,publish,cleanup
 
  #default: buildUpdate,buildTests,generateDigests,testLocal,publish,cleanup
 
  build.steps=buildUpdate
 
  build.steps=buildUpdate
 +
</td></tr></table>
  
 
If you require SVN or do not have the test framework plugins in your map file, you will need this property too, or to perform the equivalent set up manually.
 
If you require SVN or do not have the test framework plugins in your map file, you will need this property too, or to perform the equivalent set up manually.
 
+
<table><tr><td>
 
  # To permit automatic downloads of non-EPL compatible code, set this to property to "I accept"
 
  # To permit automatic downloads of non-EPL compatible code, set this to property to "I accept"
  #thirdPartyDownloadLicenseAcceptance="I accept"
+
  thirdPartyDownloadLicenseAcceptance="I accept"
 +
</td></tr></table>
  
 
==== Optional settings ====
 
==== Optional settings ====
  
 
You can also set other [http://dev.eclipse.org/viewcvs/index.cgi/pde/build/org.eclipse.pde.build/templates/headless-build/build.properties?view=markup PDE variables and compiler settings] in your releng project's build.properties:
 
You can also set other [http://dev.eclipse.org/viewcvs/index.cgi/pde/build/org.eclipse.pde.build/templates/headless-build/build.properties?view=markup PDE variables and compiler settings] in your releng project's build.properties:
 
+
<table><tr><td>
 
  compilerArg=-enableJavadoc -encoding ISO-8859-1
 
  compilerArg=-enableJavadoc -encoding ISO-8859-1
 
  flattenDependencies=true
 
  flattenDependencies=true
 
  parallelCompilation=true
 
  parallelCompilation=true
 
  generateFeatureVersionSuffix=true
 
  generateFeatureVersionSuffix=true
 +
</td></tr></table>
  
 
=== Run a build ===
 
=== Run a build ===
  
Select <code>org.eclipse.gef.releng/build.xml</code>, then <code>Run As > Ant Build</code>.
+
Select <code>your.project.releng/build.xml</code>, then <code>Run As > Ant Build</code>.
 
* Ensure you have CVS installed on your machine.
 
* Ensure you have CVS installed on your machine.
 
* If the compiler fails with errors like "Cannot find Object", make sure you have a JAVA_HOME for every BREE in your manifests.  Please see the [[Common Build Infrastructure/Getting Started/FAQ]].
 
* If the compiler fails with errors like "Cannot find Object", make sure you have a JAVA_HOME for every BREE in your manifests.  Please see the [[Common Build Infrastructure/Getting Started/FAQ]].
  
A log of the build will appear as <code>org.eclipse.gef.releng/buildlog.latest.txt</code>.
+
A log of the build will may appear as <code>your.project.releng/buildlog.latest.txt</code>, if you have configured a launch configuration to do so. Otherwise a complete buildlog.txt should appear in the destination folder where the build is created, eg., <code>/tmp/build/N201001282334/buildlog.txt</code>.
* If you receive errors related to test results not available, remove the "test" step from build.steps line.
+
* If you do not yet have tests available in your repository (or have not linked them from your map file(s), you may receive errors running the "test" or "testLocal" step.
  
 
==== Troubleshooting / server setup ====
 
==== Troubleshooting / server setup ====

Revision as of 18:52, 28 January 2010

Warning2.png
Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.


To run a build with Athena, you need to do four things:

  1. Fetch required build projects into your workspace.
  2. Close the org.eclipse.releng.basebuilder project.
  3. Fetch required releng project into your workspace.
  4. Configure build.properties to suit your system's needs.
  5. Run build.xml

Fetch build projects

At minimum, you will need these two projects in your workspace (or elsewhere on disk):

  • org.eclipse.releng.basebuilder (contains Eclipse Platform, PDE + tools/scripts needed to build)
  • org.eclipse.dash.common.releng (contains tools/scripts to communicate & extend PDE)
  • your.projects.name.here.releng (contains configurations and settings to drive PDE for building and testing)

The simplest way to get the first two projects is to download this athena.cvs.psf.

Next, open Eclipse, and do File > Import > Team > Team Project Set. Browse for the athena.cvs.psf file you downloaded above, and import it. You should end up with two new workspace projects.

Close the basebuilder project

Because the basebuilder project is used OUTSIDE of eclipse, it does not need to be open, or to have everything properly compiled, to function. In particular, due to licensing reasons, there is at least one jar (ie., j2ee.jar or javamail.jar) which is required to have everything in the project compile. This cannot be included in the project because it is not available under an EPL-compatible license.

The workaround is therefore to put the jar into the project by hand, or to simply close the project and ignore the compilation errors.

Fetch releng project

Sample Athena Releng Projects

To fetch your project's releng folder, you will need to know where it is located in CVS or SVN. Some examples to try are at right:

Note that some projects include a psfs/ folder within their releng project to facilitate checking out sources, as in step 1 above.

If you do not have a .releng project for your own code, you can create one based on the above examples.

Configure build.properties

Open your.project.releng/build.properties and edit to suit your needs. There may be examples available for Windows, Linux, and MacOSX to help you get started. You can either copy from the .example file into build.properties, or point build.xml at the alternate build.properties.example.* file, like this:

<property file="build.properties.example.linux" />

Required settings

The following properties must be set:

projectid=technology.foo
zipPrefix=MyFoo
version=0.5.0
buildType=N
mainFeatureToBuildID=org.eclipse.foo.all
testFeatureToBuildID=org.eclipse.foo.test
# if project is incubating, insert "-incubation" into
# generated zip file names; otherwise omit
incubation=-incubation
# set path and version of JVM to use; must set a variable for 
# each Bundle-RequiredExecutionEnvironment (BREE) used in plugins
JAVA_HOME=/path/to/java/home
JAVA14_HOME=/path/to/java/home
JAVA50_HOME=/path/to/java/home
JAVA60_HOME=/path/to/java/home

Define binary dependencies using dependencyURLs and/or repositoryURLs. For more examples, see Defining Binary Dependencies:

repositoryURLs=\
 http://download.eclipse.org/athena/repos/eclipse-Update-R-3.5.1-200909170800.zip
IUsToInstall=\
 org.eclipse.sdk.feature.group+org.eclipse.sdk.ide

dependencyURLs=\
 http://path/to/some/required-SDK.zip

Define what steps to perform. To run tests w/o building first, see Testing:

#default: buildUpdate,buildTests,generateDigests,testLocal,publish,cleanup
build.steps=buildUpdate

If you require SVN or do not have the test framework plugins in your map file, you will need this property too, or to perform the equivalent set up manually.

# To permit automatic downloads of non-EPL compatible code, set this to property to "I accept"
thirdPartyDownloadLicenseAcceptance="I accept"

Optional settings

You can also set other PDE variables and compiler settings in your releng project's build.properties:

compilerArg=-enableJavadoc -encoding ISO-8859-1
flattenDependencies=true
parallelCompilation=true
generateFeatureVersionSuffix=true

Run a build

Select your.project.releng/build.xml, then Run As > Ant Build.

  • Ensure you have CVS installed on your machine.
  • If the compiler fails with errors like "Cannot find Object", make sure you have a JAVA_HOME for every BREE in your manifests. Please see the Common Build Infrastructure/Getting Started/FAQ.

A log of the build will may appear as your.project.releng/buildlog.latest.txt, if you have configured a launch configuration to do so. Otherwise a complete buildlog.txt should appear in the destination folder where the build is created, eg., /tmp/build/N201001282334/buildlog.txt.

  • If you do not yet have tests available in your repository (or have not linked them from your map file(s), you may receive errors running the "test" or "testLocal" step.

Troubleshooting / server setup

If needs be, you may find additional information related to troubleshooting or server configuration here.

Next Steps

Once you can build in Eclipse, you might want to get a job added to Hudson so you can run continuous integrations or nightlies, then start publishing to download.eclipse.org.