1. Install¶
Table of Contents
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
(leavelibmicrohttpd-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).