Add a new .rst file referencing the documentation contents. This file
is then included in each documentation page so that we can enhance
the Documentation pages on the libcamera website using it. As we do
not want the appearance of the libcamera in-tree Documentation to
change just yet, disable the new class using the sphinx theme's CSS.
To facilitate easier distinguishing between "normal" and
documentation pages on the website we want to add a "documentation"
class to the content of all such pages. Since this new file will be
included on each documentation page it is convenient to add the new
directive here - do so. As the website uses different CSS to
libcamera, move the contents on docs.rst a little so that the
directive at the end of the contents block applies correctly.
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Spaces at end of lines have cropped up in a few places in libcamera.
Remove them.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Milan Zamazal <mzamazal@redhat.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Header guards were replaced by pragma once calls with commits
0a64cf8b76 ("libcamera: Convert to pragma once") through to
796210ecea ("v4l2: Convert to pragma once")
Update the coding style to reflect the updated header guard style.
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
checkstyle.py is ignored too often. Document how to automate its usage
through git commit hooks.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Umang Jain <umang.jain@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Following a conversation on the mailing list about the use of
assertions, document the error handling strategy in libcamera. This is
an initial set of rules that are expected be extended and detailed in
the future.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Utilise the clang-format header sort to provide a regex based pattern
match for our header inclusion coding style.
The rules are updated to match as closely as possible the existing
practices and the documentation is updated accordingly.
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Jean-Michel Hautbois <jeanmichel.hautbois@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Usage of 'method' to refer to member functions comes from Java. The C++
standard uses the term 'function' only. Replace 'method' with 'function'
or 'member function' through the whole code base and documentation.
While at it, fix two typos (s/backeng/backend/).
The BoundMethod and Object::invokeMethod() are left as-is here, and will
be addressed separately.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Paul Elder <paul.elder@ideasonboard.com>
Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Formatting code using astyle doesn't lead to results as good as with
clang-format, and doesn't receive much test coverage as most developers
use clang-format. The code is thus bitrotting. Drop it.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Reviewed-by: Paul Elder <paul.elder@ideasonboard.com>
Document the issue related to global variable dependencies and how to
avoid them.
Signed-off-by: Paul Elder <paul.elder@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
While libcamera prefers usage of the C standard library headers (xxx.h)
over the C++ version (cxxx), we make an exception for cmath as the
overloaded versions of the math functions are convenient. Document this,
and adjust checkstyle.py accordingly.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Due to popular request, move from C++14 to C++17. This will allow
dropping some custom constructs (such as a custom utils::clamp),
benefiting from new language features, and dropping gcc 5 and 6 from the
compilation tests.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
The syntax used for ordered lists is incorrect. Fix it.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
The documentation files are licensed under CC-BY-SA-4.0, but this has
never been specified explicitly. Add corresponding SPDX headers.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
C++14 is a minor release that doesn't introduce major new concepts or
paradigms compared to C++11, but brings two useful changes for us:
- std::make_unique allows dropping our custom implementation in utils.
- Functions returning constexpr are not assumed to be const anymore,
which is needed to create a standard-conformant span implementation.
All the g++ and clang++ versions we support and test (g++-5 onwards and
clang++6 onwards) support C++14. However, due to a defect in the
original C++14 specification, solved in N4387 ([1]), compilation would
fail on g++-5 due to the use of std::map::emplace() with a non-copyable
value type. It turns out we can easily fix it by switching to the
explicit piecewise emplace() overload.
There is thus really nothing holding back the switch. Let's do it, and
update the coding style accordingly.
[1] http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4387
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
The coding style isn't so important that it has to be displayed on the
top contents bar. Move it to the contributing section.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
We follow the Google C++ Style Guide rule on include ordering with a few
tweaks. Document our rule explicitly.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
The C++ standard defines a set of C++ standard library headers, and for
some of them, defines C compatibility headers. The former have a name of
the form <cxxx> while the later are named <xxx.h>. The C++ headers
declare names in the std namespace, and may declare the same names in
the global namespace. The C compatibility headers declare names in the
global namespace, and may declare the same names in the std namespace.
We want to standardise on one set of headers through libcamera, and
don't want to rely on optional behaviour. We can thus either use the C++
headers with an explicit std:: namespace qualifier through the code, or
the C headers without the qualifier.
Both set of headers are defined by the C++ standard, and are thus valid
choices. After weighing pros and cons, we have decided to use the C
compatibility headers, as nobody wanted to write std::uint32_t. Document
this decision.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
The documentation style for the Doxygen comment blocks is inconsistent
in the library. Document the expectations and update all existing
comment blocks to match.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Jacopo Mondi <jacopo@jmondi.org>
Using std::move() on return statement of a method or on the its returned
value prevents the compiler from implementing copy-elision. Discourage
that in the coding style document.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
clang-format produces better results than astyle as it can better match
the libcamera coding style. Default to clang-format over astyle, fall
back to astyle if clang-format isn't found, and add a --formatter
command line option to select a formatter manually.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Object ownership is a complex topic that can lead to many issues, from
memory leak to crashes. Document the rules that libcamera enforces to
make object ownership tracking explicit.
This is a first version of the rules and is expected to be expanded as
the library is developed.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
Add the move semantics (move constructor and move assignment) to the
allowed C++11 features, as we extensively use them for the unique and
shared pointers.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Jacopo Mondi <jacopo@jmondi.org>
We make use of the C++11 variadic templates feature in the signal&slot
implementation, mark it as allowed in the coding style documentation.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Jacopo Mondi <jacopo@jmondi.org>
Add a section to the coding style documentation to explain usage of the
checkstyle.py script.
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
The various lists in the document are not quoted blocks. Don't indent
them.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Jacopo Mondi <jacopo@jmondi.org>
Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
