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 "Orion/Releng Builds"

(Architecture)
(JavaScript tests)
Line 124: Line 124:
 
Sauce Labs uses its browser farm to load each test page's URL in turn and execute the tests. Each test page must use the [[#Mocha–Sauce Labs integration|Mocha–Sauce wrapper]] in order to correctly call back to Sauce at this step. The test pages return xUnit reports to Sauce showing passes and failures. Those reports are then echoed back to the test runner app, which collects them.
 
Sauce Labs uses its browser farm to load each test page's URL in turn and execute the tests. Each test page must use the [[#Mocha–Sauce Labs integration|Mocha–Sauce wrapper]] in order to correctly call back to Sauce at this step. The test pages return xUnit reports to Sauce showing passes and failures. Those reports are then echoed back to the test runner app, which collects them.
  
When all tests have finished, the runner enters a dormant state. In this state, any requests to <tt>https://{test_runner_url}/testresults</tt> will return a zip of all the test results. The build grabs the results, unzips them, and finishes. (To be precise, the build opens a connection to <tt>/testresults</tt> immediately after deploying the test app. That connection remains open until the test runner app has all the test results, at which time it sends the zip and closes the connection.)
+
When all tests have finished, the runner enters a dormant state. In this state, any requests to <tt>https://{test_runner_url}/testresults</tt> will return a zip of all the test results. The build grabs the results, unzips them, and finishes.
  
 
==== Maven setup ====
 
==== Maven setup ====

Revision as of 14:52, 2 June 2014

Orion currently has 3 kinds of builds:

How to contribute

This section applies to all builds.

Contributing changes to the build

Contributing to a build is easy: just commit your code to the master stream of the Orion repository and it will be included in the next integration build.

Setting up your workspace

  1. See Orion/Getting the source for instructions on how to set up your workspace to work with Orion source code.

Contributing your changes

Once you have made code changes, you can contribute them to the Integration build as follows:

  • Commit your changes to the local repository and push them to the master
git commit -a -m "fix lots of bugs"                   #commits all changes
git push                                              #push local commits to the master

Minification

The Orion build performs optimization of client pages and plugins using RequireJS. Note the distinction between concatenation (inlining a module's AMD dependencies to reduce HTTP overhead) and minification (shrinking a module's JavaScript code size by removing whitespace). The build minifies all JavaScript code automatically, but getting your module concatenated requires an extra step. This section has instructions on how to add new content for concatenation in the build.

Adding a new module to the optimization

To add a new page or plugin for concatenation, you must update this file: releng/org.eclipse.orion.client.releng/builder/scripts/orion.build.js Find the property modules, and add an entry for your page/plugin.

Every entry needs a name property giving the module's web path. For example, here is the Git Commit page's entry:

    { name: "git/git-commit" },

The Tycho and Node builds all share orion.build.js, so your new module will be correctly built everywhere.

Adding a new client bundle to the JS build

  1. Add an entry to the bundles section of orion.build.js. (Ant-style property replacement is supported within the bundles entry, but ${orionClient} is the only property you should use there.)
  2. If your bundle contains any JSDocs, add an entry to the jsdocs section of orion.build.js.
  3. For each of the bundle's modules you want to optimize, add an entry to the modules section of orion.build.js. (see previous section).
  4. Add a pom.xml file in the root folder of your bundle.
  5. Add an entry to the <modules> section of the client repo's top-level pom.xml. This ensures that the Maven builder finds your bundle.
  6. Update the selfHostingRules.js file by adding an entry for the new bundle. This is required for your bundle's resources to be accessible when self-hosting Orion.

Building stand-alone features

Orion pages and plugins are handled by a multi-module invocation of r.js that optimizes all of them in one shot. However, stand-alone features need different build config options, which means r.js must be invoked separately for each of these features.

To build a stand-alone feature, you must add logic to the requirejs task in the Ant script orion.mini.xml. You must invoke r.js, passing the build file for your feature. Here is an example showing how a file used for the standalone Orion editor is minified:

  1.  <!-- Clean widget output directory -->
  2.  <target name="widgetClean" depends="widget.check" if="widget.run">
  3.     <delete dir="${widgetOutDirectory}" />
  4.     <mkdir dir="${widgetOutDirectory}" />
  5.  
  6.     <copy file="${builder}/scripts/editor.build-js.js" tofile="${staging}/editor.build-js.js" overwrite="true"/>
  7.     <!-- ... -->
  8.  </target>
  9.  
  10.  <target name="requirejs" depends="checkDirs, cleanStaging, cleanOptimized">
  11.      <!-- ... -->
  12.  
  13.      <!-- build standalone editor (unless skipEditor is set) -->
  14.      <antcall target="editorOptimize">
  15.          <param name="staging" value="${staging}" />
  16.          <param name="out" value="${widgetOutDirectory}" />
  17.      </antcall>
  18.  
  19.      <!-- ... -->
  20.  </target>
  21.  
  22.  <target name="editorOptimize" unless="skipEditor">
  23.      <sequential>
  24.          <!-- Invoke r.js -->
  25.          <widgetOptimizeFile
  26.             out="${out}/built-editor-amd.min.js"
  27.             buildfile="${staging}/editor.build-js.js"
  28.             optimize="closure"
  29.             staging="${staging}" />
  30.  
  31.          <!-- Additional calls to r.js can be placed here, if needed -->
  32.      </sequential>
  33.  </target>

Deploying builds to orion.eclipse.org or orionhub.org

Builds are deployed using the script deploy.sh. This script should be copied to your home directory and run from there. Your home directory will contain a symlink to the downloads directory, so you can perform a deploy directly from the downloads area. The script takes a single argument which is the location of the zip containing the download. For our servers we want the Linux 64-bit build. It is useful to log the output of this script so it can be reviewed later. Example:

./deploy.sh -archive downloads/orion/drops/I201201102230/eclipse-orion-I20120110-2230-linux.gtk.x86_64.zip >> deploy.log

This script simply copies the build onto the deployment server, and invokes an upgrade script on that server - upgrade.sh. The upgrade script shuts down the old server, moves it, unzips and configures the new build, and finally starts it.

The entire deploy/upgrade process takes about 5 seconds when it runs smoothly. Occasionally there will be a communication error copying the new build onto the target machine. In this case simply re-running the script usually succeeds.

Server configuration

The server configuration file on orion.eclipse.org and orionhub.org is found in ~admin/current/orion.conf. This file gets copied into the server by the deployment script. So, any change made to this configuration file will take effect only on the next deployment.


Tycho build

The Tycho builds use the Eclipse Tycho infrastructure (Category:Tycho), centered around Maven. Orion committers can manage Tycho builds using the Orion Hudson instance. The build comprises 2 jobs:

orion-client

Builds Orion's client-side JavaScript code and performs JS minification. JavaScript tests are optionally executed (requires Sauce Labs and Cloud Foundry).

orion-server

Downstream project of orion-client. Builds Orion's Java server and runs Java tests.

JavaScript tests

For good coverage of client-side JS unit tests, it is desirable to run the tests under various web browsers. Older Orion builds used shell scripts to capture versions of Chromium and Firefox installed on the build.eclipse.org machine, then ran tests with js-test-driver. Keeping those browsers working and up-to-date was a frequent source of problems, and also meant the tests could never run outside the build.eclipse.org environment.

As of May 2014, unit tests in the orion-client Hudson job now execute in the Sauce Labs cloud which provides testing under various browser+OS platforms.

Architecture

The pom file responsible for managing the tests is releng/org.eclipse.orion.client.releng/pom.xml.

For Sauce Labs to run our tests, Orion's test code must be hosted on a web server that is accessible by the Sauce Labs cloud. Sauce Labs does provide a tunnel solution for testing code behind a firewall, but it does not work behind a proxy, which makes it unsuitable for Eclipse's Hudson environment.

For this reason, the test code is hosted on an external server that the build dynamically deploys to. The POM starts off by deploying a small test runner application to a Cloud Foundry environment (see Gruntfile.js for the test runner source.) The test runner is responsible for hosting the Orion client code as a web server, and invoking the Sauce Labs API to kick off the tests.

Sauce Labs uses its browser farm to load each test page's URL in turn and execute the tests. Each test page must use the Mocha–Sauce wrapper in order to correctly call back to Sauce at this step. The test pages return xUnit reports to Sauce showing passes and failures. Those reports are then echoed back to the test runner app, which collects them.

When all tests have finished, the runner enters a dormant state. In this state, any requests to https://{test_runner_url}/testresults will return a zip of all the test results. The build grabs the results, unzips them, and finishes.

Maven setup

To run the tests, Maven must be configured with a settings.xml file that contains the secret CF and Sauce authentication credentials. It should look something like this:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>orion-test-server</id>
            <username>[Cloud Foundry username]</username>
            <password>[Cloud Foundry password]</password>
        </server>
    </servers>
    <profiles>
        <profile>
            <id>orion-test</id>
            <properties>
                <SAUCE_USERNAME>[Sauce Labs username]</SAUCE_USERNAME>
                <SAUCE_ACCESS_KEY>[Sauce Labs Access Key]</SAUCE_ACCESS_KEY>
            </properties>
        </profile>
    </profiles>
</settings>

Additionally, some CF-related properties must be passed to Maven. This picture shows the required properties. Your values for these settings will differ according to the CF platform you're using. Note also that the profile orion-test must be set, otherwise the tests will not run.

Orion-test-maven-properties.png

Mocha–Sauce Labs integration

Orion has a Sauce-enabled Mocha wrapper (sauce.js) which all mocha test pages must load. The wrapper has 2 jobs:

  • Generate an xUnit report in addition to the regular HTML output displayed on the test page. The xUnit report is later downloaded by Hudson, and used to power the test results view on the build pages.
  • Compress the xUnit report. Sauce Labs has a 64KB limit on the request size returned from a browser. Because the xUnit output often exceeds 64KB, the Sauce wrapper compresses the output before sending it. The test runner application expands the output again when it obtains the test results from Sauce Labs.

Node build

The Node build is a Grunt script that produces a self-contained, Node.js-based Orion server with optimized client-side JavaScript code.

The script runs automatically before Orion is published to the npm repository, but it can be run manually as well. The Orion dev team publishes builds on a regular basis, at least once per milestone.

Running the Node build script

First, you should also install grunt globally:

npm install -g grunt

Then ensure you have the dev dependencies the Orion Node server needs:

$ cd modules/orionode
$ npm install

To run the build, simply run grunt from the orionode folder:

$ cd modules/orionode
$ grunt

< lots of output >

Done, without errors.
$ 

When the script finishes, modules/orionode contains a complete optimized server suitable for publishing to npm. Running node server.js as normal will launch the optimized server.

To produce a standalone optimized tarball of Orion, use the npm pack command:

$ npm pack

> orion@0.0.27 prepublish .
> grunt

< lots of output >

Done, without errors.
orion-0.0.27.tgz
$

How it works

The script copies all the client code from the top-level bundles/ folder of the Orion client repo into modules/orionode/orion.client/bundles. The code is then "staged" (i.e. the runtime web-path structure is recreated on disk) to a temp directory, and RequireJS optimization is performed. After optimization, minified code and source maps are copied back into the bundle folders that they originated from. The end result is a self-contained directory.

To build a customized Orion server, edit Gruntfile.js. You can supply an alternative path to the Orion client code, or a different RequireJS build configuration (take care to maintain the Orion "shape", however: for example your build config must have a bundles property).

Publishing to npm (for package maintainers)

There's a publish.sh script that performs a build and then publishes to the npm package repository if the build succeeded. You must be a maintainer of the orion package to publish, contact @kwalker or @mamacdon if you need access.

$ ./publish.sh
<lots of grunt output>
<lots of npm output>

Back to the top