This directory provides the C++ reference implementation of Fibre. Its home is located here. There's also a standalone repository for this directory here.

Overview

There are two approaches to include Fibre in your project:

Embedding fibre-cpp: Your application's build process includes the source code files of fibre-cpp. Your application uses Fibre's C++ API to interact with Fibre. This is the recommended approach for embedded systems.
Linking to libfibre: Your application links to a separately compiled library libfibre and uses Fibre's C API to interact with this library. You can obtain precompiled binaries on the main project's release page. This is the recommended approach for desktop systems, where you want all backends enabled, because you can avoid the burden of collecting build dependencies. Note: currently only the client role is supported with this approach. That means you can use it to discover and access remote objects but you cannot use it to expose local objects yet.

Configuring fibre-cpp

Various preprocessor defines can be used to customize Fibre:

FIBRE_ENABLE_SERVER={0|1} (default 0): Enable support for exposing objects to remote peers.
FIBRE_ENABLE_CLIENT={0|1} (default 0): Enable support for discovering and using objects exposed by remote peers.
FIBRE_ENABLE_EVENT_LOOP={0|1} (default 0): Enable the builtin event loop implementation. Not supported on all platforms.
FIBRE_ALLOW_HEAP={0|1} (default 0): Allow Fibre to allocate memory on the heap using malloc and free. If this option is disabled only one Fibre instance can be opened. Currently FIBRE_ENABLE_CLIENT (and several other options) cannot be used together with this option.
FIBRE_MAX_LOG_VERBOSITY={0...5} (default 5): The maximum log verbosity that will be compiled into the binary. In embedded systems it's recommended to set this to 0 to reduce binary size. On platforms that support environment variables the actual run time log verbosity can be changed by setting the environment variable FIBRE_LOG={0...5}.
FIBRE_DEFAULT_LOG_VERBOSITY={0...5} (default 5): The default log verbosity that will be used unless overridden by other means (for instance through the environment variables).
FIBRE_ENABLE_LIBUSB_BACKEND={0|1} (default 0): Enable libusb backend for host side USB support. This requires FIBRE_ALLOC_HEAP=1.
FIBRE_ENABLE_TCP_CLIENT_BACKEND={0|1} (default 0): Enable TCP client backend. This requires FIBRE_ALLOC_HEAP=1.
FIBRE_ENABLE_TCP_SERVER_BACKEND={0|1} (default 0): Enable TCP server backend. This requires FIBRE_ALLOC_HEAP=1.

Adding fibre-cpp to your application's build process

If your application uses tup as build system you can directly call the function get_fibre_package() in package.lua as part of your build process. This function spits out a list of code files and compiler flags needed to compile fibre-cpp for a given configuration. Refer to package.lua for more details.

If your application doesn't use tup, you have to manually check which code files you need.

Using fibre-cpp

Currently there's no nice walkthrough for this but here are two applications that you can use as an example:

The ODrive Firmware
The test server

Configuring `libfibre`

A file called tup.config can be placed in this directory to customize the build. See configs for examples.

Compiling `libfibre`

Before you compile libfibre yourself consider if the official releases may be suitable for you instead.

The recommended way for compiling libfibre is using Docker. You can use the same docker container to cross-compile for all supported targets.

However if you're actively developing fibre you may want to compile natively for faster compile times.

Docker

The following example compiles libfibre for the linux-amd64 target. Refer to the "configs/" folder for a list of supported targets. You can also add new targets there but you may need to modify the Dockerfile to include tooling for your new target.

docker build -t fibre-compiler .
docker run -it -v /tmp/build:/build/cpp/build --entrypoint bash fibre-compiler -c "rm -rd /build/cpp/build/*"
docker run -it -v "$(pwd)":/build -v /tmp/build:/build/build -w /build fibre-compiler configs/linux-amd64.config

The output file is now located under /tmp/build/libfibre-linux-amd64.so on your host system.

If something fails you can enter the container interactively with docker run -it -v "$(pwd)":/build -v /tmp/build:/build/build -w /build --entrypoint bash fibre-compiler.

Windows

Download MinGW from here and install it.
Add C:\Program Files\mingw-w64\x86_64-8.1.0-posix-seh-rt_v6-rev0\mingw64\bin (or similar) to your PATH environment variable.
Download the libusb binaries from here and unpack them to third_party/libusb-windows (such that the file third_party/libusb-windows/libusb-1.0.23/MinGW64/static/libusb-1.0.a exists).
Navigate to this directory and run make

Ubuntu

sudo apt-get install libusb-1.0-0-dev
Navigate to this directory and run make

macOS

brew install libusb
Navigate to this directory and run make

Using `libfibre`

The API is documented in libfibre.h.

To compile your application you need to link against the libfibre binary (-L/path/to/libfibre.so) and add "libfibre.h" to your include path under a folder named "fibre", e.g. -I/path/to/fibre-cpp/include.

Notes for Contributors

Fibre currently targets C++11 to maximize compatibility with other projects
Notes on platform independent programming:
- Don't use the keyword interface (defined as a macro on Windows in rpc.h)

README.md

fibre-cpp