Getting started¶

Pre-built Linux packages are available in most mainstream distributions

Ubuntu, Debian, etc.:

apt-get install libcbor-dev

Fedora, openSUSE, etc.:

yum install libcbor-devel

OS X users can use Homebrew:

brew install libcbor

For other platforms, you will need to compile it from source.

Building & installing libcbor¶

Configuration options

A handful of configuration flags can be passed to cmake. The following table lists libcbor compile-time directives and several important generic flags.

The following configuration options will also be defined as macros [1] in <cbor/common.h> and can therefore be used in client code:

[1]

ON & OFF will be translated to 1 and 0 using cmakedefine.

If you want to pass other custom configuration options, please refer to http://www.cmake.org/Wiki/CMake_Useful_Variables.

WARNING:

Building using make

CMake will generate a Makefile and other configuration files for the build. As a rule of thumb, you should configure the build outside of the source tree in order to keep different configurations isolated. If you are unsure where to execute the build, just use a temporary directory:

cd $(mktemp -d /tmp/cbor_build.XXXX)

Now, assuming you are in the directory where you want to build, build libcbor as a static library:

cmake -DCMAKE_BUILD_TYPE=Release path_to_libcbor_dir
make cbor

... or as a dynamic library:

cmake -DCMAKE_BUILD_TYPE=Release  -DBUILD_SHARED_LIBS=ON path_to_libcbor_dir
make cbor

To install locally:

make install

Root permissions are required on most systems when using the default installation prefix.

Portability

libcbor is highly portable and works on both little- and big-endian systems regardless of the operating system. After building on an exotic platform, you might wish to verify the result by running the test suite. If you encounter any problems, please report them to the issue tracker.

libcbor is known to successfully work on ARM Android devices. Cross-compilation is possible with arm-linux-gnueabi-gcc.

Linking with libcbor¶

If you include and linker paths include the directories to which libcbor has been installed, compiling programs that uses libcbor requires no extra considerations.

You can verify that everything has been set up properly by creating a file with the following contents

#include <cbor.h>
#include <stdio.h>
int main(int argc, char * argv[])
{


    printf("Hello from libcbor %s\n", CBOR_VERSION);
}

and compiling it

cc hello_cbor.c -lcbor -o hello_cbor

libcbor also comes with pkg-config support. If you install libcbor with a custom prefix, you can use pkg-config to resolve the headers and objects:

cc $(pkg-config --cflags libcbor) hello_cbor.c $(pkg-config --libs libcbor) -o hello_cbor

A note on linkage

libcbor is primarily intended to be linked statically. The shared library versioning scheme generally follows SemVer, but is irregular for the 0.X.Y development branch for historical reasons. The following version identifiers are used as a part of the SONAME (Linux) or the dylib "Compatibility version" (OS X):

WARNING:

Troubleshooting¶

cbor.h not found: The headers directory is probably not in your include path. First, verify the installation location by checking the installation log. If you used make, it will look something like

...
-- Installing: /usr/local/include/cbor
-- Installing: /usr/local/include/cbor/callbacks.h
-- Installing: /usr/local/include/cbor/encoding.h
...

Make sure that CMAKE_INSTALL_PREFIX (if you provided it) was correct. Including the path path during compilation should suffice, e.g.:

cc -I/usr/local/include hello_cbor.c -lcbor -o hello_cbor

cannot find -lcbor during linking: Most likely the same problem as before. Include the installation directory in the linker shared path using -R, e.g.:

cc -Wl,-rpath,/usr/local/lib -lcbor -o hello_cbor

shared library missing during execution: Verify the linkage using ldd, otool, or similar and adjust the compilation directives accordingly:

⇒  ldd hello_cbor


    linux-vdso.so.1 =>  (0x00007ffe85585000)


    libcbor.so => /usr/local/lib/libcbor.so (0x00007f9af69da000)


    libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f9af65eb000)


    /lib64/ld-linux-x86-64.so.2 (0x00007f9af6be9000)

compilation failed: If your compiler supports C99 yet the compilation has failed, please report the issue to the issue tracker.

Usage & preliminaries¶

Version information¶

libcbor exports its version using three self-explanatory macros:

The CBOR_VERSION is a string concatenating these three identifiers into one (e.g. 0.2.0).

In order to simplify version comparisons, the version is also exported as

#define CBOR_HEX_VERSION ((CBOR_MAJOR_VERSION << 16) | (CBOR_MINOR_VERSION << 8) | CBOR_PATCH_VERSION)

Since macros are difficult to work with through FFIs, the same information is also available through three uint8_t constants, namely

Headers to include¶

The cbor.h header includes all the symbols. If, for any reason, you don't want to include all the exported symbols, feel free to use just some of the cbor/*.h headers:

Using libcbor¶

If you want to get more familiar with CBOR, we recommend the cbor.io website. Once you get the grasp of what is it CBOR does, the examples (located in the examples directory) should give you a good feel of the API. The API documentation should then provide with all the information you may need.

Creating and serializing items

#include "cbor.h"
#include <stdio.h>
int main(int argc, char * argv[])
{


    /* Preallocate the map structure */


    cbor_item_t * root = cbor_new_definite_map(2);


    /* Add the content */


    cbor_map_add(root, (struct cbor_pair) {


        .key = cbor_move(cbor_build_string("Is CBOR awesome?")),


        .value = cbor_move(cbor_build_bool(true))


    });


    cbor_map_add(root, (struct cbor_pair) {


        .key = cbor_move(cbor_build_uint8(42)),


        .value = cbor_move(cbor_build_string("Is the answer"))


    });


    /* Output: `buffer_size` bytes of data in the `buffer` */


    unsigned char * buffer;


    size_t buffer_size;


    cbor_serialize_alloc(root, &buffer, &buffer_size);


    fwrite(buffer, 1, buffer_size, stdout);


    free(buffer);


    fflush(stdout);


    cbor_decref(&root);
}

Reading serialized data

#include "cbor.h"
#include <stdio.h>
/*


 * Reads data from a file. Example usage:


 * $ ./examples/readfile examples/data/nested_array.cbor


 */
int main(int argc, char * argv[])
{


    FILE * f = fopen(argv[1], "rb");


    fseek(f, 0, SEEK_END);


    size_t length = (size_t)ftell(f);


    fseek(f, 0, SEEK_SET);


    unsigned char * buffer = malloc(length);


    fread(buffer, length, 1, f);


    /* Assuming `buffer` contains `info.st_size` bytes of input data */


    struct cbor_load_result result;


    cbor_item_t * item = cbor_load(buffer, length, &result);


    /* Pretty-print the result */


    cbor_describe(item, stdout);


    fflush(stdout);


    /* Deallocate the result */


    cbor_decref(&item);


    fclose(f);
}

Using the streaming parser

#include "cbor.h"
#include <stdio.h>
#include <string.h>
/*


 * Illustrates how one might skim through a map (which is assumed to have


 * string keys and values only), looking for the value of a specific key


 *


 * Use the examples/data/map.cbor input to test this.


 */
const char * key = "a secret key";
bool key_found = false;
void find_string(void * _ctx, cbor_data buffer, size_t len)
{


    if (key_found) {


        printf("Found the value: %*s\n", (int) len, buffer);


        key_found = false;


    } else if (len == strlen(key)) {


        key_found = (memcmp(key, buffer, len) == 0);


    }
}
int main(int argc, char * argv[])
{


    FILE * f = fopen(argv[1], "rb");


    fseek(f, 0, SEEK_END);


    size_t length = (size_t)ftell(f);


    fseek(f, 0, SEEK_SET);


    unsigned char * buffer = malloc(length);


    fread(buffer, length, 1, f);


    struct cbor_callbacks callbacks = cbor_empty_callbacks;


    struct cbor_decoder_result decode_result;


    size_t bytes_read = 0;


    callbacks.string = find_string;


    while (bytes_read < length) {


        decode_result = cbor_stream_decode(buffer + bytes_read,


                                           length - bytes_read,


                                           &callbacks, NULL);


        bytes_read += decode_result.read;


    }


    fclose(f);
}

API¶

The data API is centered around cbor_item_t, a generic handle for any CBOR item. There are functions to

The single most important thing to keep in mind is: cbor_item_t is an opaque type and should only be manipulated using the appropriate functions! Think of it as an object.

The libcbor API closely follows the semantics outlined by CBOR standard. This part of the documentation provides a short overview of the CBOR constructs, as well as a general introduction to the libcbor API. Remaining reference can be found in the following files structured by data types.

The API is designed to allow both very tight control & flexibility and general convenience with sane defaults. [1] For example, client with very specific requirements (constrained environment, custom application protocol built on top of CBOR, etc.) may choose to take full control (and responsibility) of memory and data structures management by interacting directly with the decoder. Other clients might want to take control of specific aspects (streamed collections, hash maps storage), but leave other responsibilities to libcbor. More general clients might prefer to be abstracted away from all aforementioned details and only be presented complete data structures.

Types of items¶

Every cbor_item_t has a cbor_type associated with it - these constants correspond to the types specified by the CBOR standard:

To find out the type of an item, one can use

WARNING:

Please note the distinction between functions like cbor_isa_uint() and cbor_is_int(). The following functions work solely with the major type value.

Binary queries¶

Alternatively, there are functions to query each particular type.

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

Logical queries¶

These functions provide information about the item type from a more high-level perspective

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

Memory management and reference counting¶

Due to the nature of its domain, libcbor will need to work with heap memory. The stateless decoder and encoder doesn't allocate any memory.

If you have specific requirements, you should consider rolling your own driver for the stateless API.

Using custom allocator¶

libcbor gives you with the ability to provide your own implementations of malloc, realloc, and free. This can be useful if you are using a custom allocator throughout your application, or if you want to implement custom policies (e.g. tighter restrictions on the amount of allocated memory).

cbor_set_allocs(malloc, realloc, free);

Reference counting¶

As CBOR items may require complex cleanups at the end of their lifetime, there is a reference counting mechanism in place. This also enables a very simple GC when integrating libcbor into a managed environment. Every item starts its life (by either explicit creation, or as a result of parsing) with reference count set to 1. When the refcount reaches zero, it will be destroyed.

Items containing nested items will be destroyed recursively - the refcount of every nested item will be decreased by one.

The destruction is synchronous and renders any pointers to items with refcount zero invalid immediately after calling cbor_decref().

WARNING:

WARNING:

WARNING:

Decoding¶

The following diagram illustrates the relationship among different parts of libcbor from the decoding standpoint.

┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                              │
│                                      Client application                                      │
│                                                                                              │
│                                                 ┌────────────────────────────────────────────┘
│                                                 │                     ↕
│                                                 │ ┌──────────────────────────────────────────┐
│                                                 │ │                                          │
│                                                 │ │          Manipulation routines           │
│                                                 │ │                                          │
│           ┌─────────────────────────────────────┘ └──────────────────────────────────────────┘
│           │     ↑    ↑                  ↑                              ↑
│           │     │    │    ┌─────────────╫──────────┬───────────────────┴─┐
│           │     │   CDS   │             ║          │                     │
│           │     │    │   PDS            ║         PDS                   PDS
│           │     ↓    ↓    ↓             ↓          ↓                     ↓
│           │ ┌─────────────────┐   ┌────────────────────┐   ┌────────────────────────────┐
│           │ │                 │   │                    │   │                            │
│           │ │  Custom driver  │ ↔ │  Streaming driver  │ ↔ │       Default driver       │ ↔ CD
│           │ │                 │   │                    │   │                            │
└───────────┘ └─────────────────┘   └────────────────────┘   └────────────────────────────┘


      ↕                ↕                        ↕                           ↕
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                              │
│                            Stateless event─driven decoder                                    │
│                                                                                              │
└──────────────────────────────────────────────────────────────────────────────────────────────┘


              (PSD = Provided Data Structures, CDS = Custom Data Structures)

This section will deal with the API that is labeled as the "Default driver" in the diagram. That is, routines that decode complete libcbor data items

WARNING:

Associated data structures¶

Encoding¶

The easiest way to encode data items is using the cbor_serialize() or cbor_serialize_alloc() functions:

WARNING:

To determine the number of bytes needed to serialize an item, use cbor_serialized_size():

WARNING:

Type-specific serializers¶

In case you know the type of the item you want to serialize beforehand, you can use one of the type-specific serializers.

NOTE:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

Streaming Decoding¶

libcbor exposes a stateless decoder that reads a stream of input bytes from a buffer and invokes user-provided callbacks as it decodes the input:

WARNING:

For example, when cbor_stream_decode() encounters a 1B unsigned integer, it will invoke the function pointer stored in cbor_callbacks.uint8. Complete usage example: examples/streaming_parser.c

The callbacks are defined by

When building custom sets of callbacks, feel free to start from

Callback types definition¶

Streaming Encoding¶

cbor/encoding.h exposes a low-level encoding API to encode CBOR objects on the fly. Unlike cbor_serialize(), these functions take logical values (integers, floats, strings, etc.) instead of cbor_item_t. The client is responsible for constructing the compound types correctly (e.g. terminating arrays).

Streaming encoding is typically used to create an streaming (indefinite length) CBOR strings, byte strings, arrays, and maps. Complete example: examples/streaming_array.c

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

Types 0 & 1 – Positive and negative integers¶

CBOR has two types of integers – positive (which may be effectively regarded as unsigned), and negative. There are four possible widths for an integer – 1, 2, 4, or 8 bytes. These are represented by

Type 0 - positive integers¶

Note: once a positive integer has been created, its width cannot be changed.

Type 1 - negative integers¶

Note: once a positive integer has been created, its width cannot be changed.

Type 0 & 1¶

Due to their largely similar semantics, the following functions can be used for both Type 0 and Type 1 items. One can convert between them freely using the conversion functions.

Actual Type of the integer can be checked using item types API.

An integer item is created with one of the four widths. Because integers' storage is bundled together with the handle, the width cannot be changed over its lifetime.

WARNING:

cbor_item_t * item = cbor_new_int8();
cbor_mark_negint(item);
cbor_set_uint8(0);

Building new items¶

WARNING:

WARNING:

WARNING:

WARNING:

Retrieving values¶

WARNING:

WARNING:

WARNING:

WARNING:

Setting values¶

Dealing with width¶

WARNING:

Dealing with signedness¶

Creating new items¶

WARNING:

WARNING:

WARNING:

WARNING:

Type 2 – Byte strings¶

CBOR byte strings are just (ordered) series of bytes without further interpretation (unless there is a tag). Byte string's length may or may not be known during encoding. These two kinds of byte strings can be distinguished using cbor_bytestring_is_definite() and cbor_bytestring_is_indefinite() respectively.

In case a byte string is indefinite, it is encoded as a series of definite byte strings. These are called "chunks". For example, the encoded item

0xf5            Start indefinite byte string


    0x41        Byte string (1B long)


        0x00


    0x41        Byte string (1B long)


        0xff


    0xff        "Break" control token

represents two bytes, 0x00 and 0xff. This on one hand enables streaming messages even before they are fully generated, but on the other hand it adds more complexity to the client code.

Getting metadata¶

WARNING:

WARNING:

WARNING:

WARNING:

Reading data¶

WARNING:

WARNING:

Creating new items¶

WARNING:

WARNING:

Building items¶

WARNING:

Manipulating existing items¶

WARNING:

Type 3 – UTF-8 strings¶

CBOR strings have the same structure as Type 2 – Byte strings.

UTF-8 encoding validation¶

libcbor considers UTF-8 encoding validity to be a part of the well-formedness notion of CBOR and therefore invalid UTF-8 strings will be rejected by the parser. Strings created by the user are not checked.

Getting metadata¶

WARNING:

WARNING:

WARNING:

WARNING:

Reading data¶

WARNING:

WARNING:

Creating new items¶

WARNING:

WARNING:

Building items¶

WARNING:

Manipulating existing items¶

WARNING:

Type 4 – Arrays¶

CBOR arrays, just like byte strings and strings, can be encoded either as definite, or as indefinite. Definite arrays have a fixed size which is stored in the header, whereas indefinite arrays do not and are terminated by a special "break" byte instead.

Arrays are explicitly created or decoded as definite or indefinite and will be encoded using the corresponding wire representation, regardless of whether the actual size is known at the time of encoding.

NOTE:

Examples¶

0x9f        Start indefinite array


    0x01        Unsigned integer 1


    0xff        "Break" control token

0x9f        Start array, 1B length follows
0x20        Unsigned integer 32


    ...        32 items follow

Getting metadata¶

WARNING:

WARNING:

WARNING:

WARNING:

Reading data¶

WARNING:

WARNING:

Creating new items¶

WARNING:

WARNING:

Modifying items¶

WARNING:

WARNING:

WARNING:

Type 5 – Maps¶

CBOR maps are the plain old associative maps similar JSON objects or Python dictionaries.

Definite maps have a fixed size which is stored in the header, whereas indefinite maps do not and are terminated by a special "break" byte instead.

Map are explicitly created or decoded as definite or indefinite and will be encoded using the corresponding wire representation, regardless of whether the actual size is known at the time of encoding.

NOTE:

WARNING:

Examples¶

0xbf        Start indefinite map (represents {1: 2})


    0x01        Unsigned integer 1 (key)


    0x02        Unsigned integer 2 (value)


    0xff        "Break" control token

0xa0        Map of size 0

Getting metadata¶

WARNING:

WARNING:

WARNING:

WARNING:

Reading data¶

WARNING:

Creating new items¶

WARNING:

WARNING:

Modifying items¶

WARNING:

Type 6 – Semantic tags¶

Tag are additional metadata that can be used to extend or specialize the meaning or interpretation of the other data items.

For example, one might tag an array of numbers to communicate that it should be interpreted as a vector.

Please consult the official IANA repository of CBOR tags before inventing new ones.

WARNING:

WARNING:

WARNING:

Type 7 – Floats & control tokens¶

This type combines two completely unrelated types of items -- floating point numbers and special values such as true, false, null, etc. We refer to these special values as 'control values' or 'ctrls' for short throughout the code.

Just like integers, they have different possible width (resulting in different value ranges and precisions).

Getting metadata¶

WARNING:

WARNING:

Reading data¶

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

Creating new items¶

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

Building items¶

WARNING:

WARNING:

WARNING:

WARNING:

WARNING:

Manipulating existing items¶

Half floats¶

CBOR supports two bytes wide ("half-precision") floats which are not supported by the C language. libcbor represents them using float <https://en.cppreference.com/w/c/language/type> values throughout the API. Encoding will be performed by cbor_encode_half(), which will handle any values that cannot be represented as a half-float.

[1]

http://softwareengineering.vazexqi.com/files/pattern.html

Tests¶

Unit tests¶

There is a comprehensive test suite employing CMocka. You can run all of them using ctest in the build directory. Individual tests are themselves runnable. Please refer to CTest documentation for detailed information on how to specify particular subset of tests.

Testing for memory leaks¶

Every release is tested for memory correctness. You can run these tests by passing the -T memcheck flag to ctest. [1]

[1]

Project should be configured with -DCMAKE_BUILD_TYPE=Debug to obtain meaningful description of location of the leak. You might also need --dsymutil=yes on OS X.

Code coverage¶

Every release is inspected using GCOV/LCOV. Platform-independent code should be fully covered by the test suite. Simply run

make coverage

or alternatively run lcov by hand using

lcov --capture --directory . --output-file coverage.info
genhtml coverage.info --output-directory out

Fuzz testing¶

Every release is tested using a fuzz test. In this test, a huge buffer filled with random data is passed to the decoder. We require that it either succeeds or fail with a sensible error, without leaking any memory. This is intended to simulate real-world situations where data received from the network are CBOR-decoded before any further processing.

RFC conformance¶

libcbor is, generally speaking, very faithful implementation of RFC 7049. There are, however, some limitations imposed by technical constraints.

Bytestring length¶

There is no explicit limitation of indefinite length byte strings. [1] libcbor will not handle byte strings with more chunks than the maximum value of size_t. On any sane platform, such string would not fit in the memory anyway. It is, however, possible to process arbitrarily long strings and byte strings using the streaming decoder.

[1]

https://tools.ietf.org/html/rfc7049#section-2.2.2

"Half-precision" IEEE 754 floats¶

As of C99 and even C11, there is no standard implementation for 2 bytes floats. libcbor packs them as a float <https://en.cppreference.com/w/c/language/type>. When encoding, libcbor selects the appropriate wire representation based on metadata and the actual value. This applies both to canonical and normal mode.

For more information on half-float serialization, please refer to the section on Half floats.

Internal mechanics¶

Internal workings of libcbor are mostly derived from the specification. The purpose of this document is to describe technical choices made during design & implementation and to explicate the reasoning behind those choices.

Terminology¶

Conventions¶

API symbols start with cbor_ or CBOR_ prefix, internal symbols have _cbor_ or _CBOR_ prefix.

Inspiration & related projects¶

Most of the API is largely modelled after existing JSON libraries, including

and also borrowing from

General notes on the API design¶

The API design has two main driving priciples:

Combining these two principles in practice turns out to be quite difficult. Indefinite-length strings, arrays, and maps require client to handle every fixed-size chunk explicitly in order to

Coding style¶

This code loosely follows the Linux kernel coding style. Tabs are tabs, and they are 4 characters wide.

Memory layout¶

CBOR is very dynamic in the sense that it contains many data elements of variable length, sometimes even indefinite length. This section describes internal representation of all CBOR data types.

Generally speaking, data items consist of three parts:

cbor_item_t * item = cbor_new_int8();

+-----------+---------------+---------------+-----------------------------------++-----------+
|           |               |               |                                   ||           |
|   type    |   refcount    |   metadata    |              data                 ||  uint8_t  |
|           |               |               |   (= item + sizeof(cbor_item_t))  ||           |
+-----------+---------------+---------------+-----------------------------------++-----------+
^                                                                                ^
|                                                                                |
+--- item                                                                        +--- item->data

Decoding¶

As outlined in API, there decoding is based on the streaming decoder Essentially, the decoder is a custom set of callbacks for the streaming decoder.

Changelog¶

Template: - [Fix issue X in feature Y](https://github.com/PJK/libcbor/pull/XXX) (by [YYY](https://github.com/YYY))

Next¶

0.10.1 (2022-12-30)¶

0.10.0 (2022-12-29)¶

0.9.0 (2021-11-14)¶

0.8.0 (2020-09-20)¶

0.7.0 (2020-04-25)¶

0.6.1 (2020-03-26)¶

0.6.0 (2020-03-15)¶

0.5.0 (2017-02-06)¶

0.4.0 (2015-12-25)¶

Breaks build & header compatibility due to:

0.3.1 (2015-05-21)¶

0.3.0 (2015-05-21)¶

0.2.1 (2015-05-17)¶

0.2.0 (2015-05-17)¶

0.1.0 (2015-05-06)¶

The initial release, yay!

Development¶

Vision and principles¶

Consistency and coherence are one of the key characteristics of good software. While the reality is never black and white, it is important libcbor contributors are working towards the same high-level goal. This document attempts to set out the basic principles of libcbor and the rationale behind them. If you are contributing to libcbor or looking to evaluate whether libcbor is the right choice for your project, it might be worthwhile to skim through the section below.

Mission statement¶

libcbor is the compact, full-featured, and safe CBOR library that works everywhere.

Goals¶

RFC-conformance and full feature support¶

Anything the standard allows, libcbor can do.

Why? Because conformance and interoperability is the point of defining standards. Clients expect the support to be feature-complete and there is no significant complexity reduction that can be achieved by slightly cutting corners, which means that the incremental cost of full RFC support is comparatively small over "almost-conformance" seen in many alternatives.

Safety¶

Untrusted bytes from the network are the typical input.

Why? Because it is the client expectation. Vast majority of security vulnerabilities are violations of contracts -- in other words, bugs -- anyway.

Self-containment¶

libcbor has no runtime dependencies.

Why? Because any constraint imposed on libcbor has to be enforced transitively, which is difficult and leads to incompatibilities and distribution issues, especially in IoT applications.

Portability¶

If you can compile C for it, libcbor will work there.

Why? Lowest-common-denominator solution for system-level and IoT software was the original niche of libcbor. Users who rely on libcbor expect future updates to work on their target platform.

Stable and predictable API¶

libcbor will not break without a warning.

Why? Industry-standard versioning is a basic requirement for production-quality software. This is especially relevant in IoT environments where updates may be costly.

Performance¶

libcbor is fast and resource-efficient by design

Why? Because the main maintainer is an avid hater of slow bloated software. Who wouldn't want more bang per their electricity buck?

Non-goals¶

Development dependencies¶

Installing sphinx¶

pip install sphinx
pip install sphinx_rtd_theme
pip install breathe
pip install https://github.com/lepture/python-livereload/archive/master.zip
pip install sphinx-autobuild

Further instructions on configuring advanced features can be found at http://read-the-docs.readthedocs.org/en/latest/install.html.

Live preview of docs¶

cd doc
make livehtml

Set up git hooks¶

A catch-all git hook that runs clang-format and automatically refreshes the GH pages contents located in docs can be symlinked:

ln -sf $(pwd)/misc/hooks/pre-commit .git/hooks

Testing and code coverage¶

Please refer to Tests