digitalSTROM Server

h1. How to build the dSS

{{toc}}

h2. Get the source

Get the dSS release tarballs from the "dss developer site":http://developer.digitalstrom.org/releases/release-1.3/. Packages for all dSS11 projects can be found on the "dss download site":http://developer.digitalstrom.org/download/dss/.

If you like to work with the current development snapshot get the source via git as explained [[Git_Repository|here]]. These development snapshots may have changed dependencies or build instructions or may even have functional limitations.

h2. Used libraries

The dSS relies on some external libraries. To build it from source your system needs the following libraries and their development headers.

* "Boost":http://www.boost.org

* "Poco":http://pocoproject.org

* "gSOAP":http://gsoap2.sourceforge.net

  The gSOAP packages for Ubuntu with version 2.7.15 and 2.8.3-3 (and older 2.8.x releases) have known limitations and do not work with the dSS. Please update to a recent gsoap version.

* "OpenSSL":http://www.openssl.org

* "Avahi":http://avahi.org

* "libical":http://sourceforge.net/projects/freeassociation/

* "SpiderMonkey":http://www.mozilla.org/js/spidermonkey

  Since dSS release 1.3.2 the SpiderMonkey scripting engine with version 1.8.5 is required.

* "librrd":http://oss.oetiker.ch/rrdtool/doc/librrd.en.html

* "libcurl":http://curl.haxx.se/libcurl

* "dS485 Stack":http://developer.digitalstrom.org/download/ds485-stack/

  Typically the dSS release tarballs do cleanly build with the latest dS485 Stack releases. This may not be the case for the dSS git development snapshots which require to build the dS485 from the git repositories, too.

h2. Prerequisites on different distributions

To get you started we've compiled detailed instructions on how to get started on the following platforms:

* [[UbuntuSetup|Debian, Ubuntu]]

* [[FedoraSetup|Red Hat, Fedora]]

* [[Mac OS X]]

h2. Building the dS485 Stack 

The dSS requires the dSM-API and compaion library so those libraries have to be compiled first. The dS485 Stack uses

cmake to automate the build process.

To install the library into a separate directory in your home (recommended) specify the prefix using @cmake -DCMAKE_INSTALL_PREFIX=/home/yournamehere/yourpath@ instead of calling cmake without parameter.

h2. Compiling dSS with autotools

Starting with dSS version 1.4.0, the build system was changed from CMake to autotools.

h3. Before you begin

Make sure to install all development packages for the required libraries before running the configure script.

If you checked out the sources directly from git you will first have to generate the configure script. Make sure to that autoconf, automake and libtool are installed on your system and issue the following command:

<pre>

autoreconf -i

</pre>

If you downloaded a release tarball, the configure script will already be there.

h3. Configuring

If you are happy with the default options, just run:

<pre>

./configure

</pre>

However, if you installed some libraries in non standard locations you need to tell the configure script where to look for them. Also, there are some compile time options which can be used to build a specific dSS configuration, tune installation paths and more. To see all available options, run:

<pre>

./configure --help

</pre>

Below are the most useful parameters.

*Features*

<pre>

    --disable-soap          build dSS without SOAP support (default: enabled)

    --enable-http           build with HTTP support (default: HTTPS only)

    --disable-bonjour       build with bonjour support (default: enabled)

</pre>

*Installation directories*

<pre>

    --prefix=PREFIX                 install architecture-independent files in PREFIX [/usr/local]

    --with-dss-data=DIR             use DIR as dSS data directory

    --with-dss-config=DIR           use DIR as dSS config directory

    --with-dss-webroot=DIR          use DIR as dSS webroot directory

    --with-dss-js-logs=DIR          use DIR as dSS JavaScript logging directory

    --with-dss-saved-properties=DIR save dSS add-on script properties in DIR

</pre>

By default, @make install@ will install all the files in @/usr/local/bin@, @/usr/local/share/dss@ etc.  You can specify an installation prefix other than @/usr/local@ using @--prefix@, for instance @--prefix=$HOME/dSS@. This is quite useful if you do not want to do a system wide installation, but prefer to install the dSS somewhere in your home directory.

*Note:* the installation paths are compiled into the dSS binary, this means that if you ran @make install@ at least once, so that all expected paths were created, you can run the dSS binary from any place on your system. If needed, the configured paths can still be overriden on the dSS command line.

*Libraries in non standard locations*

If required libraries were not installed system wide (for example to prevent conflicts with libraries shipped by your distribution), you can tell the configure script where to look for your custom installed libraries and development headers. In most cases we use pkg-config to search for the libs, as it became a standard and is available in all major distributions.

<pre>

  --with-js-pkgconfig=DIR    search for libjs.pc or mozjs185.c in DIR

  --with-boost=DIR           prefix of Boost 1.46 [guess]

  --with-boost=DIR           prefix of Boost 1.35 [guess]

  --with-poco-h=DIR          search for poco headers in DIR

  --with-poco-libs=DIR       search for poco libraries in DIR

  --with-libdsm-api-h=DIR    search for libdsm-api headers in DIR

  --with-libdsm-api-libs=DIR search for libdsm-api libraries in DIR

  --with-gsoap-import=DIR    search for gSOAP import headers in DIR

</pre>

Use these variables to override the choices made by @configure@ or to help it to find libraries and programs with nonstandard names/locations.

<pre>

Some influential environment variables:

  BOOST_ROOT        location of Boost installation

  PKG_CONFIG        path to pkg-config utility

  PKG_CONFIG_PATH   directories to add to pkg-config's search path

  PKG_CONFIG_LIBDIR path overriding pkg-config's built-in search path

  JS_CFLAGS         C compiler flags for JS, overriding pkg-config

  JS_LIBS           linker flags for JS, overriding pkg-config

  ICAL_CFLAGS       C compiler flags for ICAL, overriding pkg-config

  ICAL_LIBS         linker flags for ICAL, overriding pkg-config

  LIBXML2_CFLAGS    C compiler flags for LIBXML2, overriding pkg-config

  LIBXML2_LIBS      linker flags for LIBXML2, overriding pkg-config

  OPENSSL_CFLAGS    C compiler flags for OPENSSL, overriding pkg-config

  OPENSSL_LIBS      linker flags for OPENSSL, overriding pkg-config

  AVAHI_CFLAGS      C compiler flags for AVAHI, overriding pkg-config

  AVAHI_LIBS        linker flags for AVAHI, overriding pkg-config

  LIBRRD_CFLAGS     C compiler flags for LIBRRD, overriding pkg-config

  LIBRRD_LIBS       linker flags for LIBRRD, overriding pkg-config

  GSOAP_CFLAGS      C compiler flags for GSOAP, overriding pkg-config

  GSOAP_LIBS        linker flags for GSOAP, overriding pkg-config

</pre>

In most cases you should not need to tune these settings, the usual "candiates" for non standard directories are the dS485 stack libraries and SpiderMonkey 1.8.5.

Here is an example from my system:

<pre>

./configure --with-libdsm-api-libs=/opt/dS485/installed/lib \

            --with-libdsm-api-h=/opt/dS485/installed/include \

            --with-js-pkgconfig=/opt/JS/installed/lib/pkgconfig

            --prefix=/tmp/dss

</pre>

h3. Compiling

Simply run @make@ followed by @make install@:

<pre>

make

make install

</pre>

After running make, the dSS binary will be located in the @./build/@ directory. If you executed @make install@ at least once, you can run the dSS binary directly from your build tree, i.e. @./build/dss@

The tests are not installed by default, you can run them directly from your build tree, i.e. @./build/dsstests@

h2. Compiling dSS with CMake

*Note:* CMake support is deprecated since version 1.4.0, however it will stay available for a short time to make transition to the new build system easier.

<pre>

mkdir dss/build

cd dss/build

cmake .. [CMake Options]

make

</pre>

If you're compiling the dSS for development it's recommended that you set the data-directory to @data/@:

<pre>

cmake .. -DWITH_DATADIR=data/

</pre>

h3. Options for CMake

* @-DWITH_DATADIR=path@ 

  specifies the default location of the @data@ directory (default: @/usr/share/dss/data@).

* @-DWITH_TESTS=[yes|no]@ 

  include tests in the build (default: @yes@).

* @-DWITH_SIM=[yes|no]@ 

  include the simulation in the build (default: @yes@)

* @-DCMAKE_BUILD_TYPE=[Release|Debug]@

  default: @Release@

* @-DLIBDSM_PREFIX=/path/to/libdsm@

  searches for the dsm-api in @/path/to/libdsm@

* @-DSPIDERMONKEY_ROOT=/path/to/spidermonkey@

  searches for the spidermonkey development files in @/path/to/spidermonkey@

* @-DWITH_SOAP=[yes|no]@ 

  include the soap service in the build (default: @yes@)

* @-DWITH_HTTP=[yes|no]@ 

  include the http protocol support in the build (default: @no@)

h2. Configuring

As of version 0.7.7 the web server is using SSL, therefore you need to generate a private key and a certificate. A helper script that will do this for you is provided, it will generate a private key, a self signed certificate and it will put them in a file called @dsscert.pem@. The script is called in @create_cert.sh@ and is located in the tools directory in the source tree, make sure that openssl is installed on your system and run the create_cert.sh script without any parameters. After that, copy the dsscert.pem file to your dss data directory.

All options are published in the internal property tree. This tree can be accessed through the webbrowser at [http://yourhost:8080/browse/].

Note, that the SOAP interface is also using SSL, by default it is configured to use the default @dsscert.pem@ file from the dss config directory.

h1. Building webpages

The web pages are built as a standalone package. If you checked out the web sources directly from git you will first have to generate the configure script. Make sure to that autoconf and automake are installed on your system and issue the following command:

<pre>

autoreconf -i

</pre>

To build the web sources make sure that you have installed sprocketize and issue the following commands:

<pre>

./configure --prefix=/desired/prefix/path

make

make install

</pre>

If you downloaded a release tarball of the web pages you can skip the above steps.

You can then either configure the webroot path via config.xml or start the dSS with @-w /path/to/websources@ parameter.

It is possible to build a release and a debug version of the web interface, it will not minimize the JS code and will use debug ExtJS/Sencha libraries. To build the debug version specify the @--enable-debug@ parameter when running the configure script, then run make:

<pre>

./configure --enable-debug

make

</pre>

The build system also supports a dist-release target, it will generate a tar file with ready to use web UI files that do not require any further processing. Just unpack it and point the dSS to the webroot directory using the @-w@ option. To generate a ready to use release tarball run the following commands:

<pre>

./configure

make

make dist-release

</pre>

h1. Building a debian package

Run the following command to build a debian package (from the dss root source directory)

<pre>

  $ dpkg-buildpackage -rfakeroot

</pre>

h2. Signed debian package

If you're intending to distribute the package, you might want to sign it using your GNUPG key:

<pre>

  $ dpkg-buildpackage -rfakeroot -k<GNUPG key>

</pre>

Not that you'll have to pass your GnuPG key ID to this command, unless you have a key in your keychain which matches the last changelog entry

h1. Running tests

The make target @test@ runs the full test-suite. You should be able to run the test by issuing the following line in your @build@ directory:

<pre>

make test

</pre>