How to build the dSS¶

• How to build the dSS
  • Get the source
  • Used libraries
  • Prerequisites on different distributions
  • Building the dS485 Stack
  • Compiling dSS with autotools
    • Before you begin
    • Configuring
    • Compiling
  • Compiling dSS with CMake
    • Options for CMake
  • Configuring
• Building webpages
• Building a debian package
  • Signed debian package
• Running tests

Get the source¶

Get the dSS release tarballs from the dss developer site. Packages for all dSS11 projects can be found on the dss download site.

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

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

• Poco

• gSOAP

  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

• Avahi

• libical

• SpiderMonkey

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

• librrd

• libcurl

• 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.

Prerequisites on different distributions¶

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

• Debian, Ubuntu
• Red Hat, Fedora
• Mac OS X

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.

Compiling dSS with autotools¶

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

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:

autoreconf -i

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

Configuring¶

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

./configure

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:

./configure --help

Below are the most useful parameters.

Features

    --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)

Installation directories

    --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

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.

  --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

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

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

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:

./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

Compiling¶

Simply run make followed by make install:

make
make install

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

If you compiled against libraries in non-standard locations, you have to tell the linker where these libraries are. You do this by setting the LD_LIBRARY_PATH (MacOS X: DYLD_LIBRARY_PATH) to the directory(s) where the libraries are installed.

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

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.

mkdir dss/build
cd dss/build
cmake .. [CMake Options]
make

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

cmake .. -DWITH_DATADIR=data/

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)

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.

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:

autoreconf -i

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

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

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:

./configure --enable-debug
make

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:

./configure
make
make dist-release

Building a debian package¶

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

  $ dpkg-buildpackage -rfakeroot

Signed debian package¶

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

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

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

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:

make test