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`