mirror of
https://github.com/zeldaret/oot
synced 2026-09-02 10:01:38 -04:00
Dragorn421
6c29db8fa6
* Document an includes style, apply to z_demo.c and z_play.c * "reverse" style includes * bss * clarify what a "main header" is * Update docs/includes.md Co-authored-by: Tharo <tharo10600@gmail.com> * Update docs/includes.md --------- Co-authored-by: Tharo <tharo10600@gmail.com>
63 lines
1.8 KiB
Markdown
63 lines
1.8 KiB
Markdown
# Includes Style Guide
|
|
|
|
## Include what you use
|
|
|
|
We go by "include what you use", which basically means that for any symbol used by a .c file, the .h where that symbol is from must be included.
|
|
|
|
A tool exists to help with this: `apt install iwyu`.
|
|
|
|
This tool (and clangd) understands IWYU pragmas: we currently only make use of `IWYU pragma: export` and `IWYU pragma: begin_exports`/`IWYU pragma: end_exports`.
|
|
|
|
For further details see https://github.com/include-what-you-use/include-what-you-use
|
|
|
|
## Includes ordering
|
|
|
|
The include should be ordered like this and sorted alphabetically within each group:
|
|
|
|
- main header(s) for the system/overlay. That is, the .h file(s) that declare what the .c defines (functions, globals).
|
|
- `versions.h` if needed
|
|
- remaining includes not in this list
|
|
- assets
|
|
- `libc64/*.h`
|
|
- `libu64/*.h`
|
|
- `ultra64.h` if needed
|
|
- libc (files from `include/libc`)
|
|
|
|
This minimizes the chance for headers to not be self-contained.
|
|
|
|
There should be no empty line between groups, except:
|
|
|
|
- after the main .h include(s)
|
|
- before and after assets includes if any
|
|
- in-between assets includes, as needed
|
|
|
|
## Angle brackets vs quotes
|
|
|
|
Use angle brackets for libc includes (files from `include/libc`), and quotes for everything else.
|
|
|
|
Example:
|
|
|
|
```c
|
|
#include "actor.h"
|
|
#include <stddef.h>
|
|
```
|
|
|
|
## Conditional includes
|
|
|
|
Some header files should be conditionally included, for example:
|
|
|
|
```c
|
|
#if PLATFORM_N64
|
|
#include "n64dd.h"
|
|
#endif
|
|
```
|
|
|
|
This should be done when a .h does not make sense to be included for all versions, for example because it provides symbols that a version doesn't even link (include in the spec).
|
|
|
|
A list of such files is:
|
|
|
|
- `cic6105.h` behind `PLATFORM_N64`
|
|
- `inflate.h` behind `PLATFORM_IQUE`
|
|
- `n64dd.h` behind `PLATFORM_N64`
|
|
- `yaz0.h` behind `!PLATFORM_IQUE`
|