1Getting started 2========================== 3 4Pre-built Linux packages are available in most mainstream distributions 5 6**Ubuntu, Debian, etc.**: 7 8.. code-block:: bash 9 10 apt-get install libcbor-dev 11 12**Fedora, openSUSE, etc.**: 13 14.. code-block:: bash 15 16 yum install libcbor-devel 17 18 19**OS X** users can use `Homebrew <http://brew.sh/>`_: 20 21.. code-block:: bash 22 23 brew install libcbor 24 25For other platforms, you will need to compile it from source. 26 27Building & installing libcbor 28------------------------------ 29 30Prerequisites: 31 - C99 compiler 32 - CMake_ 2.8 or newer (might also be called ``cmakesetup``, ``cmake-gui`` or ``ccmake`` depending on the installed version and system) 33 - C build system CMake can target (make, Apple Xcode, MinGW, ...) 34 35.. _CMake: http://cmake.org/ 36 37**Configuration options** 38 39A handful of configuration flags can be passed to `cmake`. The following table lists libcbor compile-time directives and several important generic flags. 40 41======================== ======================================================= ====================== ===================================================================================================================== 42Option Meaning Default Possible values 43------------------------ ------------------------------------------------------- ---------------------- --------------------------------------------------------------------------------------------------------------------- 44``CMAKE_C_COMPILER`` C compiler to use ``cc`` ``gcc``, ``clang``, ``clang-3.5``, ... 45``CMAKE_INSTALL_PREFIX`` Installation prefix System-dependent ``/usr/local/lib``, ... 46``BUILD_SHARED_LIBS`` Build as a shared library ``OFF`` ``ON``, ``OFF`` 47``HUGE_FUZZ`` :doc:`Fuzz test </tests>` with 8GB of data ``OFF`` ``ON``, ``OFF`` 48``SANE_MALLOC`` Assume ``malloc`` will refuse unreasonable allocations ``OFF`` ``ON``, ``OFF`` 49``COVERAGE`` Generate test coverage instrumentation ``OFF`` ``ON``, ``OFF`` 50``WITH_TESTS`` Build unit tests (see :doc:`development`) ``OFF`` ``ON``, ``OFF`` 51======================== ======================================================= ====================== ===================================================================================================================== 52 53The following configuration options will also be defined as macros [#]_ in ``<cbor/common.h>`` and can therefore be used in client code: 54 55======================== ======================================================= ====================== ===================================================================================================================== 56Option Meaning Default Possible values 57------------------------ ------------------------------------------------------- ---------------------- --------------------------------------------------------------------------------------------------------------------- 58``CBOR_PRETTY_PRINTER`` Include a pretty-printing routine ``ON`` ``ON``, ``OFF`` 59``CBOR_BUFFER_GROWTH`` Factor for buffer growth & shrinking ``2`` Decimals > 1 60======================== ======================================================= ====================== ===================================================================================================================== 61 62.. [#] ``ON`` & ``OFF`` will be translated to ``1`` and ``0`` using `cmakedefine <https://cmake.org/cmake/help/v3.2/command/configure_file.html?highlight=cmakedefine>`_. 63 64If you want to pass other custom configuration options, please refer to `<http://www.cmake.org/Wiki/CMake_Useful_Variables>`_. 65 66.. warning:: 67 ``CBOR_CUSTOM_ALLOC`` has been `removed <https://github.com/PJK/libcbor/pull/237>`_. 68 Custom allocators (historically a controlled by a build flag) are always enabled. 69 70**Building using make** 71 72CMake will generate a Makefile and other configuration files for the build. As a rule of thumb, you should configure the 73build *outside of the source tree* in order to keep different configurations isolated. If you are unsure where to 74execute the build, just use a temporary directory: 75 76.. code-block:: bash 77 78 cd $(mktemp -d /tmp/cbor_build.XXXX) 79 80Now, assuming you are in the directory where you want to build, build libcbor as a **static library**: 81 82.. code-block:: bash 83 84 cmake -DCMAKE_BUILD_TYPE=Release path_to_libcbor_dir 85 make cbor 86 87... or as a **dynamic library**: 88 89.. code-block:: bash 90 91 cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON path_to_libcbor_dir 92 make cbor 93 94To install locally: 95 96.. code-block:: bash 97 98 make install 99 100Root permissions are required on most systems when using the default installation prefix. 101 102 103**Portability** 104 105libcbor is highly portable and works on both little- and big-endian systems regardless of the operating system. After building 106on an exotic platform, you might wish to verify the result by running the :doc:`test suite </tests>`. If you encounter any problems, please 107report them to the `issue tracker <https://github.com/PJK/libcbor/issues>`_. 108 109libcbor is known to successfully work on ARM Android devices. Cross-compilation is possible with ``arm-linux-gnueabi-gcc``. 110 111 112Linking with libcbor 113--------------------- 114 115If you include and linker paths include the directories to which libcbor has been installed, compiling programs that uses libcbor requires 116no extra considerations. 117 118You can verify that everything has been set up properly by creating a file with the following contents 119 120.. code-block:: c 121 122 #include <cbor.h> 123 #include <stdio.h> 124 125 int main(int argc, char * argv[]) 126 { 127 printf("Hello from libcbor %s\n", CBOR_VERSION); 128 } 129 130 131and compiling it 132 133.. code-block:: bash 134 135 cc hello_cbor.c -lcbor -o hello_cbor 136 137 138libcbor also comes with `pkg-config <https://wiki.freedesktop.org/www/Software/pkg-config/>`_ support. If you install libcbor with a custom prefix, you can use pkg-config to resolve the headers and objects: 139 140.. code-block:: bash 141 142 cc $(pkg-config --cflags libcbor) hello_cbor.c $(pkg-config --libs libcbor) -o hello_cbor 143 144 145**A note on linkage** 146 147libcbor is primarily intended to be linked statically. The shared library versioning scheme generally follows `SemVer <https://semver.org/>`_, 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" <https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/DynamicLibraries/100-Articles/CreatingDynamicLibraries.html>`_ (OS X): 148 149 - 0.Y for the 0.Y.Z branch. Patches are backwards compatible, minor releases are generally not and require re-compilation of any dependent code. 150 - X for the X.Y.Z stable versions starting 1.X.Y. All minor release of the major version are backwards compatible. 151 152.. warning:: Please note that releases up to and including v0.6.0 `may export misleading .so/.dylib version number <https://github.com/PJK/libcbor/issues/52>`_. 153 154 155Troubleshooting 156--------------------- 157 158**cbor.h not found**: The headers directory is probably not in your include path. First, verify the installation 159location by checking the installation log. If you used make, it will look something like 160 161.. code-block:: text 162 163 ... 164 -- Installing: /usr/local/include/cbor 165 -- Installing: /usr/local/include/cbor/callbacks.h 166 -- Installing: /usr/local/include/cbor/encoding.h 167 ... 168 169Make sure that ``CMAKE_INSTALL_PREFIX`` (if you provided it) was correct. Including the path path during compilation should suffice, e.g.: 170 171.. code-block:: bash 172 173 cc -I/usr/local/include hello_cbor.c -lcbor -o hello_cbor 174 175 176**cannot find -lcbor during linking**: Most likely the same problem as before. Include the installation directory in the 177linker shared path using ``-R``, e.g.: 178 179.. code-block:: bash 180 181 cc -Wl,-rpath,/usr/local/lib -lcbor -o hello_cbor 182 183**shared library missing during execution**: Verify the linkage using ``ldd``, ``otool``, or similar and adjust the compilation directives accordingly: 184 185.. code-block:: text 186 187 ⇒ ldd hello_cbor 188 linux-vdso.so.1 => (0x00007ffe85585000) 189 libcbor.so => /usr/local/lib/libcbor.so (0x00007f9af69da000) 190 libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f9af65eb000) 191 /lib64/ld-linux-x86-64.so.2 (0x00007f9af6be9000) 192 193**compilation failed**: If your compiler supports C99 yet the compilation has failed, please report the issue to the `issue tracker <https://github.com/PJK/libcbor/issues>`_. 194