1Development
2==========================
3
4Vision and principles
5---------------------------
6
7Consistency and coherence are one of the key characteristics of good software.
8While the reality is never black and white, it is important libcbor
9contributors are working towards the same high-level goal. This document
10attempts to set out the basic principles of libcbor and the rationale behind
11them. If you are contributing to libcbor or looking to evaluate whether libcbor
12is the right choice for your project, it might be worthwhile to skim through the
13section below.
14
15Mission statement
16~~~~~~~~~~~~~~~~~~~~~~
17
18*libcbor* is the compact, full-featured, and safe CBOR library that works
19everywhere.
20
21
22Goals
23~~~~~~~~~~~~~~~~~~~~~~
24
25Standard conformance and full feature support
26^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
27
28Anything the standard allows, libcbor can do.
29
30**Why?** Because conformance and interoperability is the point of defining
31standards. Clients expect the support to be feature-complete and
32there is no significant complexity reduction that can be achieved by slightly
33cutting corners, which means that the incremental cost of full [CBOR standard](https://www.rfc-editor.org/info/std94) support is
34comparatively small over "almost-conformance" seen in many alternatives.
35
36
37Safety
38^^^^^^^^^^^^^^^^^^^^^^
39
40Untrusted bytes from the network are the typical input.
41
42**Why?** Because it is the client expectation. Vast majority of security
43vulnerabilities are violations of contracts -- in other words, bugs -- anyway.
44
45
46Self-containment
47^^^^^^^^^^^^^^^^^^^^^^
48
49libcbor has no runtime dependencies.
50
51**Why?** Because any constraint imposed on libcbor has to be enforced
52transitively, which is difficult and leads to incompatibilities and
53distribution issues, especially in IoT applications.
54
55Portability
56^^^^^^^^^^^^^^^^^^^^^^
57
58If you can compile C for it, libcbor will work there.
59
60**Why?** Lowest-common-denominator solution for system-level and IoT software
61was the original niche of libcbor. Users who rely on libcbor expect future
62updates to work on their target platform.
63
64Stable and predictable API
65^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
66
67libcbor will not break without a warning.
68
69**Why?** `Industry-standard <https://semver.org/>`_ versioning is a basic
70requirement for production-quality software. This is especially relevant in IoT
71environments where updates may be costly.
72
73Performance
74^^^^^^^^^^^^^^^^^^^^^^
75
76libcbor is fast and resource-efficient by design
77
78
79**Why?** Because the main maintainer is an avid hater of slow bloated software.
80Who wouldn't want more bang per their electricity buck?
81
82
83Non-goals
84~~~~~~~~~~~~~~~~~~~~~~
85
86 - Convenience -- libcbor only provides the minimum surface to make it usable
87 - FFI/SWIG/interop support -- libcbor is primarily a C library for C clients
88 - One-off usecases support -- although there are primitives to reuse, the
89   basic
90   assumption is that most clients want most of CBOR features
91
92
93Development dependencies
94---------------------------
95- `CMocka <http://cmocka.org/>`_ (testing)
96- `Python <https://www.python.org/>`_ and `pip <https://pypi.python.org/pypi/pip>`_ (Sphinx platform)
97- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_
98- `Sphinx <http://sphinx-doc.org/>`_ (documentation)
99- There are some `Ruby <https://www.ruby-lang.org/en/>`_ scripts in ``misc``
100- `Valgrind <http://valgrind.org/>`_ (memory correctness & profiling)
101- `GCOV/LCOV <http://ltp.sourceforge.net/coverage/lcov.php>`_ (test coverage)
102- `clang-format`
103
104
105Installing *sphinx*
106~~~~~~~~~~~~~~~~~~~~~~
107
108.. code-block:: bash
109
110  pip install sphinx
111  pip install sphinx_rtd_theme
112  pip install breathe
113  pip install https://github.com/lepture/python-livereload/archive/master.zip
114  pip install sphinx-autobuild
115
116Further instructions on configuring advanced features can be found at `<http://read-the-docs.readthedocs.org/en/latest/install.html>`_.
117
118
119Live preview of docs
120~~~~~~~~~~~~~~~~~~~~~~
121
122.. code-block:: bash
123
124  cd doc
125  make livehtml
126
127
128Set up git hooks
129~~~~~~~~~~~~~~~~~
130
131A catch-all git hook that runs clang-format and automatically refreshes the `GH
132pages <https://pages.github.com/>`_  contents located in ``docs`` can be
133symlinked:
134
135.. code-block:: bash
136
137  ln -sf $(pwd)/misc/hooks/pre-commit .git/hooks
138
139
140Testing and code coverage
141~~~~~~~~~~~~~~~~~~~~~~~~~~~
142
143Please refer to :doc:`tests`
144