1. Install

1.1. Install from source code

The source code is available under Apache 2.0 license at https://github.com/bitdribble/bitdribble:

git clone git@github.com:bitdribble/bitdribble.git

All platforms require the expat, libyaml, jansson, microhttpd, openssl and libcurl development libraries installed.

1.1.1. Centos

Centos 7 has been tested. The default cmake on Centos 7 is version 2. We need cmake version 3, which we install and execute as cmake3.

sudo yum install cmake3 expat-devel libyaml-devel jansson-devel libmicrohttpd-devel openssl-devel libcurl-devel

cd .../bitdribble
mkdir build && cd build && cmake3 ..
make
sudo make install

The make install command will install headers, libraries and binaries under /usr/local. The installer can also be packaged as an rpm package.

cpack3 -G RPM

To install the rpm package, execute the command below. This will install headers, libraries and binaries under /usr.

sudo rpm -ivh bitd-<version>-<platform>.rpm

After installing the package, enable and start the bitd service:

sudo systemctl enable bitd
sudo systemctl start bitd

To uninstall the package:

sudo rpm -e bitd

1.1.2. Ubuntu

Ubuntu 18.04 has been tested. The default cmake on Ubuntu 18.04 has version higher than 3.1, and can be used directly.

sudo add-apt-repository universe
sudo add-apt-repository multiverse
sudo apt-get install build-essential libexpat-dev libyaml-dev libjansson-dev libmicrohttpd-dev libssl-dev libcurl4-openssl-dev

cd .../bitdribble
mkdir build && cd build && cmake ..
make
sudo make install

The make install command will install headers, libraries and binaries under /usr/local. The installer can also be packaged as a deb package:

cpack -G DEB

To install the deb package, execute the command below. This will install headers, libraries and binaries under /usr.

sudo dpkg -i bitd-<version>-<platform>.deb

After installing the package, enable and start the bitd service:

sudo systemctl enable bitd
sudo systemctl start bitd

To uninstall the package:

sudo dpkg -r bitd

1.1.3. Raspbian

Raspbian GNU/Linux 8 (jessie) and GNU/Linux 9.4 (stretch) have been tested. Raspberry Pi boards usually have a limited amount of flash. Before beginning installation, check the available flash size: df. The system I tested had 14G available on the root file system, and the root file system was 33% full.

Start by upgrading all packages:

sudo apt-get update
sudo apt-get upgrade

After upgrading all the packages, the root file system became 35% full. To compile the code, cmake needs to be installed as well, if not already installed.

sudo apt-get install build-essential cmake \
      libexpat-dev libyaml-dev libjansson-dev libmicrohttpd-dev \
      libssl-dev libcurl4-openssl-dev

cd .../bitdribble
mkdir build && cd build && cmake ..
make
sudo make install

The make install command will install headers, libraries and binaries under /usr/local. The installer can also be packaged as a deb package:

cpack -G DEB

To install the deb package, execute the command below. This will install headers, libraries and binaries under /usr.

sudo apt-get install expat libyaml-0-2 openssl libcurl3
sudo dpkg -i bitd-<version>-<platform>.deb

Note that on Raspbian Jessie and Stretch we need libcurl4-ssl-dev for the compilation, but libcurl3 for installing the bitd Debian package. After installing the package, enable and start the bitd service:

sudo systemctl enable bitd
sudo systemctl start bitd

To uninstall the package:

sudo dpkg -r bitd

1.1.4. OpenWRT

Use these instructions to install the OpenWRT SDK sources on Ubuntu. At the make menuconfig step, enable compilation of

  • Libraries->jansson
  • Libraries->libexpat
  • Libraries->libmicrohttpd (leave libmicrohttpd-no-ssl unchecked)
  • Libraries->Languages->libyaml
  • Libraries->SSL->libopenssl
  • Libraries->libcurl

These packages should either be included in the firmware image file, or should be installed with opkg after the firmware has been flashed to the device.

In this example, we build OpenWRT for Target System (x86), Subtarget (x86_64), and we enable Target Image->VMDK. The resulting toolchain under openwrt/staging_dir is toolchain-x86_64_gcc-7.3.0_musl, and the target is target-x86_64_musl. We use these settings to create bitdribble/cmake/Toolchains/Toolchain-openwrt-x86_64_gcc_musl.cmake in the bitdribble source tree, then we build the bitdribble code:

cd .../bitdribble
mkdir build-openwrt-x86 && cd build-openwrt-x86
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/Toolchain-openwrt-x86.cmake ..
make

For different a OpenWRT target, create a corresponding toolchain file under bitdribble/cmake/Toolchains, and pass it on the cmake command line using -DCMAKE_TOOLCHAIN_FILE.

1.1.5. Mac OSX

The default openssl and curl libraries installed by OSX are incompatible with bitdribble. Instead, install these packages using brew, along with other package dependencies that are needed:

brew install make cmake expat libyaml jansson libmicrohttpd openssl curl

cd .../bitdribble
mkdir build && cd build && cmake ..
make

1.1.6. Cygwin

Older Cygwin only distributes cmake version 2. You need a version of Cygwin that distributes cmake version 3. We have tested Cygwin version 2.893 (64 bit) which has cmake version 3.

Use the Cygwin Setup program to install these packages:

  • Debug, Devel categories
  • expat-devel
  • openssl-devel
  • libjansson-devel
  • libcurl-devel.

Additional packages not included in the Cygwin distribution must be compiled from sources, running configure then make && make install. Following package needs to be compiled from sources:

  • libmicrohttpd version 0.9.60 or later

Then, in a Cygwin bash terminal, do the following:

cd .../bitdribble

mkdir ../cygwin && cd ../cygwin && cmake ../cygwin
make

The install step will install the packages under /usr/local/bin and /usr/local/include, in the cygwin installation tree:

make install

The installer package can be set up as a .tar.bz2 archive with the command cpack -G CygwinBinary, but modern Cygwin installers use cygport instead. We do not have cygport support at this time.

1.1.7. Windows

We use the mingw cross compilers distributed as Cygwin package. As explained in the Cygwin section, you need a version of Cygwin that distributes cmake version 3.

The instructions below assume a 64 bit Cygwin installation. Install all the Cygwin mingw64-x86_64 and mingw64-i686 packages. These packages include:

  • expat-devel
  • openssl-devel
  • libcurl-devel.

Additional packages must be compiled from sources running

configure --host=x86_64-w64-mingw32 --prefix=/usr/x86_64-w64-mingw32/sys-root/mingw
# respectively
configure --host=i686-w64-mingw32 --prefix=/usr/i686-w64-mingw32/sys-root/mingw
# both followed by
make && make install

The additional packages needed are:

  • libjansson version 2.11 or later
  • libmicrohttpd version 0.9.60 or later

For 64 bit Windows builds:

cd .../bitdribble
mkdir ../x86_64-w64-mingw32 && cd ../cygwin

cmake -DCMAKE_TOOLCHAIN_FILE=../bitdribble/cmake/Toolchains/Toolchain-x86_64-w64-mingw32.cmake ../bitdribble
make

Or this for 32 bit Windows builds:

cd .../bitdribble
mkdir ../i686-w64-mingw32 && cd ../cygwin

cmake -DCMAKE_TOOLCHAIN_FILE=../bitdribble/cmake/Toolchains/Toolchain-i686-w64-mingw32.cmake ../bitdribble
make

The install step will install the packages under /usr/local/bin and /usr/local/include, in the cygwin installation tree. Note that the expat, libyaml, ssl and curl libraries are dependencies and need to be manually copied in the PATH.

make install

1.2. Run the unit tests

After compiling from sources, and before make install, you can optionally run the unit tests:

make test

You can selectively run some of the tests by executing ctest instead of make test, passing a substring of the test labels using the -R argument:

ctest -R bitd-agent

This command will run all tests with labels containing bitd-agent as substring. To run all tests except those matchin the substring long in the test label:

ctest -E long

These commands will work on all platforms except on Win32 mingw builds, where you must put /usr/x86_64-w64-mingw32/sys-root/mingw/bin in the PATH:

export PATH=/usr/x86_64-w64-mingw32/sys-root/mingw/bin:$PATH
make test
ctest -R bitd-agent
ctest -E long

Test labels contain bitd-agent when the program tested is the bitd-agent itself. Executing all bitd-agent tests will cover test modules as well as the bitd-agent itself. Blocking tests that take multiple seconds to run contain long in the label, and can be skipped if a quick sanity check test run is desired.

1.3. Install precompiled packages

At this point, Bitdribble packages must be manually compiled. Precompiled Bitdribble packages are not available. When an rpm or deb package has been compiled, install it with the usual rpm and dpkg commands, then enable and start the bitd service.

sudo systemctl enable bitd
sudo systemctl start bitd

1.4. Building the docs

Install the sphinx software and its sphinx_rtd_theme. Check out the bitdribble-doc git sandbox, cd to bitdribble-doc, and make html. Copy the build/html folder to a web server (or, if you have key-based ssh access to your web server, customize the install make rule so that make install copies the build/html folder to your web server).