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