| Naming C/C++ objects |
| ==================== |
| |
| ## Include paths |
| |
| There are four categories of headers: system, global, library, and |
| implementation. |
| |
| #### System headers |
| |
| ``` |
| #include <zircon/foo/bar.h> |
| ``` |
| |
| ###### Definition |
| |
| These headers define the interface between the kernel and userspace, also known |
| as the vDSO interface. These headers define system calls, included related types |
| and structures. These headers also define some basic C and C++ machinery, for |
| example for crashing in a well-defined sequence. |
| |
| ###### Notes |
| |
| - System headers may be installed under `zircon/`, rather than `lib/zircon/`. |
| - System call wrappers, such as `zx`, are not considered system headers. They |
| are library headers (see below) that depend on the system headers. |
| - Standard system headers (e.g., from the C and C++ standard libraries) have |
| their standard paths. |
| |
| ###### Examples |
| |
| - `#include <zircon/process.h>` |
| - `#include <zircon/syscalls/hypervisor.h>` |
| - `#include <stdint.h>` |
| - `#include <algorithm>` |
| |
| #### Global headers |
| |
| ``` |
| #include <fuchsia/foo/bar.h> |
| ``` |
| |
| ###### Definition |
| |
| These headers define system-wide contracts between userspace components. These |
| headers are generated from FIDL definitions of these contracts. |
| |
| ###### Notes |
| |
| - Hand-written code should be presented in library headers rather than global |
| headers. |
| |
| ###### Examples |
| |
| - `#include <fuchsia/sysmem/cpp/fidl.h>` |
| - `#include <fidl/fuchsia.sysmem/cpp/wire.h>` |
| |
| #### Library headers |
| |
| ``` |
| #include <lib/foo/bar.h> |
| ``` |
| |
| ###### Definition |
| |
| Library headers are hand-written code that are used by applications. The |
| interfaces they define are local to that application. Some libraries are |
| Fuchsia-specific and provide an ergonomic wrapper around some lower-level |
| system facilities. Some libraries might not be tied directly to Fuchsia. |
| |
| ###### Notes |
| |
| - All library headers are in the `lib/` directory to help avoid collisions with |
| other header used by applications. |
| - Headers may not be placed straight under `lib/`. Subdirectories (`lib/foo/`) |
| are mandatory. |
| |
| ###### Examples |
| |
| - `#include <lib/fit/function.h>` |
| - `#include <lib/sys/cpp/component_context.h>` |
| - `#include <lib/zx/event.h>` |
| |
| #### Implementation headers |
| |
| ``` |
| #include "src/foo/bar.h" |
| ``` |
| |
| ###### Definition |
| |
| Implementation headers are internal to the Fuchsia Platform Source Tree. They |
| are never included in SDKs and are referenced by absolute path from the root of |
| the source tree. |
| |
| Tools which generate implementation headers place them in a parallel directory |
| structure within the build directory, and users include them as if they were |
| in the directory where their generation is defined in the build. |
| |
| ###### Notes |
| |
| - Includes of implementation headers use `"` rather than `<` to indicate that |
| the path is relative to the root of the source tree. |
| |
| ###### Examples |
| |
| - `#include "src/ui/scenic/bin/app.h"` |
| - `#include "src/lib/fxl/observer_list.h"` |
| |
| If `fshost_config.h` is generated by a target in |
| `//src/storage/fshost/BUILD.gn`: |
| |
| - `#include "src/storage/fshost/fshost_config.h` |