AppSuite:UI build system: Difference between revisions

From Open-Xchange
(Undo revision 22287 by Khgras (talk))
 
(56 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Stability-deprecated}}
<div class="title">Build System</div>
<div class="title">Build System</div>


'''Abstract:''' This document describes the build system of OX App Suite. It is intended for app developers who use the build system to create apps as well as for OX App Suite developers who not only use the build system but also may wish to extend it.
'''Abstract:''' This document describes the build system of OX App Suite. It is intended for app developers who use the build system to create apps as well as for OX App Suite developers who not only use the build system but also may wish to extend it.
== Introduction ==


The build system is used to create source archives from source files. These source archives can be used to compile installable packages for various Linux distributions. The build system can generate archives for the core UI as well as for independently installed apps.
The build system is used to create source archives from source files. These source archives can be used to compile installable packages for various Linux distributions. The build system can generate archives for the core UI as well as for independently installed apps.


The OX App Suite build system uses Jake, a port of Rake from Ruby to Node.js. Both Rake and Jake are dependency-based build systems like Make, which allows quick incremental builds. But unlike Make, Jake doesn't have its own syntax. Instead, it provides an API in JavaScript. The API is used not only to specify dependencies between files using a full programming language, but also to implement the generation of files in the same language. This allows easy implementation of complex build systems, of which the OX App Suite build system is an example. Using the same language for the developed project and for its build system also allows any core developer to quickly extend the build system without having to switch to another language.
The OX App Suite build system uses [https://github.com/mde/jake Jake], a port of Rake from Ruby to [http://nodejs.org Node.js]. Both Rake and Jake are dependency-based build systems like Make, which allows quick incremental builds. But unlike Make, Jake doesn't have its own syntax. Instead, it provides an API in JavaScript. The API is used not only to specify dependencies between files using a full programming language, but also to implement the generation of files in the same language. This allows easy implementation of complex build systems, of which the OX App Suite build system is an example. Using the same language for the developed project and for its build system also allows any core developer to quickly extend the build system without having to switch to another language.


== Using the Build System ==
== Using the Build System ==
Line 17: Line 17:
== Installing ==
== Installing ==


The build system comes in two variants: as part of the OX App Suite source, and as a Software Development Kit (SDK). The SDK contains only the build system and can be installed as a package. Its only external dependency is Node.js, which should be installed automatically by your package manager. While the core of OX App Suite is supposed to be built using the included version of the build system, both the source and the SDK can be used to build external (i.e. independently installable) apps.
Installing the right environment for running the <code>appserver</code> and the UI build system is described in [[AppSuite:GettingStarted#Installing | the getting started article]].
 
== Running ==
 
The build system is executed by invoking the command <code>build-appsuite</code>. Similar to most build systems, the build system can perform multiple tasks, which are specified as parameters on the command line. Each task can require any number of parameters. These parameters can be specified either on the command line, using the syntax <code>name=value</code>, or as environment variables.
 
If present, the file <code>local.conf</code> is sourced by a shell script before the build process starts. This file can export environment variables which are specific to the local system, without checking them into a version control system. Typically, it defines values for <code>[[#builddir|builddir]]</code> and <code>[[#debug|debug]]</code>.
 
Since the build system is based on Jake, it also accepts all other Jake options. In addition, the environment variable <code>$nodeopts</code> can be used to pass command line parameters to Node.js. One of the most useful parameters is <code>--debug-brk</code>, which can be used to debug the build system.
 
When developing external apps, the build system must be run from the top directory of the app's source. As a safety precaution, execution is aborted if the subdirectory <code>apps</code>, which usually contains JavaScript source code, is not found. This Article is written assuming, you're working in your workspace directory, containing the subfolder <code>apps</code>.
 
== Workflow ==
 
The build system is used not only to create source archives for packaging. It can also directly install and update the built UI in a directory during development, help with the setup of the source of a new external app and more. While all of these tasks are described in the reference section, daily work involves just a few of them.
 
To have an easy example about how to [[AppSuite:GettingStarted#Writing | write]], [[AppSuite:GettingStarted#Building | build]] & [[AppSuite:GettingStarted#Running | host]] your javascript code and how to [[AppSuite:GettingStarted#Initialization | initialize]] & [[AppSuite:GettingStarted#Building_Packages | build]] your packages, please have a look at the [[AppSuite:GettingStarted | GettingStarted article]].
 
==== JSHINT ====
 
One step of the build process is running jshint to statically analyse the sources for certain errors. JSHint is configured with (what we think) sane defaults, but if you want to configure your own rules, edit <code>.jshintrc</code> in your project`s root folder, according to your needs.
 
=== default ===
 
The default task is used instead of the app task when building the core OX App Suite. Since it is the default Jake task, it is not necessary to specify it on the command line when it's the only task.
 
The top directory of OX App Suite source code includes the script <code>build.sh</code>, which should be used instead of calling a potentially unrelated version of <code>build-appsuite</code>. The script changes the current directory to its own, so that it can be called from any directory.
 
  $ web/ui/build.sh
 
=== clean ===
 
The build system uses dependencies and file timestamps to decide which files to rebuild. This assumes that any change to a file increases its timestamp to a value which is greater than the timestamp of any existing file. When this assumption is violated (e.g. after switching to a different source control branch with older files) it may become necessary to rebuild everything to restore the assumption about timestamps. The simplest way to achieve this is the clean task, which simply deletes all generated files.
 
WARNING: This can be potentially dangerous, since the clean task simply deletes the directories specified by the variables builddir, destDir, l10nDir, manifestDir, and helpDir.
 
=== dist ===
 
When the app is ready to be shipped, or rather all the time on a continuous build system, the app needs to be packaged in a format suitable for installation on a production system. Since there already exist tools to create packages from suitably arranged source code archives, the OX App Suite build system merely prepares such source archives.
 
The dist task creates an archive with the source (the one ending in .orig.tar.bz2) and a few additional files necessary for Debian packaging. RPM packages can be generated using the same source archive and the .spec file created by init-packaging. The version of the package is extracted from the newest entry in the file debian/changelog.
 
Debian packages can also be generated manually either from the temporary directory left behind by dist, or even directly from the source tree. The second option pollutes the source tree with generated files, so it is not recommended, although the .gitignore file created by init-packaging can handle these generated files.
 
  $ build-appsuite dist
  $ ls tmp/packaging/
  example-app-0.0.1                  example-app_0.0.1-1.dsc
  example-app_0.0.1-1.debian.tar.bz2  example-app_0.0.1.orig.tar.bz2
  $ cd tmp/packaging/example-app-0.0.1/
  $ dpkg-buildpackage -b
 
== Reference ==


The actual installation depends on the chosen variant:
=== Variables ===


=== SDK ===
==== BASEDIR ====
The top directory of the build system.


First, if not already done, add the Open-Xchange repository to the list of Apt sources.
<b>Used by:</b> all tasks.


  # echo deb http://software.open-xchange.com/products/appsuite/\
<b>Default:</b> installation directory of the build system
  stable/appsuiteui/DebianSqueeze/ / >> /etc/apt/sources.list.d/ox.list
  # aptitude update
Then, the actual installation is a single command.


  # aptitude install open-xchange-appsuite-dev
Required to build external apps, since in this case, the build
Finally, the main executable of the build system should be put in the executable path for easier calling. This is typically done by either extending the $PATH environment variable
system is not installed in the current directory. This variable is
automatically set as an environment variable by the build system
executable based on <code>$OX_APPSUITE_DEV</code>.


  $ export PATH=$PATH:/opt/open-xchange-appsuite-dev/bin
==== branch ====
or copying or symlinking the binary to a directory already in the path.
The Subversion branch of the CLDR to checkout.


  # ln -s /opt/open-xchange-appsuite-dev/bin/build-appsuite /usr/local/bin
<b>Used by:</b> <code>update-i18n</code>.


=== Source ===
==== builddir ====
The target directory for generated files.


Using the source variant can avoid the requirement for root permissions. But, when building external apps and the build system executable is not invoked using its full path, the environment variable $OX_APPSUITE_DEV needs to be set to specify the path to the build system.
<b>Used by:</b> <code>app</code>, <code>clean</code>,
<code>default</code>, <code>dist</code>, <code>docs</code>,
<code>jakedeps</code>.


  $ git clone https://git.open-xchange.com/git/wd/frontend/web
Default: <code>build</code>
  $ export OX_APPSUITE_DEV=$(pwd)/web/ui
Just like with the SDK variant, the executable should be put in the executable path either by extending the $PATH variable


  $ export PATH=$PATH:$OX_APPSUITE_DEV/bin
==== copyright ====
or by copying or symlinking the executable.
The copyright line to be included in packaging metadata.


  # ln -s $OX_APPSUITE_DEV/bin/build-appsuite /usr/local/bin
<b>Used by:</b> <code>[[#init-packaging|init-packaging]]</code>.


== Running ==
<b>Example:</b> <code>2012 Open-Xchange, Inc</code>
 
==== coreDir ====
Location of OX App Suite UI files.
 
<b>Used by:</b> <code>[[#app|app]]</code>, <code>[[#default|default]]</code>.
 
<b>Default:</b> same as <code>[[#builddir|builddir]]</code>
 
Some tasks depend on installed files from the OX App Suite. When building external apps, <code>[[#coreDir|coreDir]]</code> specified the directory which contains these files.
 
Currently, this parameter is used to compile <code>.less</code> files for every installed theme. This can be disabled by setting <code>[[#skipLess|skipLess]]</code>.
 
==== debug ====
Enables a debug build.
 
<b>Used by:</b> <code>app</code>, <code>default</code>.
 
<b>Default:</b> <code>false</code>
 
To simplify debugging of OX App Suite, compression of source code
can be disabled by specifying <code>on</code>, <code>yes</code>,
<code>true</code> or <code>1</code>.
 
==== description ====
<b>Used by:</b> <code>init-packaging</code>.
 
The description of the app to be included in packaging metadata.
 
==== destDir ====
Output directory for source archives created by
the <code>dist</code> task.
 
<b>Used by:</b> <code>clean</code>, <code>dist</code>.
 
<b>Default:</b> <code>tmp/packaging</code>
 
==== disableStrictMode ====
Removes all <code>"use strict"</code> directives from processed
JavaScript code.
 
<b>Used by:</b> <code>app</code>, <code>default</code>.
 
<b>Default:</b> <code>false</code>
 
Some debugging tools which use code instrumentation have problems
when the debugged code uses strict mode. This setting enables code
processing even whe using <code>debug</code> mode, so line numbers
will not match the original source code.
 
==== forceDeb ====
Whether an error during the generation of Debian source packages is an error.
 
<b>Used by:</b> <code>dist</code>.
 
<b>Default:</b> <code>false</code>
 
This is useful when Debian packages are generated automatically, and a failure of <code>dpkg-source</code> is also a failure of the entire build. By default it merely produces a warning.
 
==== from ====
The root of the printed dependency tree between Jake tasks.
 
<b>Used by:</b> <code>jakedeps</code>.
 
==== helpDir ====
The location of online help files.
 
<b>Used by:</b> <code>clean</code>, <code>default</code>,
<code>dist</code>.
 
<b>Default:</b> same as <code>builddir</code>
 
If the value contains the string <code>@lang@</code>, it will be
replaced by the lowercase language code (e.g. <code>en-us</code>) to
allow per-language directories.
 
==== l10nDir ====
The location of compiled l10n files.
 
<b>Used by:</b> <code>app</code>, <code>clean</code>,
<code>default</code>, <code>dist</code>.
 
<b>Default:</b> same as <code>builddir</code>
 
If the value contains the string <code>@lang@</code>, it will be
replaced by the lowercase language code (e.g. <code>en-us</code>) to
allow per-language directories.
 
==== license ====
File name of the full text of the distribution license.
 
<b>Used by:</b> <code>init-packaging</code>.
 
<b>Default:</b> based on <code>licenseName</code>.
 
==== licenseName ====
Name of the distribution license to be included in packaging
metadata.
 
<b>Used by:</b> <code>init-packaging</code>.
 
<b>Default:</b> <code>CC-BY-NC-SA-3.0</code>
 
==== manifestDir ====
The location of the combined manifest file.
 
<b>Used by:</b> <code>app</code>, <code>clean</code>,
<code>default</code>, <code>dist</code>.
 
<b>Default:</b> same as <code>builddir</code>
 
==== maintainer ====
Name and email address of the package maintainer.


The build system is executed by invoking the command build-appsuite. Similar to most build systems, the build system can perform multiple tasks, which are specified as parameters on the command line. Each task can require any number of parameters. These parameters can be specified either on the command line, using the syntax name=value, or as environment variables.
<b>Used by:</b> <code>init-packaging</code>.


If present, the file local.conf is sourced by a shell script before the build process starts. This file can export environment variables which are specific to the local system, without checking them into a version control system. Typically, it defines values for builddir and debug.
<b>Format:</b> <code><var>Name</var> &lt;<var>email</var>&gt;</code>


Since the build system is based on Jake, it also accepts all other Jake options. In addition, the environment variable $nodeopts can be used to pass command line parameters to Node.js. One of the most useful parameters is --debug-brk, which can be used to debug the build system.
==== package ====
The name of the package for the built app.


When developing external apps, the build system must be run from the top directory of the app's source. As a safety precaution, execution is aborted if the subdirectory apps, which usually contains JavaScript source code, is not found.
<b>Used by:</b> all tasks.


== Workflow ==
<b>Default:</b> the package name in the first line of
<code>debian/changelog</code>


The build system is used not only to create source archives for packaging. It can also directly install and update the built UI in a directory during development, help with the setup of the source of a new external app and more. While all of these tasks are described in the reference section, daily work involves just a few of them.
Since the name of the manifest file contains the package name and it
is required to determine build dependencies, the package name must
be always known. This means either <code>debian/changelog</code>
must exist and contain at least one entry, or the parameter must be
explicitly specified.


=== init-packaging ===
==== reverse ====
Reverses the direction of printed dependencies.


The first task which should be executed when creating a new external app is init-packaging. It creates packaging metadata in the current directory. It requires the parameter package to specify the package name in the generated files. All subsequent tasks will automatically extract the package name from the files generated by init-packaging.
<b>Used by:</b> <code>deps</code>.


Before execution, the apps subdirectory must be created. It indicates that the current directory is actually a valid source directory.
When specified, the <code>deps</code> task prints modules which
depend on the specified modules, instead of modules on which
the specified module depends.


  $ mkdir apps
==== revision ====
  $ build-appsuite init-packaging package=example-app
Revision number of the package for the app.
  Build path: build
  Build version: 7.0.0-1.20130111.105125
 
  Version [7.0.0]: 0.0.1
 
  Maintainer (Name <e-mail>): Maintainer <maintainer@example.com>
 
  Copyright line [2013 Open-Xchange, Inc]:
 
  License name [CC-BY-NC-SA-3.0]:


'''Short description:''' Hello World app to demonstrate usage of the build system
<b>Used by:</b> <code>app</code>, <code>default</code>,
The task presents a number of interactive prompts to get the necessary information about the generated packages. The entered values should follow the Debian Maintainer's Guide. Some or even all prompts can be skipped by explicitly specifying the information as a build variable. The list of variable names is available in the reference of init-packaging.
<code>dist</code>.


After the task is finished, the generated files can be customized manually to account for any additional packaging requirements.
<b>Default:</b> <code>1</code>


=== app ===
The revision number must increase with each rebuild of the same
version to enable the creation of unique version strings. These are
required in package names and to control content caching in clients.


The main workhorse task is ''app''. It is used to process all source files to an optimized deployable app. During development, it is usually called automatically by an IDE or a directory monitoring tool. Since the builds are incremental, the task can be called after every source modification.
==== root ====
Specifies for which module to print the dependencies.


For quickest roundtrip times, the directory with the generated files of the app should be made available through the OX App Suite back end by overlaying an existing OX App Suite installation, for example, by symlinking it.
<b>Used by:</b> <code>deps</code>.


  # ln -s $(readlink -m build/apps/com.example) \
<b>Default:</b> print all roots
  /opt/open-xchange/appsuite/apps/com.example
To make the manifest accessible to the backend, it should be symlinked into the directory specified by the com.openexchange.apps.manifestPath setting (from manifests.properties) of a locally installed OX App Suite backend.


  # ln -s $(readlink -m build/manifests/example-app.json) \
If specified, only the dependencies of the specified module are
  /opt/open-xchange/appsuite/manifests/example-app.json
printed. Otherwise, the dependencies of all modules are printed.
Now, any changes can be tested by reloading OX App Suite in the browser, and any changes in the app manifest can be applied by restarting the backend.


WARNING: Do not use build variables builddir or manifestDir when developing an external app to generate the files directly in their final destination! The clean task will delete these directories and all their contents! In general, don't point builddir or any other *Dir variables at existing directories.
==== skipDeb ====
Whether to skip the generation of Debian source packages.


As an example, let's create a small app and build it. It requires only two files: apps/com.example/main.js for the source code of the app
<b>Used by:</b> <code>dist</code>.


<pre class="language-javascript">  
<b>Default:</b> <code>false</code>
define('com.example/main', function () {
  'use strict';
  var app = ox.ui.createApp({ name: 'com.example' });
  app.setLauncher(function () {
    var win = ox.ui.createWindow({
      name: 'com.example',
      title: 'Hello World App'
    });
    app.setWindow(win);
    win.nodes.main.append($('<h1>').text('Hello, World!'));
    win.show();
  });
  return { getApp: app.getInstance };
});
</pre>
and apps/com.example/manifest.json for the manifest:
  { title: 'Hello World App' }


Building the app is as easy as calling
This is useful when Debian packages are not required and/or
  $ build-appsuite app
<code>dpkg-source</code> is not available, e.g. on RPM based
systems.


=== default ===
Even when using this flag, at least the file
<code>debian/changelog</code> is still required, because it is used
to store the package name and version.


The default task is used instead of the app task when building the core OX App Suite. Since it is the default Jake task, it is not necessary to specify it on the command line when it's the only task.
==== skipLess ====
Whether to skip the preprocessing of LessCSS files.


The top directory of OX App Suite source code includes the script build.sh, which should be used instead of calling a potentially unrelated version of build-appsuite. The script changes the current directory to its own, so that it can be called from any directory. Furthermore, it sets BASEDIR, so that $OX_APPSUITE_DIR is neither used nor necessary.
<b>Used by:</b> <code>app</code>, <code>default</code>.


  $ ./build.sh
<b>Default:</b> <code>false</code>
  clean


The build system uses dependencies and file timestamps to decide which files to rebuild. This assumes that any change to a file increases its timestamp to a value which is greater than the timestamp of any existing file. When this assumption is violated (e.g. after switching to a different source control branch with older files) it may become necessary to rebuild everything to restore the assumption about timestamps. The simplest way to achieve this is the clean task, which simply deletes all generated files.
This flag skips the generation of CSS files in
the <code>apps/themes/*/less</code> directories of all themes.
It is used by the packaging system, where the LessCSS files are
precompiled after installation on the target system instead of
while building the package.


WARNING: This can be potentially dangerous, since the clean task simply deletes the directories specified by the variables builddir, destDir, l10nDir, manifestDir, and helpDir.
==== tag ====
The Subversion tag of the CLDR to checkout.


=== dist ===
<b>Used by:</b> <code>update-i18n</code>.


When the app is ready to be shipped, or rather all the time on a continuous build system, the app needs to be packaged in a format suitable for installation on a production system. Since there already exist tools to create packages from suitably arranged source code archives, the OX App Suite build system merely prepares such source archives.
==== to ====
The leaf task in the printed dependency path between Jake tasks.


The dist task creates an archive with the source (the one ending in .orig.tar.bz2) and a few additional files necessary for Debian packaging. RPM packages can be generated using the same source archive and the .spec file created by init-packaging. The version of the package is extracted from the newest entry in the file debian/changelog.
<b>Used by:</b> <code>jakedeps</code>.


Debian packages can also be generated manually either from the temporary directory left behind by dist, or even directly from the source tree. The second option pollutes the source tree with generated files, so it is not recommended, although the .gitignore file created by init-packaging can handle these generated files.
When specified, only a single path from the root to the leaf task is
printed (in reverse order).


  $ build-appsuite dist
==== version ====
  $ ls tmp/packaging/
Version number of the app.
  example-app-0.0.1                  example-app_0.0.1-1.dsc
  example-app_0.0.1-1.debian.tar.bz2  example-app_0.0.1.orig.tar.bz2
  $ cd tmp/packaging/example-app-0.0.1/
  $ dpkg-buildpackage -b


== Reference ==
<b>Used by:</b> <code>app</code>, <code>default</code>,
<code>dist</code>, <code>init-packaging</code>.


=== Variables ===
<b>Default:</b> <code>0.0.1</code>


<dl>
The version should consist of a major, minor and patch version
    <dt>BASEDIR</dt>
separated by dots.
    <dd>
        <p>The top directory of the build system.</p>
        <p><b>Used by:</b> all tasks.</p>
        <p><b>Default:</b> installation directory of the build system</p>
        <p>
            Required to build external apps, since in this case, the build
            system is not installed in the current directory. This variable is
            automatically set as an environment variable by the build system
            executable based on <code>$OX_APPSUITE_DEV</code>.
        </p>
    </dd>
</dl>
<dl>
    <dt>branch</dt>
    <dd>
        <p>The Subversion branch of the CLDR to checkout.</p>
        <p><b>Used by:</b> <code>update-i18n</code>.</p>
    </dd>
</dl>
<dl>
    <dt>builddir</dt>
    <dd>
        <p>The target directory for generated files.</p>
        <p>
            <b>Used by:</b> <code>app</code>, <code>clean</code>,
            <code>default</code>, <code>dist</code>, <code>docs</code>,
            <code>jakedeps</code>.
        </p>
        <p>Default: <code>build</code></p>
    </dd>
</dl>
<dl>
    <dt>copyright</dt>
    <dd>
        <p>The copyright line to be included in packaging metadata.</p>
        <p><b>Used by:</b> <code>init-packaging</code>.</p>
        <p><b>Example:</b> <code>2012 Open-Xchange, Inc</code></p>
    </dd>
</dl>
<dl>
    <dt>debug</dt>
    <dd>
        <p>Enables a debug build.</p>
        <p><b>Used by:</b> <code>app</code>, <code>default</code>.</p>
        <p><b>Default:</b> <code>false</code></p>
        <p>
            To simplify debugging of OX App Suite, compression of source code
            can be disabled by specifying <code>on</code>, <code>yes</code>,
            <code>true</code> or <code>1</code>.
        </p>
    </dd>
</dl>
<dl>
    <dt>description</dt>
    <dd>
        <p></p>
        <p><b>Used by:</b> <code>init-packaging</code>.</p>
        <p>The description of the app to be included in packaging metadata.</p>
    </dd>
</dl>
<dl>
    <dt>destDir</dt>
    <dd>
        <p>
            Output directory for source archives created by
            the <code>dist</code> task.
        </p>
        <p><b>Used by:</b> <code>clean</code>, <code>dist</code>.</p>
        <p><b>Default:</b> <code>tmp/packaging</code></p>
    </dd>
</dl>
<dl>
    <dt>disableStrictMode</dt>
    <dd>
        <p>
            Removes all <code>"use strict"</code> directives from processed
            JavaScript code.
        </p>
        <p><b>Used by:</b> <code>app</code>, <code>default</code>.</p>
        <p><b>Default:</b> <code>false</code></p>
        <p>
            Some debugging tools which use code instrumentation have problems
            when the debugged code uses strict mode. This setting enables code
            processing even whe using <code>debug</code> mode, so line numbers
            will not match the original source code.
        </p>
    </dd>
</dl>
<dl>
    <dt>from</dt>
    <dd>
        <p>The root of the printed dependency tree between Jake tasks.</p>
        <p><b>Used by:</b> <code>jakedeps</code>.</p>
    </dd>
</dl>
<dl>
    <dt>helpDir</dt>
    <dd>
        <p>The location of online help files.</p>
        <p>
            <b>Used by:</b> <code>clean</code>, <code>default</code>,
            <code>dist</code>.
        </p>
        <p><b>Default:</b> same as <code>builddir</code></p>
        <p>
            If the value contains the string <code>@lang@</code>, it will be
            replaced by the lowercase language code (e.g. <code>en-us</code>) to
            allow per-language directories.
        </p>
    </dd>
</dl>
<dl>
    <dt>l10nDir</dt>
    <dd>
        <p>The location of compiled l10n files.</p>
        <p>
            <b>Used by:</b> <code>app</code>, <code>clean</code>,
            <code>default</code>, <code>dist</code>.
        </p>
        <p><b>Default:</b> same as <code>builddir</code></p>
        <p>
            If the value contains the string <code>@lang@</code>, it will be
            replaced by the lowercase language code (e.g. <code>en-us</code>) to
            allow per-language directories.
        </p>
    </dd>
</dl>
<dl>
    <dt>license</dt>
    <dd>
        <p>File name of the full text of the distribution license.</p>
        <p><b>Used by:</b> <code>init-packaging</code>.</p>
        <p><b>Default:</b> based on <code>licenseName</code>.</p>
    </dd>
</dl>
<dl>
    <dt>licenseName</dt>
    <dd>
        <p>
            Name of the distribution license to be included in packaging
            metadata.
        </p>
        <p><b>Used by:</b> <code>init-packaging</code>.</p>
        <p><b>Default:</b> <code>CC-BY-NC-SA-3.0</code></p>
    </dd>
</dl>
<dl>
    <dt>manifestDir</dt>
    <dd>
        <p>The location of the combined manifest file.</p>
        <p>
            <b>Used by:</b> <code>app</code>, <code>clean</code>,
            <code>default</code>, <code>dist</code>.
        </p>
        <p><b>Default:</b> same as <code>builddir</code></p>
    </dd>
</dl>
<dl>
    <dt>maintainer</dt>
    <dd>
        <p>Name and email address of the package maintainer.</p>
        <p><b>Used by:</b> <code>init-packaging</code>.</p>
        <p>
            <b>Format:</b> <code><var>Name</var> &lt;<var>email</var>&gt;</code>
        </p>
    </dd>
</dl>
<dl>
    <dt>package</dt>
    <dd>
        <p>The name of the package for the built app.</p>
        <p><b>Used by:</b> all tasks.</p>
        <p>
            <b>Default:</b> the package name in the first line of
            <code>debian/changelog</code>
        </p>
        <p>
            Since the name of the manifest file contains the package name and it
            is required to determine build dependencies, the package name must
            be always known. This means either <code>debian/changelog</code>
            must exist and contain at least one entry, or the parameter must be
            explicitly specified.
        </p>
    </dd>
</dl>
<dl>
    <dt>reverse</dt>
    <dd>
        <p>Reverses the direction of printed dependencies.</p>
        <p><b>Used by:</b> <code>deps</code>.</p>
        <p>
            When specified, the <code>deps</code> task prints modules which
            depend on the specified modules, instead of modules on which
            the specified module depends.
        </p>
    </dd>
</dl>
<dl>
    <dt>revision</dt>
    <dd>
        <p>Revision number of the package for the app.</p>
        <p>
            <b>Used by:</b> <code>app</code>, <code>default</code>,
            <code>dist</code>.
        </p>
        <p><b>Default:</b> <code>1</code></p>
        <p>
            The revision number must increase with each rebuild of the same
            version to enable the creation of unique version strings. These are
            required in package names and to control content caching in clients.
        </p>
    </dd>
</dl>
<dl>
    <dt>root</dt>
    <dd>
        <p>Specifies for which module to print the dependencies.</p>
        <p><b>Used by:</b> <code>deps</code>.</p>
        <p><b>Default:</b> print all roots</p>
        <p>
            If specified, only the dependencies of the specified module are
            printed. Otherwise, the dependencies of all modules are printed.
        </p>
    </dd>
</dl>
<dl>
    <dt>skipDeb</dt>
    <dd>
        <p>Whether to skip the generation of Debian source packages.</p>
        <p><b>Used by:</b> <code>dist</code>.</p>
        <p><b>Default:</b> <code>false</code></p>
        <p>
            This is useful when Debian packages are not required and/or
            <code>dpkg-source</code> is not available, e.g. on RPM based
            systems.
        </p>
        <p>
            Even when using this flag, at least the file
            <code>debian/changelog</code> is still required, because it is used
            to store the package name and version.
        </p>
    </dd>
</dl>
<dl>
    <dt>skipLess</dt>
    <dd>
        <p>Whether to skip the preprocessing of LessCSS files.</p>
        <p><b>Used by:</b> <code>app</code>, <code>default</code>.</p>
        <p><b>Default:</b> <code>false</code></p>
        <p>
            This flag skips the generation of CSS files in
            the <code>apps/themes/*/less</code> directories of all themes.
            It is used by the packaging system, where the LessCSS files are
            precompiled after installation on the target system instead of
            while building the package.
        </p>
    </dd>
</dl>
<dl>
    <dt>tag</dt>
    <dd>
        <p>The Subversion tag of the CLDR to checkout.</p>
        <p><b>Used by:</b> <code>update-i18n</code>.</p>
    </dd>
</dl>
<dl>
    <dt>to</dt>
    <dd>
        <p>The leaf task in the printed dependency path between Jake tasks.</p>
        <p><b>Used by:</b> <code>jakedeps</code>.</p>
        <p>
            When specified, only a single path from the root to the leaf task is
            printed (in reverse order).
        </p>
    </dd>
</dl>
<dl>
    <dt>version</dt>
    <dd>
        <p>Version number of the app.</p>
        <p>
            <b>Used by:</b> <code>app</code>, <code>default</code>,
            <code>dist</code>, <code>init-packaging</code>.
        </p>
        <p><b>Default:</b> <code>0.0.1</code></p>
        <p>
            The version should consist of a major, minor and patch version
            separated by dots.
        </p>
    </dd>
</dl>


=== Tasks ===
=== Tasks ===
<p>
<p>
An up-to-date list of tasks can be printed using the -T command line option.
An up-to-date list of tasks can be printed using the -T command line option.
</p>
 
<dl>
==== app ====
    <dt>app</dt>
Builds an external app.
    <dd>
 
        <p>Builds an external app.</p>
<b>Variables:</b> <code>[[#BASEDIR|BASEDIR]]</code>, <code>[[#builddir|builddir]]</code>, <code>[[#coreDir|coreDir]]</code>, <code>[[#debug|debug]]</code>, <code>[[#disableStrictMode|disableStrictMode]]</code>, <code>[[#l10nDir|l10nDir]]</code>, <code>[[#manifestDir|manifestDir]]</code>, <code>[[#package|package]]</code>, <code>[[#revision|revision]]</code>, <code>[[#version|version]]</code>.
        <ul class="params">
 
            <li>
This is the main task used to build external apps.
                <b>Variables:</b> <code>BASEDIR</code>, <code>builddir</code>,
 
                <code>debug</code>, <code>disableStrictMode</code>,
It works without explicitly specifying any variables, but during
                <code>l10nDir</code>, <code>manifestDir</code>,
development, <code>[[#builddir|builddir]]</code> is usually pointed to
                <code>package</code>, <code>revision</code>,
the directory of a locally installed OX App Suite UI to avoid
                <code>version</code>.
additional copying steps. For debugging, <code>[[#debug|debug]]</code> is also
            </li>
often used. Note that <code>[[#clean|clean]]</code> must be called when
        </ul>
changing any of the variables.
        <p>This is the main task used to build external apps.</p>
 
        <p>
==== clean ====
            It works without explicitly specifying any variables, but during
Removes all generated files.
            development, <code>builddir</code> is usually pointed to
 
            the directory of a locally installed OX App Suite UI to avoid
<b>Variables:</b> <code>BASEDIR</code>, <code>builddir</code>,
            additional copying steps. For debugging, <code>debug</code> is also
<code>destDir</code>, <code>l10nDir</code>,
            often used. Note that <code>clean</code> must be called when
<code>manifestDir</code>, <code>package</code>.
            changing any of the variables.
 
        </p>
This task should be executed before a normal build using
    </dd>
<code>app</code> or <code>default</code> after changing any build
</dl>
variables and after a switch between Git branches. Normal
<dl>
incremental builds can miss changed files if a branch switch
    <dt>clean</dt>
replaces files by older versions.
    <dd>
 
        <p>Removes all generated files.</p>
==== default ====
        <ul class="params">
Builds OX App Suite.
            <li>
 
                <b>Variables:</b> <code>BASEDIR</code>, <code>builddir</code>,
<b>Variables:</b> <code>[[#BASEDIR|BASEDIR]]</code>, <code>[[#builddir|builddir]]</code>, <code>[[#debug|debug]]</code>, <code>[[#disableStrictMode|disableStrictMode]]</code>, <code>[[#l10nDir|l10nDir]]</code>, <code>[[#manifestDir|manifestDir]]</code>, <code>[[#package|package]]</code>, <code>[[#revision|revision]]</code>, <code>[[#version|version]]</code>.
                <code>destDir</code>, <code>l10nDir</code>,
 
                <code>manifestDir</code>, <code>package</code>.
This is the main task to build OX App Suite. Since it is the default
            </li>
Jake task, it does not need to be specified explicitly on
        </ul>
the command line when it is the only task.
        <p>
 
            This task should be executed before a normal build using
It works without explicitly specifying any variables, but during
            <code>app</code> or <code>default</code> after changing any build
development, <code>[[#builddir|builddir]]</code> is usually pointed to
            variables and after a switch between Git branches. Normal
a directory which is accessible to a local web server. For
            incremental builds can miss changed files if a branch switch
debugging, <code>[[#debug|debug]]</code> is also often used. Note that
            replaces files by older versions.
<code>[[#clean|clean]]</code> must be called when changing any of
        </p>
the variables.
    </dd>
 
</dl>
==== deps ====
<dl>
Prints module dependencies.
    <dt>default</dt>
 
    <dd>
<b>Variables:</b> <code>BASEDIR</code>, <code>package</code>,
        <p>Builds OX App Suite.</p>
<code>reverse</code>, <code>root</code>.
        <ul class="params">
 
            <li>
This task visualizes dependencies of RequireJS modules. It prints
                <b>Variables:</b> <code>BASEDIR</code>, <code>builddir</code>,
a tree of dependencies to <code>stdout</code>.
                <code>debug</code>, <code>disableStrictMode</code>,
 
                <code>l10nDir</code>, <code>manifestDir</code>,
If <code>root</code> is specified, then only the dependencies of
                <code>package</code>, <code>revision</code>,
that module are printed. Otherwise, the dependencies of all modules,
                <code>version</code>.
on which no other module depends are printed in sequence.
            </li>
 
        </ul>
If <code>reverse</code> is specified, then this task prints
        <p>
dependants instead of dependencies, i.e. modules which depend on
            This is the main task to build OX App Suite. Since it is the default
the specified module instead of modules on which the specified
            Jake task, it does not need to be specified explicitly on
module depends.
            the command line when it is the only task.
 
        </p>
==== dist ====
        <p>
Creates source packages.
            It works without explicitly specifying any variables, but during
 
            development, <code>builddir</code> is usually pointed to
<b>Variables:</b> <code>BASEDIR</code>, <code>builddir</code>,
            a directory which is accessible to a local web server. For
<code>destDir</code>, <code>forceDeb</code>, <code>l10nDir</code>,
            debugging, <code>debug</code> is also often used. Note that
<code>manifestDir</code>, <code>package</code>,
            <code>clean</code> must be called when changing any of
<code>revision</code>, <code>skipDeb</code>,
            the variables.
<code>version</code>.
        </p>
 
    </dd>
This task cleans the source tree by calling <code>clean</code> and
</dl>
packs the source into an archive which can be used to create Debian
<dl>
and RPM packages. The necessary Debian metadata is created alongside
    <dt>deps</dt>
the source archive. All files necessary for Debian packaging are
    <dd>
placed in the directory specified by <code>destDir</code>.
        <p>Prints module dependencies.</p>
The generated <code>.orig.tar.bz2</code> archive can also be used
        <ul class="params">
together with the <code>.spec</code> file to generate RPM packages.
            <li>
 
                <b>Variables:</b> <code>BASEDIR</code>, <code>package</code>,
Unless the variable <code>skipDeb</code> is set to
                <code>reverse</code>, <code>root</code>.
<code>true</code>, the program <code>dpkg-source</code> is required
            </li>
by this task. It is used to generate Debian-specific packaging
        </ul>
metadata.
        <p>
 
            This task visualizes dependencies of RequireJS modules. It prints
==== init-packaging ====
            a tree of dependencies to <code>stdout</code>.
Initializes packaging information for a new app.
        </p>
 
        <p>
<b>Variables:</b> <code>BASEDIR</code>, <code>copyright</code>,
            If <code>root</code> is specified, then only the dependencies of
<code>description</code>, <code>license</code>,
            that module are printed. Otherwise, the dependencies of all modules,
<code>licenseName</code>, <code>maintainer</code>,
            on which no other module depends are printed in sequence.  
<code>package</code>, <code>version</code>.
        </p>
 
        <p>
This task is the first task called when starting with
            If <code>reverse</code> is specified, then this task prints
the development of a new external app. The directory from which it
            dependants instead of dependencies, i.e. modules which depend on
is called must already contain at least the <code>apps</code>
            the specified module instead of modules on which the specified
subdirectory. This is also the only task where
            module depends.
the <code>package</code> variable must be specified explicitly.
        </p>
Afterwards, the package name is looked up automatically in the file
    </dd>
<code>debian/changelog</code>, which is created by this task.
</dl>
 
<dl>
The variables <code>version</code>, <code>maintainer</code>,
    <dt>dist</dt>
<code>copyright</code>, <code>licenseName</code>,
    <dd>
<code>license</code>, and <code>description</code> are required to
        <p>Creates source packages.</p>
fill out all necessary packaging metadata. Any of these variables
        <ul class="params">
which are not specified explicitly will cause an interactive prompt.
            <li>
This avoids the need to remember the list of variables before one
                <b>Variables:</b> <code>BASEDIR</code>, <code>builddir</code>,
can start developing an app.
                <code>destDir</code>, <code>l10nDir</code>,
 
                <code>manifestDir</code>, <code>package</code>,
==== jakedeps ====
                <code>revision</code>, <code>skipDeb</code>,
Shows the dependency chain between two Jake tasks.
                <code>version</code>.
 
            </li>
<b>Variables:</b> <code>BASEDIR</code>, <code>from</code>,
        </ul>
<code>package</code>, <code>to</code>.
        <p>
 
            This task cleans the source tree by calling <code>clean</code> and
This task visualized dependencies between Jake tasks. The variable
            packs the source into an archive which can be used to create Debian
<code>from</code> specifies the root of a dependency tree, with all
            and RPM packages. The necessary Debian metadata is created alongside
dependencies of <code>from</code> as inner and leaf nodes. If
            the source archive. All files necessary for Debian packaging are
<code>to</code> is not specified, then that entire tree is printed.
            placed in the directory specified by <code>destDir</code>.
 
            The generated <code>.orig.tar.bz2</code> archive can also be used
If <code>to</code> is also specified, then only the first found
            together with the <code>.spec</code> file to generate RPM packages.
dependency path from <code>from</code> to <code>to</code> is
        </p>
.printed with <code>to</code> at the top and <code>from</code> at
        <p>
the bottom.
            Unless the variable <code>skipDeb</code> is set to
 
            <code>true</code>, the program <code>dpkg-source</code> is required
==== merge ====
            by this task. It is used to generate Debian-specific packaging
Updates all <code>.po</code> files with the generated
            metadata.
<code>ox.pot</code>.
        </p>
 
        <p>
<b>Variables:</b> <code>BASEDIR</code>, <code>builddir</code>,
            The variables <code>version</code> and <code>revision</code> specify
<code>debug</code>, <code>package</code>, <code>revision</code>,
            the version of the package which will be built from the created
<code>version</code>.
            files, and should therefore be specified explicitly.
 
        </p>
This task updates the list of extracted i18n strings in
    </dd>
<code>ox.pot</code> and calls the GNU Gettext tool
</dl>
<code>msgmerge</code> for every language in <code>i18n/*.po</code>.
<dl>
 
    <dt>docs</dt>
<code>i18n/en_US.po</code> is not updated by this task because the original strings are already in the <code>en_US</code> locale. It would only end up with every translation mapping every string to itself. The only entries in that file should be for cases when the <code>en_US</code> text is not a suitable fallback for missing translations. The original string in such a case would be something internationally appropriate (e.&nbsp;g. a date written as "2013-01-01" instead of "01/01/2013") and <code>i18n/en_US.po</code> would contain a translation.
    <dd>
 
        <p>Generates developer documentation.</p>
==== update-i18n ====
        <ul class="params">
Updates CLDR data in the source tree.
            <li>
 
                <b>Variables:</b> <code>BASEDIR</code>, <code>builddir</code>,
<b>Variables:</b> <code>BASEDIR</code>, <code>branch</code>,
                <code>package</code>.
<code>package</code>, <code>tag</code>.
            </li>
 
        </ul>
This task downloads data from the Unicode CLDR and updates date
        <p>
translations for all languages in <code>i18n/*.po</code>.
            This task generates developer documentation for OX App Suite.
 
            The generated HTML files are put into
The exact version of CLDR data is specified as Suubversion tag or
            <code>builddir</code><code>/doc</code>.
branch by the variables <code>tag</code> and <code>branch</code>,
        </p>
respectively. If neither is specified, then the Subversion trunk is
    </dd>
checked out. If both are specified, <code>tag</code> is used.
</dl>
 
<dl>
==== verify-doc ====
    <dt>init-packaging</dt>
Generates a documentation skeleton for extension points.
    <dd>
 
        <p>Initializes packaging information for a new app.</p>
<b>Variables:</b> <code>BASEDIR</code>, <code>package</code>.
        <ul class="params">
 
            <li>
This task is still under development. Currently, it creates a list of all extension points, which have a constant name in the source code. In the future it is supposed to update an existing list instead of overwriting it, and to handle non-constant extension point names.
                <b>Variables:</b> <code>BASEDIR</code>, <code>copyright</code>,
 
                <code>description</code>, <code>license</code>,
The list of extension points is stored as an HTML snippet in <code>doc/extensionpoints.html</code>.
                <code>licenseName</code>, <code>maintainer</code>,
 
                <code>package</code>, <code>version</code>.
 
            </li>
        </ul>
        <p>
            This task is the first task called when starting with
            the development of a new external app. The directory from which it
            is called must already contain at least the <code>apps</code>
            subdirectory. This is also the only task where
            the <code>package</code> variable must be specified explicitly.
            Afterwards, the package name is looked up automatically in the file
            <code>debian/changelog</code>, which is created by this task.
        </p>
        <p>
            The variables <code>version</code>, <code>maintainer</code>,
            <code>copyright</code>, <code>licenseName</code>,
            <code>license</code>, and <code>description</code> are required to
            fill out all necessary packaging metadata. Any of these variables
            which are not specified explicitly will cause an interactive prompt.
            This avoids the need to remember the list of variables before one
            can start developing an app.
        </p>
    </dd>
</dl>
<dl>
    <dt>jakedeps</dt>
    <dd>
        <p>Shows the dependency chain between two Jake tasks.</p>
        <ul class="params">
            <li>
                <b>Variables:</b> <code>BASEDIR</code>, <code>from</code>,
                <code>package</code>, <code>to</code>.
            </li>
        </ul>
        <p>
            This task visualized dependencies between Jake tasks. The variable
            <code>from</code> specifies the root of a dependency tree, with all
            dependencies of <code>from</code> as inner and leaf nodes. If
            <code>to</code> is not specified, then that entire tree is printed.
        </p>
        <p>
            If <code>to</code> is also specified, then only the first found
            dependency path from <code>from</code> to <code>to</code> is
            .printed with <code>to</code> at the top and <code>from</code> at
            the bottom.
        </p>
    </dd>
</dl>
<dl>
    <dt>merge</dt>
    <dd>
        <p>
            Updates all <code>.po</code> files with the generated
            <code>ox.pot</code>.
        </p>
        <ul class="params">
            <li>
                <b>Variables:</b> <code>BASEDIR</code>, <code>builddir</code>,
                <code>debug</code>, <code>package</code>, <code>revision</code>,
                <code>version</code>.
            </li>
        </ul>
        <p>
            This task updates the list of extracted i18n strings in
            <code>ox.pot</code> and calls the GNU Gettext tool
            <code>msgmerge</code> for every language in <code>i18n/*.po</code>.
        </p>
    </dd>
</dl>
<dl>
    <dt>update-i18n</dt>
    <dd>
        <p>Updates CLDR data in the source tree.</p>
        <ul class="params">
            <li>
                <b>Variables:</b> <code>BASEDIR</code>, <code>branch</code>,
                <code>package</code>, <code>tag</code>.
            </li>
        </ul>
        <p>
            This task downloads data from the Unicode CLDR and updates date
            translations for all languages in <code>i18n/*.po</code>.
        </p>
        <p>
            The exact version of CLDR data is specified as Suubversion tag or
            branch by the variables <code>tag</code> and <code>branch</code>,
            respectively. If neither is specified, then the Subversion trunk is
            checked out. If both are specified, <code>tag</code> is used.
        </p>
    </dd>
</dl>
<dl>
    <dt>verify-doc</dt>
    <dd>
        <p>Generates a documentation skeleton for extension points.</p>
        <ul class="params">
            <li>
                <b>Variables:</b> <code>BASEDIR</code>, <code>package</code>.
            </li>
        </ul>
        <p>
            This task is still under development. Currently, it creates a list
            of all extension points, which have a constant name in the source
            code. In the future it is supposed to update an existing list
            instead of overwriting it, and to handle non-constant extension
            point names.
        </p>
        <p>
            The list of extension points is stored as an HTML snippet in
            <code>doc/extensionpoints.html</code>.
        </p>
    </dd>
</dl>
[[Category:AppSuite]]
[[Category:AppSuite]]
[[Category:UI]]
[[Category:UI]]

Latest revision as of 09:00, 10 August 2016

API status: Deprecated

Build System

Abstract: This document describes the build system of OX App Suite. It is intended for app developers who use the build system to create apps as well as for OX App Suite developers who not only use the build system but also may wish to extend it.

The build system is used to create source archives from source files. These source archives can be used to compile installable packages for various Linux distributions. The build system can generate archives for the core UI as well as for independently installed apps.

The OX App Suite build system uses Jake, a port of Rake from Ruby to Node.js. Both Rake and Jake are dependency-based build systems like Make, which allows quick incremental builds. But unlike Make, Jake doesn't have its own syntax. Instead, it provides an API in JavaScript. The API is used not only to specify dependencies between files using a full programming language, but also to implement the generation of files in the same language. This allows easy implementation of complex build systems, of which the OX App Suite build system is an example. Using the same language for the developed project and for its build system also allows any core developer to quickly extend the build system without having to switch to another language.

Using the Build System

While easily extensible, most of the time the build system will be used as-is. This chapter describes how to set up and use the build system to develop apps and the OX App Suite core.

All command examples are given for the Debian operating system. The instructions should work similarly on other POSIX systems. The first character of each command indicates whether it should be executed as root (#) or as a normal user ($).

Installing

Installing the right environment for running the appserver and the UI build system is described in the getting started article.

Running

The build system is executed by invoking the command build-appsuite. Similar to most build systems, the build system can perform multiple tasks, which are specified as parameters on the command line. Each task can require any number of parameters. These parameters can be specified either on the command line, using the syntax name=value, or as environment variables.

If present, the file local.conf is sourced by a shell script before the build process starts. This file can export environment variables which are specific to the local system, without checking them into a version control system. Typically, it defines values for builddir and debug.

Since the build system is based on Jake, it also accepts all other Jake options. In addition, the environment variable $nodeopts can be used to pass command line parameters to Node.js. One of the most useful parameters is --debug-brk, which can be used to debug the build system.

When developing external apps, the build system must be run from the top directory of the app's source. As a safety precaution, execution is aborted if the subdirectory apps, which usually contains JavaScript source code, is not found. This Article is written assuming, you're working in your workspace directory, containing the subfolder apps.

Workflow

The build system is used not only to create source archives for packaging. It can also directly install and update the built UI in a directory during development, help with the setup of the source of a new external app and more. While all of these tasks are described in the reference section, daily work involves just a few of them.

To have an easy example about how to write, build & host your javascript code and how to initialize & build your packages, please have a look at the GettingStarted article.

JSHINT

One step of the build process is running jshint to statically analyse the sources for certain errors. JSHint is configured with (what we think) sane defaults, but if you want to configure your own rules, edit .jshintrc in your project`s root folder, according to your needs.

default

The default task is used instead of the app task when building the core OX App Suite. Since it is the default Jake task, it is not necessary to specify it on the command line when it's the only task.

The top directory of OX App Suite source code includes the script build.sh, which should be used instead of calling a potentially unrelated version of build-appsuite. The script changes the current directory to its own, so that it can be called from any directory.

  $ web/ui/build.sh

clean

The build system uses dependencies and file timestamps to decide which files to rebuild. This assumes that any change to a file increases its timestamp to a value which is greater than the timestamp of any existing file. When this assumption is violated (e.g. after switching to a different source control branch with older files) it may become necessary to rebuild everything to restore the assumption about timestamps. The simplest way to achieve this is the clean task, which simply deletes all generated files.

WARNING: This can be potentially dangerous, since the clean task simply deletes the directories specified by the variables builddir, destDir, l10nDir, manifestDir, and helpDir.

dist

When the app is ready to be shipped, or rather all the time on a continuous build system, the app needs to be packaged in a format suitable for installation on a production system. Since there already exist tools to create packages from suitably arranged source code archives, the OX App Suite build system merely prepares such source archives.

The dist task creates an archive with the source (the one ending in .orig.tar.bz2) and a few additional files necessary for Debian packaging. RPM packages can be generated using the same source archive and the .spec file created by init-packaging. The version of the package is extracted from the newest entry in the file debian/changelog.

Debian packages can also be generated manually either from the temporary directory left behind by dist, or even directly from the source tree. The second option pollutes the source tree with generated files, so it is not recommended, although the .gitignore file created by init-packaging can handle these generated files.

  $ build-appsuite dist
  $ ls tmp/packaging/
  example-app-0.0.1                   example-app_0.0.1-1.dsc
  example-app_0.0.1-1.debian.tar.bz2  example-app_0.0.1.orig.tar.bz2
  $ cd tmp/packaging/example-app-0.0.1/
  $ dpkg-buildpackage -b

Reference

Variables

BASEDIR

The top directory of the build system.

Used by: all tasks.

Default: installation directory of the build system

Required to build external apps, since in this case, the build system is not installed in the current directory. This variable is automatically set as an environment variable by the build system executable based on $OX_APPSUITE_DEV.

branch

The Subversion branch of the CLDR to checkout.

Used by: update-i18n.

builddir

The target directory for generated files.

Used by: app, clean, default, dist, docs, jakedeps.

Default: build

copyright

The copyright line to be included in packaging metadata.

Used by: init-packaging.

Example: 2012 Open-Xchange, Inc

coreDir

Location of OX App Suite UI files.

Used by: app, default.

Default: same as builddir

Some tasks depend on installed files from the OX App Suite. When building external apps, coreDir specified the directory which contains these files.

Currently, this parameter is used to compile .less files for every installed theme. This can be disabled by setting skipLess.

debug

Enables a debug build.

Used by: app, default.

Default: false

To simplify debugging of OX App Suite, compression of source code can be disabled by specifying on, yes, true or 1.

description

Used by: init-packaging.

The description of the app to be included in packaging metadata.

destDir

Output directory for source archives created by the dist task.

Used by: clean, dist.

Default: tmp/packaging

disableStrictMode

Removes all "use strict" directives from processed JavaScript code.

Used by: app, default.

Default: false

Some debugging tools which use code instrumentation have problems when the debugged code uses strict mode. This setting enables code processing even whe using debug mode, so line numbers will not match the original source code.

forceDeb

Whether an error during the generation of Debian source packages is an error.

Used by: dist.

Default: false

This is useful when Debian packages are generated automatically, and a failure of dpkg-source is also a failure of the entire build. By default it merely produces a warning.

from

The root of the printed dependency tree between Jake tasks.

Used by: jakedeps.

helpDir

The location of online help files.

Used by: clean, default, dist.

Default: same as builddir

If the value contains the string @lang@, it will be replaced by the lowercase language code (e.g. en-us) to allow per-language directories.

l10nDir

The location of compiled l10n files.

Used by: app, clean, default, dist.

Default: same as builddir

If the value contains the string @lang@, it will be replaced by the lowercase language code (e.g. en-us) to allow per-language directories.

license

File name of the full text of the distribution license.

Used by: init-packaging.

Default: based on licenseName.

licenseName

Name of the distribution license to be included in packaging metadata.

Used by: init-packaging.

Default: CC-BY-NC-SA-3.0

manifestDir

The location of the combined manifest file.

Used by: app, clean, default, dist.

Default: same as builddir

maintainer

Name and email address of the package maintainer.

Used by: init-packaging.

Format: Name <email>

package

The name of the package for the built app.

Used by: all tasks.

Default: the package name in the first line of debian/changelog

Since the name of the manifest file contains the package name and it is required to determine build dependencies, the package name must be always known. This means either debian/changelog must exist and contain at least one entry, or the parameter must be explicitly specified.

reverse

Reverses the direction of printed dependencies.

Used by: deps.

When specified, the deps task prints modules which depend on the specified modules, instead of modules on which the specified module depends.

revision

Revision number of the package for the app.

Used by: app, default, dist.

Default: 1

The revision number must increase with each rebuild of the same version to enable the creation of unique version strings. These are required in package names and to control content caching in clients.

root

Specifies for which module to print the dependencies.

Used by: deps.

Default: print all roots

If specified, only the dependencies of the specified module are printed. Otherwise, the dependencies of all modules are printed.

skipDeb

Whether to skip the generation of Debian source packages.

Used by: dist.

Default: false

This is useful when Debian packages are not required and/or dpkg-source is not available, e.g. on RPM based systems.

Even when using this flag, at least the file debian/changelog is still required, because it is used to store the package name and version.

skipLess

Whether to skip the preprocessing of LessCSS files.

Used by: app, default.

Default: false

This flag skips the generation of CSS files in the apps/themes/*/less directories of all themes. It is used by the packaging system, where the LessCSS files are precompiled after installation on the target system instead of while building the package.

tag

The Subversion tag of the CLDR to checkout.

Used by: update-i18n.

to

The leaf task in the printed dependency path between Jake tasks.

Used by: jakedeps.

When specified, only a single path from the root to the leaf task is printed (in reverse order).

version

Version number of the app.

Used by: app, default, dist, init-packaging.

Default: 0.0.1

The version should consist of a major, minor and patch version separated by dots.

Tasks

An up-to-date list of tasks can be printed using the -T command line option.

app

Builds an external app.

Variables: BASEDIR, builddir, coreDir, debug, disableStrictMode, l10nDir, manifestDir, package, revision, version.

This is the main task used to build external apps.

It works without explicitly specifying any variables, but during development, builddir is usually pointed to the directory of a locally installed OX App Suite UI to avoid additional copying steps. For debugging, debug is also often used. Note that clean must be called when changing any of the variables.

clean

Removes all generated files.

Variables: BASEDIR, builddir, destDir, l10nDir, manifestDir, package.

This task should be executed before a normal build using app or default after changing any build variables and after a switch between Git branches. Normal incremental builds can miss changed files if a branch switch replaces files by older versions.

default

Builds OX App Suite.

Variables: BASEDIR, builddir, debug, disableStrictMode, l10nDir, manifestDir, package, revision, version.

This is the main task to build OX App Suite. Since it is the default Jake task, it does not need to be specified explicitly on the command line when it is the only task.

It works without explicitly specifying any variables, but during development, builddir is usually pointed to a directory which is accessible to a local web server. For debugging, debug is also often used. Note that clean must be called when changing any of the variables.

deps

Prints module dependencies.

Variables: BASEDIR, package, reverse, root.

This task visualizes dependencies of RequireJS modules. It prints a tree of dependencies to stdout.

If root is specified, then only the dependencies of that module are printed. Otherwise, the dependencies of all modules, on which no other module depends are printed in sequence.

If reverse is specified, then this task prints dependants instead of dependencies, i.e. modules which depend on the specified module instead of modules on which the specified module depends.

dist

Creates source packages.

Variables: BASEDIR, builddir, destDir, forceDeb, l10nDir, manifestDir, package, revision, skipDeb, version.

This task cleans the source tree by calling clean and packs the source into an archive which can be used to create Debian and RPM packages. The necessary Debian metadata is created alongside the source archive. All files necessary for Debian packaging are placed in the directory specified by destDir. The generated .orig.tar.bz2 archive can also be used together with the .spec file to generate RPM packages.

Unless the variable skipDeb is set to true, the program dpkg-source is required by this task. It is used to generate Debian-specific packaging metadata.

init-packaging

Initializes packaging information for a new app.

Variables: BASEDIR, copyright, description, license, licenseName, maintainer, package, version.

This task is the first task called when starting with the development of a new external app. The directory from which it is called must already contain at least the apps subdirectory. This is also the only task where the package variable must be specified explicitly. Afterwards, the package name is looked up automatically in the file debian/changelog, which is created by this task.

The variables version, maintainer, copyright, licenseName, license, and description are required to fill out all necessary packaging metadata. Any of these variables which are not specified explicitly will cause an interactive prompt. This avoids the need to remember the list of variables before one can start developing an app.

jakedeps

Shows the dependency chain between two Jake tasks.

Variables: BASEDIR, from, package, to.

This task visualized dependencies between Jake tasks. The variable from specifies the root of a dependency tree, with all dependencies of from as inner and leaf nodes. If to is not specified, then that entire tree is printed.

If to is also specified, then only the first found dependency path from from to to is .printed with to at the top and from at the bottom.

merge

Updates all .po files with the generated ox.pot.

Variables: BASEDIR, builddir, debug, package, revision, version.

This task updates the list of extracted i18n strings in ox.pot and calls the GNU Gettext tool msgmerge for every language in i18n/*.po.

i18n/en_US.po is not updated by this task because the original strings are already in the en_US locale. It would only end up with every translation mapping every string to itself. The only entries in that file should be for cases when the en_US text is not a suitable fallback for missing translations. The original string in such a case would be something internationally appropriate (e. g. a date written as "2013-01-01" instead of "01/01/2013") and i18n/en_US.po would contain a translation.

update-i18n

Updates CLDR data in the source tree.

Variables: BASEDIR, branch, package, tag.

This task downloads data from the Unicode CLDR and updates date translations for all languages in i18n/*.po.

The exact version of CLDR data is specified as Suubversion tag or branch by the variables tag and branch, respectively. If neither is specified, then the Subversion trunk is checked out. If both are specified, tag is used.

verify-doc

Generates a documentation skeleton for extension points.

Variables: BASEDIR, package.

This task is still under development. Currently, it creates a list of all extension points, which have a constant name in the source code. In the future it is supposed to update an existing list instead of overwriting it, and to handle non-constant extension point names.

The list of extension points is stored as an HTML snippet in doc/extensionpoints.html.