10ff414c14
git-subtree-dir: contrib/libcbor git-subtree-mainline:293663f4dagit-subtree-split:5b2defbd2a
144 lines
4.2 KiB
ReStructuredText
144 lines
4.2 KiB
ReStructuredText
Development
|
|
==========================
|
|
|
|
Vision and principles
|
|
---------------------------
|
|
|
|
Consistency and coherence are one of the key characteristics of good software.
|
|
While the reality is never black and white, it is important libcbor
|
|
contributors are working towards the same high-level goal. This document
|
|
attempts to set out the basic principles of libcbor and the rationale behind
|
|
them. If you are contributing to libcbor or looking to evaluate whether libcbor
|
|
is the right choice for your project, it might be worthwhile to skim through the
|
|
section below.
|
|
|
|
Mission statement
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
*libcbor* is the compact, full-featured, and safe CBOR library that works
|
|
everywhere.
|
|
|
|
|
|
Goals
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
RFC-conformance and full feature support
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Anything the standard allows, libcbor can do.
|
|
|
|
**Why?** Because conformance and interoperability is the point of defining
|
|
standards. Clients expect the support to be feature-complete and
|
|
there is no significant complexity reduction that can be achieved by slightly
|
|
cutting corners, which means that the incremental cost of full RFC support is
|
|
comparatively small over "almost-conformance" seen in many alternatives.
|
|
|
|
|
|
Safety
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Untrusted bytes from the network are the typical input.
|
|
|
|
**Why?** Because it is the client expectation. Vast majority of security
|
|
vulnerabilities are violations of contracts -- in other words, bugs -- anyway.
|
|
|
|
|
|
Self-containment
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
libcbor has no runtime dependencies.
|
|
|
|
**Why?** Because any constraint imposed on libcbor has to be enforced
|
|
transitively, which is difficult and leads to incompatibilities and
|
|
distribution issues, especially in IoT applications.
|
|
|
|
Portability
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
If you can compile C for it, libcbor will work there.
|
|
|
|
**Why?** Lowest-common-denominator solution for system-level and IoT software
|
|
was the original niche of libcbor. Users who rely on libcbor expect future
|
|
updates to work on their target platform.
|
|
|
|
Stable and predictable API
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
libcbor will not break without a warning.
|
|
|
|
**Why?** `Industry-standard <https://semver.org/>`_ versioning is a basic
|
|
requirement for production-quality software. This is especially relevant in IoT
|
|
environments where updates may be costly.
|
|
|
|
Performance
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
libcbor is fast and resource-efficient by design
|
|
|
|
|
|
**Why?** Because the main maintainer is an avid hater of slow bloated software.
|
|
Who wouldn't want more bang per their electricity buck?
|
|
|
|
|
|
Non-goals
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
- Convenience -- libcbor only provides the minimum surface to make it usable
|
|
- FFI/SWIG/interop support -- libcbor is primarily a C library for C clients
|
|
- One-off usecases support -- although there are primitives to reuse, the
|
|
basic
|
|
assumption is that most clients want most of CBOR features
|
|
|
|
|
|
Development dependencies
|
|
---------------------------
|
|
- `CMocka <http://cmocka.org/>`_ (testing)
|
|
- `Python <https://www.python.org/>`_ and `pip <https://pypi.python.org/pypi/pip>`_ (Sphinx platform)
|
|
- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_
|
|
- `Sphinx <http://sphinx-doc.org/>`_ (documentation)
|
|
- There are some `Ruby <https://www.ruby-lang.org/en/>`_ scripts in ``misc``
|
|
- `Valgrind <http://valgrind.org/>`_ (memory correctness & profiling)
|
|
- `GCOV/LCOV <http://ltp.sourceforge.net/coverage/lcov.php>`_ (test coverage)
|
|
- `clang-format`
|
|
|
|
|
|
Installing *sphinx*
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install sphinx
|
|
pip install sphinx_rtd_theme
|
|
pip install breathe
|
|
pip install https://github.com/lepture/python-livereload/archive/master.zip
|
|
pip install sphinx-autobuild
|
|
|
|
Further instructions on configuring advanced features can be found at `<http://read-the-docs.readthedocs.org/en/latest/install.html>`_.
|
|
|
|
|
|
Live preview of docs
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: bash
|
|
|
|
cd doc
|
|
make livehtml
|
|
|
|
|
|
Set up git hooks
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
A catch-all git hook that runs clang-format and automatically refreshes the `GH
|
|
pages <https://pages.github.com/>`_ contents located in ``docs`` can be
|
|
symlinked:
|
|
|
|
.. code-block:: bash
|
|
|
|
ln -sf $(pwd)/misc/hooks/pre-commit .git/hooks
|
|
|
|
|
|
Testing and code coverage
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Please refer to :doc:`tests`
|