View source

From Eclipsepedia

for Common Build Infrastructure/Getting Started
You do not have permission to do that, for the following reason:
The action you have requested is limited to users in the group user.
You can view and copy the source of this page:
{{:DocumentationGuidelines/DraftHeader}}

{{Warning2|text=
This information is preliminary and subject to change. If you see an error or omission, please feel free to [http://wiki.eclipse.org/index.php?title=Common_Build_Infrastructure/Getting_Started&action=edit edit it].
}}

== Create Configuration Project ==

The first step is to create a project ''(often called a .releng project)'' to house your configuration settings. Here are [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/?root=Technology_Project some sample projects to get you started].

At its simplest, this is:

* '''build.properties''' -- settings for the build
* '''maps/build.map''' -- where to fetch sources (you can have as many .map files as you need)

However, you will likely need to feed in extra dependencies to the build, if it requires more than just the Eclipse "Classic" SDK to build (ie, JDT, PDE, CVS). 

* '''buildExtra.xml''' -- extra inputs and packaging steps

You will likely also want to run automated tests as part of your build. For this you'll need:

* '''testing.properties''' -- properties specific to running tests

Finally, to control how your build is published, you'll need another properties file:

* '''promote.properties''' -- properties specific to publishing builds 

Check all these files into CVS or SVN.

== Set Up Locally ==

===In Eclipse===

To set up to build locally in Eclipse, see [[Common_Build_Infrastructure/Getting_Started/Build_In_Eclipse]].

===Commandline / Server===

To set up to build commandline outside Eclipse, eg., as a server like build.eclipse.org, read on:

<table><tr valign="top"><td>
To set up the local bootstrapping required to run a build, you can run this script: 

* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.dash.commonbuilder.releng/setup/localhost.setup.sh?root=Technology_Project&view=markup localhost.setup.sh].

Note that this script is currently only supported on Fedora 10. We're looking for testers to try it out on other linuxes and on Windows via cygwin. If you can't get it working, use it as a checklist for the manual steps required to get your local machine set up to build.
</td><td>
Once you've set up your environment, you should have something like this:

 3rdPartyJars/ [libraries and 3rd party jars, including [http://downloads.sourceforge.net/ant-contrib/ant-contrib-1.0b3-bin.zip ant-contrib.jar]]
 downloads/    [dependencies, cached and reused]
 
 scripts/      [build system scripts & tools]
 
 org.eclipse.dash.commonbuilder.releng_HEAD/ [a specific version of o.e.d.c.releng]
 org.eclipse.dash.commonbuilder.releng/      [a symlink to the above]
 
 org.eclipse.releng.basebuilder_R35_M5/ [a specific version of o.e.r.bb]
 org.eclipse.releng.basebuilder/        [a symlink to the above]
 
 [http://downloads.sourceforge.net/svn-pde-build/org.eclipse.pde.build.svn-1.0.1RC2.zip org.eclipse.pde.build.svn-1.0.1RC2.zip] [required for making PDE understand SVN map files]
</td></tr>
</table>

== Run A Build ==

=== What Can I Do? ===

* You can build in Eclipse using Ant and a build.xml script, or headlessly via commandline using start.sh (which in turn launches Eclipse's AntRunner too).

* You can have requirements in your workspace (o.e.releng.basebuilder, o.e.d.common.releng, o.e.myproject.releng), or in /opt/public/cbi/build/, or in /tmp/build/. As long as they're on disk or you specify where to put them, they'll be used or checked out then used. We've also provided [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.dash.commonbuilder.releng/psf/?root=Technology_Project a few sample .psf files] to help you share this configuration with your team. 

* You can build in, for example, /opt/public/cbi/build/tools/gef/downloads/drops/3.4.0/N200902260105/, or in /tmp/build/tools/gef/downloads/drops/3.4.0/N200902260105/ or in /tmp/build/N200902260105 - whatever you want you can do.

* You can build with Hudson - there are [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.dash.commonbuilder.releng/hudson/?root=Technology_Project sample wrapper scripts for start.sh] to pass though Hudson parameters. You can either copy the whole script into the hudson config field, or if the script is elsewhere on the disk, you can simply point at it like this:

 export BUILDTYPE="${BUILDTYPE}"
 export EXTRAFLAGS="${EXTRAFLAGS}"
 . /opt/public/cbi/build/org.eclipse.dash.common.releng/hudson/gef-3.4.x-nightly.sh

=== Requirements===

* Ant-Contrib is required to run the build. You can put this jar in one of 4 different places, at your discretion:

 <taskdef resource="net/sf/antcontrib/antlib.xml">
   <classpath>
     <pathelement path="${classpath}" />
     <pathelement location="${relengCommonBuilderDir}/lib/ant-contrib.jar" />
     <pathelement location="${relengBuilderDir}/lib/ant-contrib.jar" />
     <pathelement location="${thirdPartyJarsDir}/ant-contrib.jar" />
     <pathelement location="/usr/share/java/ant-contrib.jar" />
   </classpath>
 </taskdef>

* The SVN PDE plugin will be automatically downloaded and unpacked into o.e.releng.basebuilder if the thirdPartyDownloadLicenseAcceptance flag is properly set in the project's build.properties; this is a bit of a legal hack for making people accept that they need some non-EPL stuff to build from SVN sources. Alternatively, you can download this plugin yourself and add it to basebuilder by hand.

* While most of the system is Eclipse- and Ant-based, a few small scripts are still shell script based, and thus will only run on a Linux box. The most prominent example of this is the script that runs the tests because it's intended to be platform-specific so that a build could run tests on multiple platforms.

As such, if you run on a Mac or Windows box (with or without Cygwin), your mileage will vary. Builds have been tested and run on Linux using the following Eclipse platform versions: ppc, x86, and x86_64. 

<b style="color:red">If you have test hardware or are willing to contribute translations of shell scripts (to Ant, to Java, or to .cmd/.bat), please don't hesitate to [[Common_Build_Infrastructure#Contributing|drop us a line]].</b>

===Build Types===
'''R'''

'''Releases are builds''' that have been declared major releases by the development
team - for example "R1.0".  Releases are the right builds for people who want
to be on a stable, tested release, and don't need the latest greatest features
and improvements.  Non-release builds are named according to the date  
of the build - for example 200904061234 is the build from 6 April 2009 @ 12:34pm; release builds are named for the release (eg., using `-buildAlias 2.0.0`).

'''S'''

'''Stable builds''' are integration builds that have been
found to be stable enough for most people to use.  They are promoted from
integration build to stable build by the development team after they have been
used for a few days and deemed reasonably stable.  The latest stable build is
the right build for people who want to stay up to date with what is going on in
the latest development stream and don't mind putting up with a few problems in
order to get the latest greatest features and bug fixes.  The latest stable
build is the one the development team likes people to be using, because of the
valuable and timely feedback. Stable builds include Milestones and Release Candidates, and are identified using `-buildAlias 2.0.0M7` or `-buildAlias 0.7.0RC2`

'''I'''

Periodically, component teams version off their work in what they believe is a
stable, consistent state, and they update the build configuration to indicate
that the next integration build should take this version of the component.
'''Integration builds''' are built from these stable component versions that
have been specified by each component team as the best version available. 
Integration builds may be promoted to stable builds after a few days of 
testing.  Integration builds are built whenever new stable component versions
are released into the build. Healthy, agile teams should be producing an I build weekly or bi-weekly.

'''M'''

'''Maintenance Builds''' - Periodically builds for maintenance of the current release
will be performed.  They will not necessarily be stable builds.  When the
maintenance is finalized and released, it will be moved up to a Release build.
If the build name starts with an "M" i.e. M20090405, then it has not been
tested for stability.  If it is a release candidate, i.e.  0.5.1RC, then it
is a stable build, and should be of type S, not M. The final release build in a maintenance cycle should be of type R, and identified using `-buildAlias 0.5.1`

'''N'''

'''Nightly Builds''' are produced over night from whatever has been released
into the HEAD stream of the SCM repository.  They are only unit tested and will
sometimes have problems.  Some will not work at all.  These drops are normally
only useful to developers actually working on this project. Not all projects need publish N builds if they produce at least one or two monthly I builds.

===Commandline Headless Build===

Builds are run though [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.dash.commonbuilder.releng/tools/scripts/start.sh?root=Technology_Project&view=markup start.sh], which sets up configuration variables and invokes Eclipse's AntRunner to run the build. Testing is done by having this ant thread call into the shell to start a new Eclipse thread on a different display (or one day, a remote machine). As such, there is still some dependency on bash scripting for the build system to work. We plan to remove this dependency over time.

Here's a sample invokation of start.sh -- run the script without any commandline options for other examples, or check out the README.txt files in the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/?root=Technology_Project other sample projects]:

 cd /opt/public/cbi/build/org.eclipse.dash.common.releng; \
 cvs up -Pd; cd tools/scripts; ./start.sh -projectid tools.gef -version 3.4.0 \
  -projRelengRoot ':pserver:anonymous@dev.eclipse.org:/cvsroot/technology' \
  -projRelengPath 'org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.gef.releng'
   2>&1 | tee /opt/public/cbi/logs/buildlog_`date +%H%M%S`.txt

* To run locally, check out org.eclipse.releng.basebuilder, org.eclipse.dash.common.releng, and the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.gef.releng/?root=Technology_Project org.eclipse.gef.releng project in the Dash Athena project], then run the Ant script build.xml. You can do all three checkouts using [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=markup this psf file]

* Note that you should use a such as the following in build.properties, as ${WORKSPACE} is not defined unless run from within Hudson:

 writableBuildRoot="${HOME}/athena/build"

===In Eclipse With AntRunner===

You can create a simple project.releng project, and use that to run a headless build from within your Eclipse workspace. The project basically consists of properties, build instuctions (beyond the defaults) and one or more map files to define where to get sources if not already cached locally. [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.gef.releng/?root=Technology_Project Here's a sample].

For more information, see [[Common Build Infrastructure/Getting Started/Build In Eclipse]].

===In Hudson===

<b style="color:red">If you want to build with Hudson on build.eclipse.org, see [[Common Build Infrastructure/Getting Started/Build In Hudson|Getting Started - Build In Hudson]].</b>

Or, start your own local Hudson instance (on your vserver or home machine) and use that. To start Hudson, simply [http://hudson.gotdns.com/latest/hudson.war download the latest hudson.war], then run:

 java -jar hudson.war &

Then, to get started, copy an existing configuration. Everything in Hudson can [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.dash.commonbuilder.releng/hudson/?root=Technology_Project be scripted and stored in VCS for reference].

In the above configs, a pre-checked-out cache of basebuilder and common.releng are available in <code>build.eclipse.org:/opt/public/cbi/build/</code> to speed up builds and to reduce CVS checkout churn.

* As a developer working on the common.releng code, you will need to <code>cvs up</code> in there to ensure your checked in changes are pushed to the build system; however, bear in mind that your changes will be public immediately and anything you broke will be immediately obvious... so play nice (test locally first)!

* As a user running builds using the common.releng code, you can choose to checkout or export from a given CVS tag for common.releng and basebuilder rather than using symlinks if you prefer to not live on the bleeding edge. When you want to move up to a new stable tag, you can clear your Hudson workspace and start fresh. In this case your [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.dash/athena/org.eclipse.dash.commonbuilder/org.eclipse.dash.commonbuilder.releng/hudson/?root=Technology_Project startup script] will need to be a little different.

* If using the shared Hudson instance on build.eclipse.org, use the following path in your myproject.releng/build.properties file:

 writableBuildRoot="${WORKSPACE}/build"

===Build From Local Sources===

It's a bit of a hack at the moment ({{bug|252774}}), but you can use locally cached sources (eg., in your Eclipse workspace, or in the Hudson workspace) from which to build. Why would you want this? So that you can build in Hudson from HEAD instead of from a mapfile (and tag AFTER the build), or so you can build from locally-edited files and try out a change w/o having to commit it into the repo and possibly break the build.

Here's how:

* Symlink org.eclipse.test and org.eclipse.ant.optional.junit into your own project's repo so that a .psf fetch or other cvs/svn checkout will get them:

 cd /cvsroot/tools/org.eclipse.gef/test; \
 ln -s /cvsroot/eclipse/org.eclipse.test/; \
 ln -s /cvsroot/eclipse/org.eclipse.ant.optional.junit/

Thus:

<pre>/cvsroot/tools/org.eclipse.gef/test
  org.eclipse.draw2d.test/
  org.eclipse.zest.tests/
  org.eclipse.gef.test/
  org.eclipse.test -> /cvsroot/eclipse/org.eclipse.test/
  org.eclipse.ant.optional.junit -> /cvsroot/eclipse/org.eclipse.ant.optional.junit/</pre>

* Next, point the build at the folder in which the sources are located. 

==== Hudson Configuration ====

* For Hudson, first configure the build to check out the sources

::[[Image:Hudson-CVS-configuration-whole-tree-in-legacy-mode.jpg]]

* Then, use this option when invoking start.sh:

 -localSourceCheckoutDir /opt/users/hudsonbuild/.hudson/jobs/cbi-gef-3.5.x-nightly/workspace/org.eclipse.gef

==== Local Build In Eclipse Configuration ====

* For a local Eclipse build, it depends on how/where you checked out sources. If you checked out the whole /cvsroot/tools/org.eclipse.gef folder as a single project in your workspace, you might might specify it in build.properties like this:

 localSourceCheckoutDir=~/workspace/org.eclipse.gef

* Then, to be able to properly edit & compile plugins in your workspace, you'll have to File > Import > Existing Projects > ~/workspace/org.eclipse.gef/plugins/ > select plugins to import. Do not copy them to the new project location - you want them to simply be a reference to the actual subfolder path (linked).

* With everything imported from the local folder, you can edit them as projects, and spin a build to verify your changes haven't broken the build. 

* Next, close or delete the whole-tree project (do not delete from disk, only the workspace). This will prevent Eclipse getting the parent folder and its subfolders out of sync, and you won't see the same the same files listed twice in the Synchronize view.

== Debug Build ==

Here are some general tips for finding log files and sifting the build's tea leaves:

* Always log to a file, preferably a unique one. You can watch console output AND log to file (standard out and standard error) with this: 

 start.sh ... 2>&1 | tee /opt/public/cbi/logs/buildlog_`date +%H%M%S`.txt

* You can also use this, which will dump a log in your build's folder for you:

 start_logger.sh

* Logs can be found in the build's folder like this:

 find /path/to/build/folder -type f -name "*log" -o -name "*log.txt" -o -name "*log.zip"

* Search logs for keywords like "ERROR" and "FAIL" to see what went wrong

* Chances are if something really bad happened, it occurred in the first or last 100 lines of the log.

== See Also ==

* [[Common_Build_Infrastructure/Getting_Started/FAQ|Getting Started FAQ]]
* [[Modeling_Project_Releng/Building_Zips_And_Jars#Build_Problem_FAQ | Build Problem FAQ]]
* [[Modeling_Project_Releng/Building_Zips_And_Jars#Testing_Problem_FAQ | Testing Problem FAQ]]


[[Category:Athena Common Build]]
[[Category:Releng]]
[[Category:Draft_Documentation]]
Templates used on this page:
Return to Common Build Infrastructure/Getting Started.
Retrieved from "http://wiki.eclipse.org/Common_Build_Infrastructure/Getting_Started"
Home Privacy Policy Terms of Use Copyright Agent Contact About Eclipsepedia	Copyright © 2009 The Eclipse Foundation. All Rights Reserved
Eclipse

View source

From Eclipsepedia

Personal tools
