Getting started¶
Pre-built Linux packages are distributed from the libcbor website. For other platforms, you will need to compile it from source.
Building & installing libcbor¶
- Prerequisites:
- C11 compiler
- CMake 2.8 or newer (might also be called
cmakesetup
,cmake-gui
orccmake
depending on the installed version and system) - C build system CMake can target (make, Apple Xcode, MinGW, ...)
Note
As of May 2015, the 2015 release candidate of Visual Studio does not support C11. While CMake will be happy to generate a VS solution that you can play with, libcbor currently cannot be compiled using the MSVC toolchain. Both ICC and GCC under Cygwin will work.
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.
Option | Meaning | Default | Possible values |
CMAKE_C_COMPILER |
C compiler to use | cc |
gcc , clang , clang-3.5 , ... |
CMAKE_INSTALL_PREFIX |
Installation prefix | System-dependent | /usr/local/lib , ... |
CUSTOM_ALLOC |
Allow custom malloc ? |
ON |
ON , OFF |
HUGE_FUZZ |
Fuzz test with 8GB of data | OFF |
ON , OFF |
SANE_MALLOC |
Assume malloc will refuse unreasonable allocations |
OFF |
ON , OFF |
COVERAGE |
Generate test coverage instrumentation | OFF |
ON , OFF |
PRETTY_PRINTER |
Include a pretty-printer implementation | ON |
ON , OFF |
BUFFER_GROWTH |
Buffer growth factor | 2 |
>1 |
If you want to pass other custom configuration options, please refer to http://www.cmake.org/Wiki/CMake_Useful_Variables.
Building using make
# Assuming you are in the directory where you want to build
cmake -DCMAKE_BUILD_TYPE=Release path_to_libcbor_dir
make cbor
Both the shared (libcbor.so
) and the static (libcbor.a
) libraries should now be in the src
subdirectory.
In order to install the libcbor headers and libraries, the usual
make install
is what your’re looking for. Root permissions are required on most systems.
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
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 C11 yet the compilation has failed, please report the issue to the issue tracker.