Building from Source (with Autotools)

• Prerequisites

• Dependencies

• Building

  • ‘Debug’ variant

  • ‘Release’ variant

  • Single Debian package created with ‘checkinstall’

  • The traditional method

  • Conditional compilation of sub-projects

    • Excluding the player sub-project

    • Excluding the plugins/spotify_source sub-project

    • Excluding the plugins/pcm_renderer_alsa sub-project

• Tizonia’s configuration file

• Resource Manager’s D-BUS service activation file (optional)

• Known issues

• Speeding up (re-)compilation using ccache

• Creating a JSON compilation database, for use with e.g. Emacs RTags

To build and install from source, please read the following sections. Ubuntu 18.04 is assumed, but should work on other recent Debian-based distros.

Prerequisites

Please make sure you have enough RAM available on your system to build Tizonia. A good 8GB of RAM may be needed if you are planning to build everything, including the ‘tizonia’ player application. You might encounter problems if you are trying to run the compilation while large programs like Chrome or Firefox are running. See Known issues for the kind of errors that you might encounter in those cases. Also look at Conditional compilation of sub-projects for instructions on how to disable certain parts of the software.

NOTE: Also make sure you have some time in your hands. Building Tizonia may take at least 20 minutes on a fast SSD-based system. You may want to look at Speeding up (re-)compilation usingccache if you are planning to build the Tizonia tree multiple times.

Dependencies

To install all the development dependencies, the tizonia-dev-build tool is the recommended way. This script lives under the tools directory and internally maintains an up-to-date list of all the packages that are required in a Debian-compatible system to build Tizonia from source.

NOTE: The following command installs Mopidy’s ‘libspotify-dev’ package, and the ‘gmusicapi’, ‘soundcloud’, ‘pafy’ and ‘youtube-dl’ Python PIP packages, plus a few other necessary debian packages.

# Setup the following environment variables
$ export TIZONIA_REPO_DIR=/path/to/tizonia/repo # (e.g. /home/user/tizonia-openmax-il)
$ export TIZONIA_INSTALL_DIR=/path/to/install/dir # (e.g. /usr or /home/user/temp)
$ export PATH=$TIZONIA_REPO_DIR/tools:$PATH

# Set the PYTHONPATH accordingly (replace X to match the python version on your system)
$ export PYTHONPATH=$TIZONIA_INSTALL_DIR/lib/python3.X/site-packages:$PYTHONPATH

# Now install everything that is required to build Tizonia from source (Debian derivative assumed)
$ tizonia-dev-build --deps

Building

Once all the dependencies have been installed, build and install the OpenMAX IL framework, all plugins and the ‘tizonia’ command-line application, using any of the following methods.

‘Debug’ variant

The following command re-configures all sub-projects with ‘debug’ type of flags, and then proceeds to build and install them.

$ tizonia-dev-build --debug --install

‘Release’ variant

The following command re-configures all sub-projects with ‘release’ type of flags, builds and installs them.

$ tizonia-dev-build --release --install

Single Debian package created with ‘checkinstall’

The following command configures all sub-projects with ‘release’ flags appropriate for a Debian/Ubuntu system, builds the whole repo, then using checkinstall creates a single Debian package and installs it in the system. The package can then be removed via ‘dpkg’ or even moved to another machine for testing.

NOTE: This is the best way to build Tizonia if all you want is to install it on a system that for which there are no official binaries.

NOTE: This is not how the Debian packages hosted on Bintray are created. The packages hosted on Bintray are fully ‘debianized’ packages created using the ‘tizonia-qemu-debootstrap-env’ script.

# This produces and install a Debian package called 'tizonia-all-testing'
$ tizonia-dev-build --debian

# To remove from the system, run:
$ dpkg -r tizonia-all-testing

The traditional method

Alternatively, from the top of Tizonia’s repo, one can also do the familiar:

$ autoreconf -ifs
$ ./configure    # or ./configure --disable-player to disable the command-line player program
$ make
$ make install

Conditional compilation of sub-projects

Excluding the player sub-project

Some people are only interested in building the OpenMAX IL framework, without the tizonia player application (that lives under the ‘player’ sub-directory). During configuration, it can be disabled by including the --disable-player option:

# Disable compilation of the command-line player program.
$ ./configure --disable-player

Alternatively, the --no-player option may be added to tizonia-dev-build to disable configuration and build of the tizonia player.

# Build and install in DEBUG mode without the command-line player program.
$ tizonia-dev-build --no-player --debug --install

Excluding the plugins/spotify_source sub-project

The --without-libspotify option may be included to disable configuration and build of the libspotify-based OpenMAX IL component. This option will also disable the support for this plugin in the tizonia player program.

# Disable support for the spotify_source plugin.
$ ./configure --without-libspotify

Excluding the plugins/pcm_renderer_alsa sub-project

The --without-alsa option may be included to disable configuration and build of the ALSA-based OpenMAX IL pcm renderer.

# Disable support for the ALSA pcm renderer plugin.
$ ./configure --without-alsa

Tizonia’s configuration file

Copy tizonia.conf into the user’s config folder:

$ mkdir -p $HOME/.config/tizonia \
    && cp $TIZONIA_REPO_DIR/config/src/tizonia.conf $HOME/.config/tizonia

Resource Manager’s D-BUS service activation file (optional)

OpenMAX IL Resource Management is present but disabled by default. This is a feature required on an compliant OpenMAX IL 1.2 implementation. Currently, there is no other use beyond enabling OpenMAX IL compliance. In case this is to be used during OpenMAX IL conformance testing (prior to that, it needs to be explicitly enabled in tizonia.conf), copy the Resource Manager’s D-BUS activation file to some place where it can be found by the DBUS services. E.g:

$ mkdir -p ~/.local/share/dbus-1/services \
    && cp rm/tizrmd/dbus/com.aratelia.tiz.rm.service ~/.local/share/dbus-1/services

Known issues

The tizonia player app makes heavy use the the the Boost Meta State Machine (MSM) library by Christophe Henry (MSM is in turn based on Boost MPL).

MSM is used to generate a number of state machines that control the tunneled OpenMAX IL components for the various playback uses cases. The state machines are quite large and MSM is known for not being easy on the compilers. Building the tizonia command-line app in ‘debug’ configuration (with debug symbols, etc) requires quite a bit of RAM.

You may see GCC crashing like below; simply keep running make -j1 or make -j1 install until the application is fully built (it will finish eventually, given the sufficient amount RAM). An alternative to that is to build in ‘release’ mode (especially if you are on a 32-bit distro).

Making all in src
  CXX      tizonia-tizplayapp.o
  CXX      tizonia-main.o
  CXX      tizonia-tizomxutil.o
  CXX      tizonia-tizprogramopts.o
  CXX      tizonia-tizgraphutil.o
  CXX      tizonia-tizgraphcback.o
  CXX      tizonia-tizprobe.o
  CXX      tizonia-tizdaemon.o
  CXX      tizonia-tizplaylist.o
  CXX      tizonia-tizgraphfactory.o
  CXX      tizonia-tizgraphmgrcmd.o
  CXX      tizonia-tizgraphmgrops.o
  CXX      tizonia-tizgraphmgrfsm.o
  CXX      tizonia-tizgraphmgr.o
  CXX      tizonia-tizdecgraphmgr.o
g++: internal compiler error: Killed (program cc1plus)
Please submit a full bug report,
with preprocessed source if appropriate.
See <file:///usr/share/doc/gcc-4.8/README.Bugs> for instructions.
make[2]: *** [tizonia-tizplayapp.o] Error 4
make[2]: *** Waiting for unfinished jobs....
g++: internal compiler error: Killed (program cc1plus)
Please submit a full bug report,
with preprocessed source if appropriate.
See <file:///usr/share/doc/gcc-4.8/README.Bugs> for instructions.

Speeding up (re-)compilation using ccache

ccache is a compiler cache. It speeds up recompilation by caching previous compilations. With Tizonia, this is very useful during development, especially since the ‘player’ application is so hard to build due to the boost machinery.

On a debian system, ccache can be installed using:

$ sudo apt-get install ccache

Once ccache is installed, tizonia-dev-build will detect its presence and start making use of it to (dramatically) reduce compilation time in most cases.

Creating a JSON compilation database, for use with e.g. Emacs RTags

JSON compilation databases are used nowdays by many tools to provide information on how a single compilation unit is processed. This helps these programs to perform many useful tasks, like static analyses of various kinds. RTags is an example of program that uses a JSON compilation database to index C/C++ code and keep a persistent file-based database, for use within Emacs to provide powerful integrations.

tizonia-dev-build has support for bear (a program that creates JSON databases) and RTags. To use, install both programs:

$ sudo apt-get install bear

# For RTags, visit its GitHub for up-to-date installation instructions
# https://github.com/Andersbakken/rtags

and finally, create the compilation db with these two commands:

$ tizonia-dev-build --debug (or --release)

# followed by

$ tizonia-dev-build --bear

After that, to keep the database up-to-date after code changes, use:

$ tizonia-dev-build --make (or --install)