Building nymea
This section assumes that the build environment has already been set up. Please refer to the previous section if the build environment has not been set up yet.
Depending on the need, nymea can be built using a graphical IDE or via command line. If the purpose of building nymea from source is to install nymea on a new system, or do only small modifications like applying patches, building via the command line might be the better choice. A developer changing the code will most likely want to use QtCreator as it offers code completion, inline documentation and all the other features that are expected from an IDE.
Building natively
The nymea source code can be obtained from GitHub. There is a range of repositories. Depending on the need, only a selection of those repositories might be checked out.
If the entire nymea stack is to be built from source, all those repositories are required.
If only individual parts are to be built from source, each individual repository can be built individually and the others uses from the nymea. After following the instructions for setting up the build environment all parts should be available as binary form on the development machine already.
Each module supports different build configurations. In order to activate those, append the given option to the qmake
line. For
example: qmake .. PREFIX=/usr CONFIG+=release
.
nymea-gpio
git clone https://github.com/nymea/nymea-gpio
mkdir nymea-gpio/builddir
cd nymea-gpio/builddir
qmake .. PREFIX=/usr/
make
sudo make install
This module supports the following build configurations:
- debug:
CONFIG+=debug
- release:
CONFIG+=release
libnymea-networkmanager
git clone https://github.com/nymea/libnymea-networkmanager
mkdir libnymea-networkmanager/builddir
cd libnymea-networkmanager/builddir
qmake .. PREFIX=/usr/
make
sudo make install
This module supports the following build configurations:
- debug:
CONFIG+=debug
- release:
CONFIG+=release
nymea-networkmanager
git clone https://github.com/nymea/nymea-networkmanager
mkdir nymea-networkmanager/builddir
cd nymea-networkmanager/builddir
qmake .. PREFIX=/usr/
make
sudo make install
This module supports the following build configurations:
- debug:
CONFIG+=debug
- release:
CONFIG+=release
nymea-remoteproxyclient
git clone https://github.com/nymea/nymea-remoteproxyclient
mkdir nymea-remoteproxyclient/builddir
cd nymea-remoteproxyclient/builddir
qmake .. PREFIX=/usr/
make
sudo make install
This module supports the following build configurations:
- debug:
CONFIG+=debug
- release:
CONFIG+=release
nymea-mqtt
git clone https://github.com/nymea/nymea-mqtt
mkdir nymea-mqtt/builddir
cd nymea-mqtt/builddir
qmake .. PREFIX=/usr/
make
sudo make install
This module supports the following build configurations:
- debug:
CONFIG+=debug
- release:
CONFIG+=release
nymea
git clone https://github.com/nymea/nymea
mkdir nymea/builddir
cd nymea/builddir
qmake .. PREFIX=/usr/
make
sudo make install
This module supports the following build configurations:
- debug:
CONFIG+=debug
- release:
CONFIG+=release
- build without tests:
CONFIG+=disabletesting
- enable code coverage reporting for tests:
CONFIG+=coverage
- build with address sanitizer:
CONFIG+=asan
nymea-plugins
git clone https://github.com/nymea/nymea-plugins
mkdir nymea-plugins/builddir
cd nymea-plugins/builddir
qmake .. PREFIX=/usr/
make
sudo make install
This module supports the following build configurations:
- debug:
CONFIG+=debug
- release:
CONFIG+=release
- select only specific plugins to be built:
WITH_PLUGINS=plugin1 plugin2 ...
- exclude specific plugins from being built:
WITHOUT_PLUGINS=plugin1 plugin2 ...
Cross-compiling
In order to build debian packages for nymea for your target device, we provide a tool for crosscompiling called crosscompiler
.
This tool makes helps to build a debian package inside a lxd container which can makes sure all required packages for building and deploying
are available and also for different architectures.
The crossbuilder
tool can be started within a git source code repository and generates a brand new lxc container for the given distribution and architecture.
Installation
Install the crossbuilder package from the nymea repositoy (see install section):
$ sudo apt-get install crossbuilder
Setup
In order to set up the crossbuilder lxd environment you can run following command and follow the setup instructions:
$ crossbuilder setup-lxd
Building
Assuming you are running crossbuilder on a amd64
Ubuntu machine, and you want to build a project for armhf
debian stretch
you can do following steps.
You clone a project repository (in this example the nymea
project) and change to the project directory:
$ git clone https://github.com/nymea/nymea.git
$ cd nymea
If you run the crossbuilder the first time, we need to specify the architecture and the distribution we want to build packages for:
$ crossbuilder -a armhf -u stretch
Crossbuilder will now contact the nymea lxc host server (https://jenkins.nymea.io:8443) and check if the available image for crosscompilation exists for the target achitecture and distribution (stretch armhf
). If the image was found, a new local lxc container will be created for exactly this repository.
The next step for crossbuilder is mounting the current source directory into the new created container and will start building the packages (containing build dependencies installing). If you change the source code and want to run the build process again, crossbuilder will reuse this container and also the already created build outputs. If you change the build dependencies of the package you don’t need to rebuild the container, you just need to run following command in order to install the missing build dependencies inside the container:
$ crossbuilder dependencies
You can check any time which containers you already have and which are running on your local build machine:
$ lxc list
+--------------------------------------------------------+---------+-------------------+------+------------+-----------+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
+--------------------------------------------------------+---------+-------------------+------+------------+-----------+
| nymea-nymea-builder-stretch-amd64-armhf | RUNNING | 10.0.1.106 (eth0) | | PERSISTENT | 0 |
+--------------------------------------------------------+---------+-------------------+------+------------+-----------+
Her you can see the created container for building nymea. The naming of the container is <project>-nymea-builder-<distribution>-<host-architecture>-<target-architecture>
.
Cleaning the build
Once the crossbuilder has finished, you can find all build results in the source tree (since the packages where created in the mounted source tree). If you want to clean up the source directory again you can run:
$ crossbuilder clean
Build output
A compressed file containing the debian packages and also the source packages will be the output of script. You can take a look at the built packages by extracting the file and check the content:
$ tar xfv debs_*
libnymea1_0.9.0+201803271733~c348a6b~stretch_armhf.deb
libnymea1-dev_0.9.0+201803271733~c348a6b~stretch_armhf.deb
nymea_0.9.0+201803271733~c348a6b~stretch_armhf.deb
nymead_0.9.0+201803271733~c348a6b~stretch_armhf.deb
nymea-dbg_0.9.0+201803271733~c348a6b~stretch_armhf.deb
nymea-tests_0.9.0+201803271733~c348a6b~stretch_armhf.deb
nymea-translations_0.9.0+201803271733~c348a6b~stretch_all.deb
source_repository/nymea_0.9.0+201803271733~c348a6b~stretch.dsc
source_repository/nymea_0.9.0+201803271733~c348a6b~stretch_source.changes
source_repository/nymea_0.9.0+201803271733~c348a6b~stretch.tar.xz
The content will be extracted in the source directory. If you want to see the content of the resulting packages you can use the dpkg
command:
$ dpkg -c libnymea1_0.9.0+201803271733~c348a6b~stretch_armhf.deb
drwxr-xr-x root/root 0 2018-03-27 17:36 ./
drwxr-xr-x root/root 0 2018-03-27 17:36 ./usr/
drwxr-xr-x root/root 0 2018-03-27 17:36 ./usr/lib/
drwxr-xr-x root/root 0 2018-03-27 17:36 ./usr/lib/arm-linux-gnueabihf/
-rw-r--r-- root/root 539272 2018-03-27 17:36 ./usr/lib/arm-linux-gnueabihf/libnymea.so.1.0.0
drwxr-xr-x root/root 0 2018-03-27 17:36 ./usr/share/
drwxr-xr-x root/root 0 2018-03-27 17:36 ./usr/share/doc/
drwxr-xr-x root/root 0 2018-03-27 17:36 ./usr/share/doc/libnymea1/
-rw-r--r-- root/root 1436 2018-03-27 17:36 ./usr/share/doc/libnymea1/changelog.gz
-rw-r--r-- root/root 1942 2018-03-27 17:30 ./usr/share/doc/libnymea1/copyright
lrwxrwxrwx root/root 0 2018-03-27 17:36 ./usr/lib/arm-linux-gnueabihf/libnymea.so.1 -> libnymea.so.1.0.0
lrwxrwxrwx root/root 0 2018-03-27 17:36 ./usr/lib/arm-linux-gnueabihf/libnymea.so.1.0 -> libnymea.so.1.0.0
Login into container
If you want to login into the build container you can simply run:
$ crossbuilder shell
Cache
If you run the crossbuilder a second time, you just need to run crossbuilder
, since the first time a configuration file for the container has been created. Crossbuilder will also make use of the host ccache
independent form the architecture and distribution. In this example you can find the crossbuilder
cached information here:
$ cat .crossbuilder/cache.conf
TARGET_ARCH=armhf
TARGET_UBUNTU=stretch
Delete the container
If you are finished and the container will not be needed any more you can delete the container by running:
$ crossbuilder delete
Deploy on target machine
If you want crossbuilder to deploy the packages to a remote machine and install them, you can create following configuration file:
$ nano .crossbuilder/deploy.conf
Here you can add the remote information of the target machine (in this example an armhf stretch
machine running on 10.10.10.10
where you want to install the debian packages built with the crosscompiler
.
Note: the packages need to be already installed once on the target machine, since crossbuilder is just updating them, not installing them from scretch. If that is not the case, you can install them manually after crossbuilder copied them to the target and created the local repository: on the target
sudo dpkg -i /tmp/repo/*.deb
.
DEPLOY_IP=10.10.10.10
DEPLOY_USER=nymea
DEPLOY_KEY=~/.ssh/id_rsa
Each new build will from now on be installed automatically on the target machine until you delete the configuration file.
Interacting with the containers
Remove a container if the source repositoy does not exist any more:
Note: the
--force
is only needed if the container is still running.
$ lxc list
+--------------------------------------------------------+---------+-------------------+------+------------+-----------+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
+--------------------------------------------------------+---------+-------------------+------+------------+-----------+
| nymea-nymea-builder-stretch-amd64-armhf | RUNNING | 10.0.1.106 (eth0) | | PERSISTENT | 0 |
+--------------------------------------------------------+---------+-------------------+------+------------+-----------+
$ lxc delete nymea-nymea-builder-stretch-amd64-armhf --force
Building with Yocto
nymea can be built with yocto. For that, we offer a meta layer which can be found on GitHub.
This meta layer can be added to a yocto image and offers the following packages:
- nymea-mqtt
- nymea-networkmanager
- nymea-remoteproxy
- nymea-gpio
- nymead
- nymea-plugins