Difference between revisions of "Graphical Modeling Framework/Build"

From Eclipsepedia

Jump to: navigation, search
m
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Introduction==
+
This page is no more accurrate.
This document describes how to build GMF components from the command line using Ant scripts, including the running of unit tests and operation under [http://cruisecontrol.sf.net CruiseControl].
+
  
Note that while there is no mandated standard for builds among Eclipse projects, they generally follow a similar process to what is described here; that is, they leverage the [http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.releng.eclipsebuilder/readme.html?rev=HEAD&content-type=text/html org.eclipse.releng.basebuilder] framework. This framework enables headless operation of the Eclipse [http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.releng.basebuilder/readme.html?rev=HEAD&content-type=text/html PDE build] functionality. The GMF build process was developed using examples found in the Platform, GEF, EMF, VE, and WTP projects.
+
See [[Common Build Infrastructure]]
 
+
A release engineering [http://download.eclipse.org/eclipse/downloads/drops/R-3.1-200506271435/download.php?dropFile=org.eclipse.releng.tools_3.1.0.zip tool] is available for use with this framework. Information on its use can be found below.
+
==Prerequisites==
+
A number of prerequisites need to be installed on the build machine, as follows:
+
# [http://www.nongnu.org/cvs/ CVS] version 1.10 or higher
+
# [http://java.sun.com/j2se/1.5.0/download.jsp J2SE 5.0]
+
# [http://www.info-zip.org/pub/infozip/ Info-Zip zip and unzip]
+
# [http://ant.apache.org/ Ant]
+
# [http://cruisecontrol.sf.net/ CruiseControl] (optional)
+
# [http://jakarta.apache.org/tomcat/ Tomcat] or similar webserver (optional)
+
 
+
For more information on PDE Build, refer to the [http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.releng.basebuilder/readme.html?rev=HEAD&content-type=text/html plug-in] itself.
+
 
+
For examples, refer to the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng.eclipsebuilder/ org.eclipse.releng.eclipsebuilder] plug-in and its [http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.releng.eclipsebuilder/readme.html?rev=HEAD&content-type=text/html readme].
+
 
+
==Setup==
+
With the prerequisites installed, follow these steps to setup your environment and build the GMF components:<br /><br />
+
# Add the zip, unzip, and cvs executables to your PATH environment variable.<br />
+
# Add the jre/bin directory of the installed JDK to your PATH environment variable.<br />
+
# Add the ant/bin directory of the installed Ant to your PATH environment variable.<br />
+
# Create a directory for the build, e.g.
+
##<code>mkdir /gmfbuild</code> <b>Note</b> that you will want to place this directory close to the root of the drive on Windows, due to path length limitations. Optionally, you may choose to use the -DbuildRoot property to target a location near the root.
+
# Install the v3.1 Eclipse release engineering basebuilder (this installation will be used to run the build tools, it is not itself a GMF installation): Export <b>org.eclipse.releng.basebuilder</b> from the CVS repository <b>/home/eclipse</b> into the build directory, e.g.
+
##<code>cd /gmfbuild</code>
+
##<code>cvs -d :pserver:anonymous@dev.eclipse.org:/home/eclipse export -r HEAD org.eclipse.releng.basebuilder</code>
+
# Export <b>org.eclipse.gmf.releng.builder</b> into the build directory. <code>cvs -d :pserver:anonymous@dev.eclipse.org:/cvsroot/technology export -r HEAD -d org.eclipse.gmf.releng.builder org.eclipse.gmf/releng/org.eclipse.gmf.releng.builder</code>
+
# Before running the build, you may wish to adjust some of the build properties (see [#antbuildproperties|below]). In particular, you may want to comment-out the 'useMirror' property found in the main build.properties file (in the 'scripts' directory). By default, the GMF build machine uses a local [http://jakarta.apache.org/tomcat/ Tomcat] installation for an update site and [http://cruisecontrol.sf.net CruiseControl] reporting. Technically, the build should function without a local mirror and default to the main update site for dependency installation, which is obviously not desired for frequent builds.
+
 
+
By default, the build will create the following structure, assuming a 'gmfbuild' root was created as indicated above. This structure also shows the default expected Tomcat and CruiseControl locations, which are configurable:
+
{|  width="100%" border="0"
+
|  colspan="6" | <strong>/gmfbuild</strong>
+
|  width="62%" | Root of build (named as in instructions above)
+
|-
+
|  width="2%" | &nbsp;
+
|  colspan="5" bordercolor="0" | <strong>/build</strong>
+
| Root of the build output (configurable with -DbuildRoot
+
property)
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/artifacts</strong>
+
| Root of component build results, with a subdirectory for each
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/checkout</strong>
+
| CVS structure used by CruiseControl
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/doc</strong>
+
| Build directory of the 'doc' component
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/eclipse</strong>
+
| Base installation to compile against and execute tests
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/examples</strong>
+
| Build directory of the 'examples' component
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/logs</strong>
+
| Location of CruiseControl logs
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/runtime</strong>
+
| Build directory of the 'runtime' component
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/sdk</strong>
+
| Build directory of the 'sdk' component
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/tests</strong>
+
| Build directory of the 'tests' component
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/updateSite</strong>
+
| Target for generated update jars, replicated on local mirror if
+
used
+
|-
+
|  width="2%" | &nbsp;
+
|  colspan="5" bordercolor="0" | <strong>/org.eclipse.gmf.releng.builder</strong>
+
| GMF releng builder
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/doc</strong>
+
| Script to build the org.eclipse.gmf.doc feature
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/examples</strong>
+
| Script to build the org.eclipse.gmf.examples feature
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/runtime</strong>
+
| Script to build the org.eclipse.gmf feature
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/scripts</strong>
+
| Directory containing build, tests, update, cruise, etc. scripts.
+
Execute from this directory.
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/sdk</strong>
+
| Script to build the org.eclipse.gmf.sdk feature
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/tests</strong>
+
| Script to bulid the org.eclipse.gmf.tests feature
+
|-
+
|  width="2%" | &nbsp;
+
|  colspan="5" bordercolor="0" | <strong>/org.eclipse.releng.basebuilder</strong>
+
| Eclipse releng builder
+
|-
+
|  colspan="6" | <strong>/java</strong>
+
|  width="62%" | Root of Tomcat and CruiseControl
+
|-
+
|  width="2%" | &nbsp;
+
|  colspan="5" bordercolor="0" | <strong>/cruisecontrol-2.3.1</strong>
+
| CruiseControl installation
+
|-
+
|  width="2%" | &nbsp;
+
|  colspan="5" bordercolor="0" | <strong>/Tomcat 5.5</strong>
+
| Tomcat installation
+
|}
+
 
+
==Run the build==
+
<b>cd</b> to the 'scripts' directory under org.eclipse.gmf.releng.builder and execute the build command passing the desired component to target (on Windows) :<ul><li>cd org.eclipse.gmf.releng.builder\scripts</li><li>build.bat -Dcomponent=sdk &#124; runtime &#124; examples &#124; tests &#124; doc</li></ul>
+
+
<p>Optionally, you can use the following command:</p>
+
<ul><li>java -jar ..\org.eclipse.releng.basebuilder\startup.jar -application org.eclipse.ant.core.antRunner -Dcomponent=sdk &#124; runtime &#124; examples &#124; tests &#124; doc</li></ul><br />
+
<p><b>Note</b> that the download of the Eclipse SDK and/or test framework may fail using the Ant 'get' task, so you may have to download these elements and place in the 'build' folder manually. These zips are maintained for future use in the 'build' directory to make -DcleanBase builds quicker. Notice that unless a local mirror is installed, each dependent feature (EMF, GEF, etc.) will be downloaded from its respective update site with each -DcleanBase build.
+
+
Therefore, it is recommended that a local mirror be used to speed up the process and to reduce stress on the update sites.</p><p> The component property value sets the name of the directory in org.eclipse.gmf.releng.builder which contains the Ant scripts that build a given GMF component, as descibed below: <br /></p>
+
{|  width="100%" border="1"
+
|  width="25%" | <b>Component</b> (directory name in
+
org.eclipse.gmf.releng.builder)
+
|  width="75%" | <b>Description</b>
+
|-
+
|  width="25%" | sdk
+
|  width="75%" | This directory contains the scripts used to build
+
the GMF SDK feature (org.eclipse.gmf.sdk). A GMF SDK includes the
+
runtime feature and is comprised of binaries and sources.
+
|-
+
|  width="25%" | runtime
+
|  width="75%" | This directory contains the scripts used to build
+
the GMF runtime feature (org.eclipse.gmf). The GMF runtime component
+
contains only those binaries required to run a GMF-based
+
application.
+
|-
+
|  width="25%" | examples
+
|  width="75%" | This directory contains the scripts used to build
+
the GMF example feature (org.eclipse.gmf.examples) with sources. <b>Note</b>
+
that the SDK build is a prerequisite.
+
|-
+
|  width="25%" | tests
+
|  width="75%" | This directory contains the scripts used to build
+
and execute the GMF unit tests feature (org.eclispe.gmf.tests). <b>Note</b>
+
that the SDK and examples builds are prerequisites.
+
|-
+
|  width="25%" | doc
+
|  width="75%" | This directory contains the scripts used to build
+
the GMF documentation feature (org.eclipse.gmf.doc).
+
|}
+
<br />
+
A number of properties described below can be passed in via the build command to override the default settings. Of course, direct modification of the properties is an alternative. <b>Note</b> that if you choose to set the 'buildDirectory' property, it will need to end in the name of the component. It is recommended that 'buildRoot' be used instead, as it will have the component name appended to form the 'buildDirectory' property by default. By default, 'buildRoot' will be a sibling of the org.eclipse.gmf.releng.builder directory.<br />
+
 
+
<b>Examples:</b>
+
<b>build -Dcomponent=sdk -javacFailOnError=false -DjavacVerbose=false -DbuildRoot=d:\mybuild</b><br />
+
 
+
This builds a GMF SDK in the directory d:\mybuild\sdk. &quot;-DjavaVerbose=false&quot; indicates that no compile logs will be generated and &quot;-javacFailOnError=false&quot; will cause the build to not fail if there are any compile errors.<br />
+
 
+
<b>build -Dcomponent=runtime -DbuildRoot=d:\gmfbuilds -DbaseLocation=d:\eclipse\eclipse3.1</b>
+
 
+
This builds a GMF runtime in the directory &quot;d:\gmfbuilds\runtime&quot; yet uses an installation of eclipse located at 'd:\eclipse\eclipse3.1' as the base to build against.<br />
+
 
+
<b>build -Dcomponent=tests -DbuildRoot=d:\mybuild -DcleanBase=true -Dclean=true</b>
+
 
+
This builds the GMF test plug-ins from scratch, as 'clean' is used. The build will also delete the base installation and unzip a fresh copy of Eclipse and install GMF's dependencies. <b>Note</b> that an 'sdk' build is a necessary dependency of the 'tests' build.<br />
+
 
+
==Using a local mirror==
+
The GMF build process utilizes the Eclipse update manager to install its dependencies. If you plan to run a clean build frequently, it is recommended that you configure a local mirror to provide the features for installation. Simply uncomment the 'useMirror' property set in the build.properties file(s) and install a local HTTP server to enable this functionality. It is recommended that Tomcat is used, as it can also serve to provide the CruiseControl reporting described below.
+
 
+
GMF builds utilize the update manager via the command line for the installation of build dependencies (e.g. EMF &amp; GEF), and also to install GMF itself for unit tests runs. This has the added benefit of testing update site packaging and leverages the ability to update and maintain a local mirror site. The alternative is to download archives from the Eclipse website, which may turn out to be a better approach ;-)
+
 
+
To use a local mirror, you will need to install Tomcat and perform the following steps to setup the local update site:
+
 
+
* <code>Adjust the 'localUpdateSite' and 'localUpdateSitePath' properties in the main build.properties to reflect yourconfiguration.</code>
+
* <code>cd org.eclipse.gmf.releng.builder\scripts</code>
+
* <code>run 'build initLocalMirror'</code>
+
* <code>run 'build' command with -Dcomponent argument as described above</code>
+
 
+
Run the build and then navigate to http://localhost/updateSite (or similar, depending on your configuration). If you had run the build previously, you may want to rerun with -DcleanBase=true option in order to force the mirror and install of GMF dependencies locally.
+
 
+
Without the mirror running, the build will resort to using the official update sites for dependencies, while using a simple unzip of GMF components (when running tests). When running, each build will produce update site jars which are then copied to the update site directory.
+
 
+
==Using CruiseControl==
+
The GMF project utilizes [http://cruisecontrol.sf.net|CruiseControl] to manage its automated build process. The following basic steps are required to leverage CruiseControl:
+
* Install [http://cruisecontrol.sf.net|CruiseControl] (version 2.3.1 is used currently)
+
* Check the settings of build.properties and config.xml files, modifying as necessary. In particular, the schedule interval, email server and addresses.
+
* If using Tomcat for the reporting component, follow the CC instructions to install the cruisecontrol.war and modify the web.xml file to point at the build's log and artifact locations. These will be specified in the CC config.xml file and are by default /build/logs and /build/ccpublish, respectively. The installation is as simple as copying the cc/reporting/jsp/dist/cruisecontrol.war file into the tomcat/webapps directory.
+
* You may want to adjust the maximum memory setting for Tomcat, and copy the xalan.jar provided with CruiseControl into the WEB-INF/lib directory of the exploded cruisecontrol webapp to avoid problems rendering larger reports.
+
* To run CruiseControl as a service on Windows, follow the instructions provided [http://confluence.public.thoughtworks.org/display/CC/RunningCruiseControlAsaWindowsService|here].
+
 
+
To invoke CruiseControl, follow the instructions below:
+
* <code>cd org.eclipse.gmf.releng.builder\scripts</code>
+
* <code>cruise</code>
+
 
+
<b>Note</b> that the checkout command is run initially and produces a full checkout structure of GMF in a 'checkout' subfolder of 'build'. This is necessary for CC to check for changes and kick off a build. It seems necessary for this duplication to exist, as the PDE build uses the 'export' CVS command and not 'checkout' as is required when checking for changes.
+
 
+
Also, <b>note</b> that it should be possible for much of the scripts here and in the build itself to be generated from plug-ins and features. Perhaps future versions of the build will take advantage of these possibilities.
+
 
+
==Ant build.properties==
+
There are a number of Ant properties declared in the build.properties file, most of which are provided by the org.eclipse.releng.basebuilder utility and are described in [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng.eclipsebuilder/readme.html?rev=1.24 this] document. Below are a list of additional properties found in GMF's build process and their description.
+
 
+
Each property can be overridden by setting them at the command line at build time or by changing them directly in the component's build.properties file, or a map definition's build.cfg file.
+
+
{|  width="100%" border="1"
+
|  Component build.properties |
+
|-
+
| buildRoot
+
| This directory is the root of the build folders for each component (e.g. sdk, tests, etc.) and the CruiseControl folders (when used). By default, it is a sibling to the releng folders. In GMF builds, it is recommended that you stick to setting buildRoot and avoid the buildDirectory property found within the scripts.
+
|-
+
| cleanBase
+
| Normally commented out, but if present will cause the base to be deleted prior to the build. This will remove the base Eclipse installation and force an updated install of all dependencies.
+
|-
+
| clean
+
| This will normally cause the cleaning of all output directories prior to the build, but in GMF will also cause a cleaning of all checkout areas to force an update from CVS.
+
|-
+
| skipTests
+
| This is only found in the tests component and will prevent the execution of unit tests following the build and packaging steps.
+
|-
+
|  Map build.cfg |
+
|-
+
| TODO:
+
| The properties found here are presently self-explanatory and largely to be unnecessary as most information can be gotten from feature.xml files (as is planned for future versions of the build process).
+
|}
+
 
+
==Project Structure==
+
The CVS structure for GMF organizes the project by plug-ins, features, tests, etc., as seen below:
+
{|  width="100%" border="0"
+
|  colspan="6" | <strong>/cvsroot/technology</strong>
+
|  width="62%" | CVS ROOT (dev.eclipse.org)
+
|-
+
|  width="2%" | &nbsp;
+
|  colspan="5" bordercolor="0" | <strong>/org.eclipse.gmf</strong>
+
| Graphical Modeling Framework subproject
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/contributions</strong>
+
| GMF code contributions
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/doc</strong>
+
| Project documentation
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/examples</strong>
+
| GMF examples
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/features</strong>
+
| GMF features
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/plugins</strong>
+
| GMF plugins
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/releng</strong>
+
| Build procedure scripts, update site, etc.
+
|-
+
| &nbsp;
+
|  width="3%" bordercolor="0" | &nbsp;
+
|  colspan="4" | <strong>/tests</strong>
+
| GMF unit tests
+
|}
+
 
+
==Executing the tests==
+
This section describes the process for executing the unit tests packaged in the GMF test component. The tests are normally installed and executed as part of the build process, while these instructions are intended for those who wish to invoke the tests after installed in their local environment.
+
* <b>Install the prerequisites</b>: The GMF unit tests require a few dependencies to be installed prior to execution. These are all available or listed on the GMF download page. Presently, you will need to install the GMF SDK and Examples, along with the UML2 project runtime component, in addition to their dependencies.
+
* <b>Setting the test properties</b>: Modify the properties found at the top of the main test.xml file to match your configuration. This file is found in the org.eclipse.gmf.tests.source_X.X.X folder under the plugins directory of your Eclipse installation.
+
* <b>Running the tests</b>: From the org.eclipse.gmf.tests.source_X.X.X folder in the plugins directory of your Eclipse installation, you will need to invoke Ant and pass in the test.xml as the build script file (-f option). When complete, a /testresults/html folder will contain the test output.
+
 
+
==Developer information==
+
This section outlines some of the procedures and practices for GMF developers to maintain a smooth build/test environment. In particular, information on using the releng tool and how to add a plug-in to the build is covered.
+
* <b>Adding or removing a plug-in</b>: As the build depends on features remaining accurate, be sure to update the feature.xml for listed plug-ins and also check the 'Dependencies' list, using the Compute feature of the PDE if desired. You will also need to update the appropriate map file(s) to indicate the changes to plug-ins and their location in the repository. Alternatively, email the developer mailing list with changes requested and let the maintainer of the build effect the change.
+
* <b>Adding a test plug-in</b>: Each test plug-in needs to have a corresponding test.xml file in order to be run as part of the build. See existing test.xml files for an example. Be sure to appropriately choose either 'ui-test' or 'core-test' for the target within this file. Information on what these mean is found in the [ftp://download.eclipse.org/R-3.0.2-200503110845/testframework.html readme] for the testing framework. Finally, each test plug-in is listed for execution in the test.xml file found in the sourceTemplatePlugin directory of org.eclipse.gmf.tests-feature. You will need to add your new test plug-in to this list.
+
 
+
==Gotchas==
+
The build process is fairly complex, and will hopefully improve with more being generated/automated. A few things to watch out for are listed below:
+
* If the build stops during the fetch with an error message telling you to check your map files, open the generated fetch_*.xml file in your component build directory. If it is cutoff (malformed), check your CVS connection, as it is likely the cause.
+
* If you are running a build and get the message that 'plug-in org.*_X_X_X' cannot be found, check that you have declared/installed the necessary dependencies for the plug-in.
+
* If you are building a feature that contains a generate.* option in its build.properties file, and you are getting '.../build.xml file does not exist' messages, check that your plug-ins do not contain any cyclic dependencies. Specifically, look at any fragments you may have to see if they have their host plug-in listed as a dependency.
+

Latest revision as of 12:31, 5 October 2011

This page is no more accurrate.

See Common Build Infrastructure