Coding Style Guidelines¶

Order of Includes¶

Headers shall be included at the beginning of .c, .cpp and .h files, right after the file description comment block and, for .h files, the header guard macro. For .cpp files, if the file implements an API declared in a header file, that header file shall be included first in order to ensure it is self-contained.

While the following list is extensive, it documents the expected behaviour defined by the clang-format configuration and tooling should assist with ordering.

The headers shall be grouped and ordered as follows:

1. The header declaring the API being implemented (if any)
2. The C and C++ system and standard library headers
3. Linux kernel headers
4. The libcamera base private header if required
5. The libcamera base library headers
6. The libcamera public API headers
7. The libcamera IPA interfaces
8. The internal libcamera headers
9. Other libraries’ headers, with one group per library
10. Local headers grouped by subdirectory
11. Any local headers

Groups of headers shall be separated by a single blank line. Headers within each group shall be sorted alphabetically.

System and library headers shall be included with angle brackets. Project headers shall be included with angle brackets for the libcamera public API headers, and with double quotes for internal libcamera headers.

Object Ownership¶

libcamera creates and destroys many objects at runtime, for both objects internal to the library and objects exposed to the user. To guarantee proper operation without use after free, double free or memory leaks, knowing who owns each object at any time is crucial. The project has enacted a set of rules to make object ownership tracking as explicit and fool-proof as possible.

In the context of this section, the terms object and instance are used interchangeably and both refer to an instance of a class. The term reference refers to both C++ references and C++ pointers in their capacity to refer to an object. Passing a reference means offering a way to a callee to obtain a reference to an object that the caller has a valid reference to. Borrowing a reference means using a reference passed by a caller without ownership transfer based on the assumption that the caller guarantees the validity of the reference for the duration of the operation that borrows it.

1. Single Owner Objects

   • By default an object has a single owner at any time.

   • Storage of single owner objects varies depending on how the object ownership will evolve through the lifetime of the object.

     • Objects whose ownership needs to be transferred shall be stored as std::unique_ptr<> as much as possible to emphasize the single ownership.
     • Objects whose owner doesn’t change may be embedded in other objects, or stored as pointer or references. They may be stored as std::unique_ptr<> for automatic deletion if desired.

   • Ownership is transferred by passing the reference as a std::unique_ptr<> and using std::move(). After ownership transfer the former owner has no valid reference to the object anymore and shall not access it without first obtaining a valid reference.

   • Objects may be borrowed by passing an object reference from the owner to the borrower, providing that

     • the owner guarantees the validity of the reference for the whole duration of the borrowing, and
     • the borrower doesn’t access the reference after the end of the borrowing.

     When borrowing from caller to callee for the duration of a function call, this implies that the callee shall not keep any stored reference after it returns. These rules apply to the callee and all the functions it calls, directly or indirectly.

     When the object is stored in a std::unique_ptr<>, borrowing passes a reference to the object, not to the std::unique_ptr<>, as

     • a ‘const &’ when the object doesn’t need to be modified and may not be null.
     • a pointer when the object may be modified or may be null. Unless otherwise specified, pointers passed to functions are considered as borrowed references valid for the duration of the function only.

2. Shared Objects

   • Objects that may have multiple owners at a given time are called shared objects. They are reference-counted and live as long as any references to the object exist.
   • Shared objects are created with std::make_shared<> or std::allocate_shared<> and stored in an std::shared_ptr<>.
   • Ownership is shared by creating and passing copies of any valid std::shared_ptr<>. Ownership is released by destroying the corresponding std::shared_ptr<>.
   • When passed to a function, std::shared_ptr<> are always passed by value, never by reference. The caller can decide whether to transfer its ownership of the std::shared_ptr<> with std::move() or retain it. The callee shall use std::move() if it needs to store the shared pointer.
   • Do not over-use std::move(), as it may prevent copy-elision. In particular a function returning a std::shared_ptr<> value shall not use std::move() in its return statements, and its callers shall not wrap the function call with std::move().
   • Borrowed references to shared objects are passed as references to the objects themselves, not to the std::shared_ptr<>, with the same rules as for single owner objects.

These rules match the object ownership rules from the Chromium C++ Style Guide.

Global Variables¶

The order of initializations and destructions of global variables cannot be reasonably controlled. This can cause problems (including segfaults) when global variables depend on each other, directly or indirectly. For example, if the declaration of a global variable calls a constructor which uses another global variable that hasn’t been initialized yet, incorrect behavior is likely. Similar issues may occur when the library is unloaded and global variables are destroyed.

Global variables that are statically initialized and have trivial destructors (such as an integer constant) do not cause any issue. Other global variables shall be avoided when possible, but are allowed when required (for instance to implement factories with auto-registration). They shall not depend on any other global variable, should run a minimal amount of code in the constructor and destructor, and code that contains dependencies should be moved to a later point in time.

Error Handling¶

Proper error handling is crucial to the stability of libcamera. The project follows a set of high-level rules:

• Make errors impossible through API design. The best way to handle errors is to prevent them from happening in the first place. The preferred option is thus to prevent error conditions at the API design stage when possible.
• Detect errors at compile time. Compile-test checking of errors not only reduces the runtime complexity, but also ensures that errors are caught early on during development instead of during testing or, worse, in production. The static_assert() declaration should be used where possible for this purpose.
• Validate all external API contracts. Explicit pre-condition checks shall be used to validate API contracts. Whenever possible, appropriate errors should be returned directly. As libcamera doesn’t use exceptions, errors detected in constructors shall result in the constructed object being marked as invalid, with a public member function available to check validity. The checks should be thorough for the public API, and may be lighter for internal APIs when pre-conditions can reasonably be considered to be met through other means.
• Use assertions for fatal issues only. The ASSERT() macro causes a program abort when compiled in debug mode, and is a no-op otherwise. It is useful to abort execution synchronously with the error check instead of letting the error cause problems (such as segmentation faults) later, and to provide a detailed backtrace. Assertions shall only be used to catch conditions that are never supposed to happen without a serious bug in libcamera that would prevent safe recovery. They shall never be used to validate API contracts. The assertion conditions shall not cause any side effect as they are compiled out in non-debug mode.

C Compatibility Headers¶

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. Code shall not rely on the optional declaration of names in the global or std namespace.

Usage of the C compatibility headers is preferred, except for the math.h header. Where math.h defines separate functions for different argument types (e.g. abs(int), labs(long int), fabs(double) and fabsf(float)) and requires the developer to pick the right function, cmath defines overloaded functions (std::abs(int), std::abs(long int), std::abs(double) and std::abs(float) to let the compiler select the right function. This avoids potential errors such as calling abs(int) with a float argument, performing an unwanted implicit integer conversion. For this reason, cmath is preferred over math.h.