xref: /freebsd/contrib/libcbor/doc/source/getting_started.rst (revision 3332f1b444d4a73238e9f59cca27bfc95fe936bd)
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_CUSTOM_ALLOC``     Enable custom allocator support                           ``OFF``                  ``ON``, ``OFF``
59``CBOR_PRETTY_PRINTER``   Include a pretty-printing routine                         ``ON``                  ``ON``, ``OFF``
60``CBOR_BUFFER_GROWTH``    Factor for buffer growth & shrinking                       ``2``                    Decimals > 1
61========================  =======================================================   ======================  =====================================================================================================================
62
63.. [#] ``ON`` & ``OFF`` will be translated to ``1`` and ``0`` using `cmakedefine <https://cmake.org/cmake/help/v3.2/command/configure_file.html?highlight=cmakedefine>`_.
64
65If you want to pass other custom configuration options, please refer to `<http://www.cmake.org/Wiki/CMake_Useful_Variables>`_.
66
67**Building using make**
68
69CMake will generate a Makefile and other configuration files for the build. As a rule of thumb, you should configure the
70build *outside of the source tree* in order to keep different configurations isolated. If you are unsure where to
71execute the build, just use a temporary directory:
72
73.. code-block:: bash
74
75  cd $(mktemp -d /tmp/cbor_build.XXXX)
76
77Now, assuming you are in the directory where you want to build, build libcbor as a **static library**:
78
79.. code-block:: bash
80
81  cmake -DCMAKE_BUILD_TYPE=Release path_to_libcbor_dir
82  make cbor
83
84... or as a **dynamic library**:
85
86.. code-block:: bash
87
88  cmake -DCMAKE_BUILD_TYPE=Release  -DBUILD_SHARED_LIBS=ON path_to_libcbor_dir
89  make cbor
90
91To install locally:
92
93.. code-block:: bash
94
95  make install
96
97Root permissions are required on most systems when using the default installation prefix.
98
99
100**Portability**
101
102libcbor is highly portable and works on both little- and big-endian systems regardless of the operating system. After building
103on an exotic platform, you might wish to verify the result by running the :doc:`test suite </tests>`. If you encounter any problems, please
104report them to the `issue tracker <https://github.com/PJK/libcbor/issues>`_.
105
106libcbor is known to successfully work on ARM Android devices. Cross-compilation is possible with ``arm-linux-gnueabi-gcc``.
107
108
109Linking with libcbor
110---------------------
111
112If you include and linker paths include the directories to which libcbor has been installed, compiling programs that uses libcbor requires
113no extra considerations.
114
115You can verify that everything has been set up properly by creating a file with the following contents
116
117.. code-block:: c
118
119    #include <cbor.h>
120    #include <stdio.h>
121
122    int main(int argc, char * argv[])
123    {
124        printf("Hello from libcbor %s\n", CBOR_VERSION);
125    }
126
127
128and compiling it
129
130.. code-block:: bash
131
132    cc hello_cbor.c -lcbor -o hello_cbor
133
134
135libcbor 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:
136
137.. code-block:: bash
138
139    cc $(pkg-config --cflags libcbor) hello_cbor.c $(pkg-config --libs libcbor) -o hello_cbor
140
141
142**A note on linkage**
143
144libcbor 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):
145
146  - 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.
147  - X for the X.Y.Z stable versions starting 1.X.Y. All minor release of the major version are backwards compatible.
148
149.. 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>`_.
150
151
152Troubleshooting
153---------------------
154
155**cbor.h not found**: The headers directory is probably not in your include path. First, verify the installation
156location by checking the installation log. If you used make, it will look something like
157
158.. code-block:: text
159
160    ...
161    -- Installing: /usr/local/include/cbor
162    -- Installing: /usr/local/include/cbor/callbacks.h
163    -- Installing: /usr/local/include/cbor/encoding.h
164    ...
165
166Make sure that ``CMAKE_INSTALL_PREFIX`` (if you provided it) was correct. Including the path path during compilation should suffice, e.g.:
167
168.. code-block:: bash
169
170    cc -I/usr/local/include hello_cbor.c -lcbor -o hello_cbor
171
172
173**cannot find -lcbor during linking**: Most likely the same problem as before. Include the installation directory in the
174linker shared path using ``-R``, e.g.:
175
176.. code-block:: bash
177
178    cc -Wl,-rpath,/usr/local/lib -lcbor -o hello_cbor
179
180**shared library missing during execution**: Verify the linkage using ``ldd``, ``otool``, or similar and adjust the compilation directives accordingly:
181
182.. code-block:: text
183
184    ⇒  ldd hello_cbor
185        linux-vdso.so.1 =>  (0x00007ffe85585000)
186        libcbor.so => /usr/local/lib/libcbor.so (0x00007f9af69da000)
187        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f9af65eb000)
188        /lib64/ld-linux-x86-64.so.2 (0x00007f9af6be9000)
189
190**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>`_.
191