110ff414cSEd MasteDevelopment 210ff414cSEd Maste========================== 310ff414cSEd Maste 410ff414cSEd MasteVision and principles 510ff414cSEd Maste--------------------------- 610ff414cSEd Maste 710ff414cSEd MasteConsistency and coherence are one of the key characteristics of good software. 810ff414cSEd MasteWhile the reality is never black and white, it is important libcbor 910ff414cSEd Mastecontributors are working towards the same high-level goal. This document 1010ff414cSEd Masteattempts to set out the basic principles of libcbor and the rationale behind 1110ff414cSEd Mastethem. If you are contributing to libcbor or looking to evaluate whether libcbor 1210ff414cSEd Masteis the right choice for your project, it might be worthwhile to skim through the 1310ff414cSEd Mastesection below. 1410ff414cSEd Maste 1510ff414cSEd MasteMission statement 1610ff414cSEd Maste~~~~~~~~~~~~~~~~~~~~~~ 1710ff414cSEd Maste 1810ff414cSEd Maste*libcbor* is the compact, full-featured, and safe CBOR library that works 1910ff414cSEd Masteeverywhere. 2010ff414cSEd Maste 2110ff414cSEd Maste 2210ff414cSEd MasteGoals 2310ff414cSEd Maste~~~~~~~~~~~~~~~~~~~~~~ 2410ff414cSEd Maste 25*abd87254SEd MasteStandard conformance and full feature support 26*abd87254SEd Maste^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2710ff414cSEd Maste 2810ff414cSEd MasteAnything the standard allows, libcbor can do. 2910ff414cSEd Maste 3010ff414cSEd Maste**Why?** Because conformance and interoperability is the point of defining 3110ff414cSEd Mastestandards. Clients expect the support to be feature-complete and 3210ff414cSEd Mastethere is no significant complexity reduction that can be achieved by slightly 33*abd87254SEd Mastecutting corners, which means that the incremental cost of full [CBOR standard](https://www.rfc-editor.org/info/std94) support is 3410ff414cSEd Mastecomparatively small over "almost-conformance" seen in many alternatives. 3510ff414cSEd Maste 3610ff414cSEd Maste 3710ff414cSEd MasteSafety 3810ff414cSEd Maste^^^^^^^^^^^^^^^^^^^^^^ 3910ff414cSEd Maste 4010ff414cSEd MasteUntrusted bytes from the network are the typical input. 4110ff414cSEd Maste 4210ff414cSEd Maste**Why?** Because it is the client expectation. Vast majority of security 4310ff414cSEd Mastevulnerabilities are violations of contracts -- in other words, bugs -- anyway. 4410ff414cSEd Maste 4510ff414cSEd Maste 4610ff414cSEd MasteSelf-containment 4710ff414cSEd Maste^^^^^^^^^^^^^^^^^^^^^^ 4810ff414cSEd Maste 4910ff414cSEd Mastelibcbor has no runtime dependencies. 5010ff414cSEd Maste 5110ff414cSEd Maste**Why?** Because any constraint imposed on libcbor has to be enforced 5210ff414cSEd Mastetransitively, which is difficult and leads to incompatibilities and 5310ff414cSEd Mastedistribution issues, especially in IoT applications. 5410ff414cSEd Maste 5510ff414cSEd MastePortability 5610ff414cSEd Maste^^^^^^^^^^^^^^^^^^^^^^ 5710ff414cSEd Maste 5810ff414cSEd MasteIf you can compile C for it, libcbor will work there. 5910ff414cSEd Maste 6010ff414cSEd Maste**Why?** Lowest-common-denominator solution for system-level and IoT software 6110ff414cSEd Mastewas the original niche of libcbor. Users who rely on libcbor expect future 6210ff414cSEd Masteupdates to work on their target platform. 6310ff414cSEd Maste 6410ff414cSEd MasteStable and predictable API 6510ff414cSEd Maste^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6610ff414cSEd Maste 6710ff414cSEd Mastelibcbor will not break without a warning. 6810ff414cSEd Maste 6910ff414cSEd Maste**Why?** `Industry-standard <https://semver.org/>`_ versioning is a basic 7010ff414cSEd Masterequirement for production-quality software. This is especially relevant in IoT 7110ff414cSEd Masteenvironments where updates may be costly. 7210ff414cSEd Maste 7310ff414cSEd MastePerformance 7410ff414cSEd Maste^^^^^^^^^^^^^^^^^^^^^^ 7510ff414cSEd Maste 7610ff414cSEd Mastelibcbor is fast and resource-efficient by design 7710ff414cSEd Maste 7810ff414cSEd Maste 7910ff414cSEd Maste**Why?** Because the main maintainer is an avid hater of slow bloated software. 8010ff414cSEd MasteWho wouldn't want more bang per their electricity buck? 8110ff414cSEd Maste 8210ff414cSEd Maste 8310ff414cSEd MasteNon-goals 8410ff414cSEd Maste~~~~~~~~~~~~~~~~~~~~~~ 8510ff414cSEd Maste 8610ff414cSEd Maste - Convenience -- libcbor only provides the minimum surface to make it usable 8710ff414cSEd Maste - FFI/SWIG/interop support -- libcbor is primarily a C library for C clients 8810ff414cSEd Maste - One-off usecases support -- although there are primitives to reuse, the 8910ff414cSEd Maste basic 9010ff414cSEd Maste assumption is that most clients want most of CBOR features 9110ff414cSEd Maste 9210ff414cSEd Maste 9310ff414cSEd MasteDevelopment dependencies 9410ff414cSEd Maste--------------------------- 9510ff414cSEd Maste- `CMocka <http://cmocka.org/>`_ (testing) 9610ff414cSEd Maste- `Python <https://www.python.org/>`_ and `pip <https://pypi.python.org/pypi/pip>`_ (Sphinx platform) 9710ff414cSEd Maste- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ 9810ff414cSEd Maste- `Sphinx <http://sphinx-doc.org/>`_ (documentation) 9910ff414cSEd Maste- There are some `Ruby <https://www.ruby-lang.org/en/>`_ scripts in ``misc`` 10010ff414cSEd Maste- `Valgrind <http://valgrind.org/>`_ (memory correctness & profiling) 10110ff414cSEd Maste- `GCOV/LCOV <http://ltp.sourceforge.net/coverage/lcov.php>`_ (test coverage) 10210ff414cSEd Maste- `clang-format` 10310ff414cSEd Maste 10410ff414cSEd Maste 10510ff414cSEd MasteInstalling *sphinx* 10610ff414cSEd Maste~~~~~~~~~~~~~~~~~~~~~~ 10710ff414cSEd Maste 10810ff414cSEd Maste.. code-block:: bash 10910ff414cSEd Maste 11010ff414cSEd Maste pip install sphinx 11110ff414cSEd Maste pip install sphinx_rtd_theme 11210ff414cSEd Maste pip install breathe 11310ff414cSEd Maste pip install https://github.com/lepture/python-livereload/archive/master.zip 11410ff414cSEd Maste pip install sphinx-autobuild 11510ff414cSEd Maste 11610ff414cSEd MasteFurther instructions on configuring advanced features can be found at `<http://read-the-docs.readthedocs.org/en/latest/install.html>`_. 11710ff414cSEd Maste 11810ff414cSEd Maste 11910ff414cSEd MasteLive preview of docs 12010ff414cSEd Maste~~~~~~~~~~~~~~~~~~~~~~ 12110ff414cSEd Maste 12210ff414cSEd Maste.. code-block:: bash 12310ff414cSEd Maste 12410ff414cSEd Maste cd doc 12510ff414cSEd Maste make livehtml 12610ff414cSEd Maste 12710ff414cSEd Maste 12810ff414cSEd MasteSet up git hooks 12910ff414cSEd Maste~~~~~~~~~~~~~~~~~ 13010ff414cSEd Maste 13110ff414cSEd MasteA catch-all git hook that runs clang-format and automatically refreshes the `GH 13210ff414cSEd Mastepages <https://pages.github.com/>`_ contents located in ``docs`` can be 13310ff414cSEd Mastesymlinked: 13410ff414cSEd Maste 13510ff414cSEd Maste.. code-block:: bash 13610ff414cSEd Maste 13710ff414cSEd Maste ln -sf $(pwd)/misc/hooks/pre-commit .git/hooks 13810ff414cSEd Maste 13910ff414cSEd Maste 14010ff414cSEd MasteTesting and code coverage 14110ff414cSEd Maste~~~~~~~~~~~~~~~~~~~~~~~~~~~ 14210ff414cSEd Maste 14310ff414cSEd MastePlease refer to :doc:`tests` 144