Document an includes style, apply to z_demo.c and z_play.c (#2803)

* 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>
2026-09-02 01:52:35 -04:00 · 2026-09-01 18:58:33 +02:00
parent d01089e81a
commit 6c29db8fa6
7 changed files with 162 additions and 47 deletions
@@ -0,0 +1,62 @@
+# 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`
@@ -2,7 +2,7 @@
 #define ACTOR_H

 #include "color.h"
-#include "actor_profile.h"
+#include "actor_profile.h" // IWYU pragma: export
 #include "animation.h"
 #include "z_math.h"
 #include "collision_check.h"
@@ -3,7 +3,7 @@

 #include "ultra64.h"
 #include "alignment.h"
-#include "romfile.h"
+#include "romfile.h" // IWYU pragma: export

 typedef struct DmaRequest {
    /* 0x00 */ uintptr_t    vromAddr; // VROM address (source)
@@ -3,11 +3,14 @@

 #include "ultra64/ultratypes.h"
 #include "ultra64/gbi.h"
+
+// IWYU pragma: begin_exports
 #include "transition_circle.h"
 #include "transition_fade.h"
 #include "transition_triforce.h"
 #include "transition_wipe.h"
 #include "transition_instances.h"
+// IWYU pragma: end_exports

 #define TRANS_TRIGGER_OFF 0 // transition is not active
 #define TRANS_TRIGGER_START 20 // start transition (exiting an area)
@@ -10,9 +10,10 @@
 #include "stdlib.h"
 #include "string.h"

-#include "ultra64/ultratypes.h"
+#include "ultra64/ultratypes.h" // IWYU pragma: export
 #include "unk.h"

+// IWYU pragma: begin_exports
 #include "ultra64/libc.h"
 #include "ultra64/xstdio.h"
 #include "ultra64/exception.h"
@@ -39,6 +40,7 @@
 #include "ultra64/siint.h"
 #include "ultra64/ucode.h"
 #include "ultra64/version.h"
+// IWYU pragma: end_exports

 union uObjBg;

@@ -1,43 +1,61 @@
-#pragma increment_block_number "gc-eu:128 gc-eu-mq:128 gc-jp:128 gc-jp-ce:128 gc-jp-mq:128 gc-us:128 gc-us-mq:128" \
-                               "ique-cn:128 ntsc-1.0:0 ntsc-1.1:0 ntsc-1.2:0 pal-1.0:0 pal-1.1:0"
+#pragma increment_block_number "gc-eu:0 gc-eu-mq:0 gc-jp:0 gc-jp-ce:0 gc-jp-mq:0 gc-us:0 gc-us-mq:0 ique-cn:0" \
+                               "ntsc-1.0:0 ntsc-1.1:0 ntsc-1.2:0 pal-1.0:0 pal-1.1:0"

-#include "libu64/gfxprint.h"
+#include "cutscene.h"
+
+#include "actor.h"
 #include "array_count.h"
+#include "audio.h"
+#include "camera.h"
+#include "color.h"
 #include "controller.h"
+#include "cutscene_flags.h"
+#include "environment.h"
 #include "gfx.h"
 #include "gfxalloc.h"
+#include "interface.h"
+#include "item.h"
 #include "letterbox.h"
+#include "light.h"
 #include "memory_utils.h"
+#include "message.h"
 #if PLATFORM_N64
 #include "n64dd.h"
 #endif
+#include "ocarina.h"
+#include "play_state.h"
+#include "player.h"
 #include "printf.h"
+#include "quake.h"
 #include "regs.h"
 #include "rumble.h"
-#include "quake.h"
+#include "save.h"
+#include "scene.h"
 #include "segmented_address.h"
 #include "seqcmd.h"
 #include "sequence.h"
 #include "sfx.h"
+#include "transition.h"
 #include "translation.h"
 #include "z_lib.h"
-#include "audio.h"
-#include "camera.h"
-#include "cutscene.h"
-#include "cutscene_flags.h"
-#include "ocarina.h"
-#include "play_state.h"
-#include "player.h"
-#include "save.h"
+#include "z_math.h"
+
+#include "assets/scenes/dungeons/bdan/bdan_scene.h"
+#include "assets/scenes/dungeons/ddan/ddan_scene.h"
+#include "assets/scenes/dungeons/ydan/ydan_scene.h"
+#include "assets/scenes/dungeons/ganontika/ganontika_scene.h"
+#include "assets/scenes/dungeons/jyasinboss/jyasinboss_scene.h"
+#include "assets/scenes/dungeons/ice_doukutu/ice_doukutu_scene.h"

 #include "assets/scenes/indoors/tokinoma/tokinoma_scene.h"

+#include "assets/scenes/misc/hakaana_ouke/hakaana_ouke_scene.h"
+
 #include "assets/scenes/overworld/ganon_tou/ganon_tou_scene.h"
 #include "assets/scenes/overworld/spot00/spot00_scene.h"
 #include "assets/scenes/overworld/spot01/spot01_scene.h"
 #include "assets/scenes/overworld/spot02/spot02_scene.h"
 #include "assets/scenes/overworld/spot04/spot04_scene.h"
-#include "assets/scenes/overworld/spot05/spot05_scene.h"
 #include "assets/scenes/overworld/spot06/spot06_scene.h"
 #include "assets/scenes/overworld/spot07/spot07_scene.h"
 #include "assets/scenes/overworld/spot08/spot08_scene.h"
@@ -50,14 +68,11 @@
 #include "assets/scenes/overworld/spot18/spot18_scene.h"
 #include "assets/scenes/overworld/spot20/spot20_scene.h"

-#include "assets/scenes/dungeons/bdan/bdan_scene.h"
-#include "assets/scenes/dungeons/ddan/ddan_scene.h"
-#include "assets/scenes/dungeons/ydan/ydan_scene.h"
-#include "assets/scenes/dungeons/ganontika/ganontika_scene.h"
-#include "assets/scenes/dungeons/jyasinboss/jyasinboss_scene.h"
-#include "assets/scenes/dungeons/ice_doukutu/ice_doukutu_scene.h"
-
-#include "assets/scenes/misc/hakaana_ouke/hakaana_ouke_scene.h"
+#include "libu64/gfxprint.h"
+#include "libu64/pad.h"
+#include "ultra64.h"
+#include <stdbool.h>
+#include <stddef.h>

 u16 sCurTextId = 0;
 u16 sCurOcarinaAction = 0;
@@ -150,7 +165,7 @@ u16 gCamEyePointAppliedFrame;
 u16 gCamAtPointAppliedFrame;

 #pragma increment_block_number "gc-eu:128 gc-eu-mq:128 gc-jp:128 gc-jp-ce:128 gc-jp-mq:128 gc-us:128 gc-us-mq:128" \
-                               "ique-cn:128 ntsc-1.0:128 ntsc-1.1:128 ntsc-1.2:128 pal-1.0:128 pal-1.1:128"
+                               "ique-cn:128 ntsc-1.0:0 ntsc-1.1:0 ntsc-1.2:0 pal-1.0:0 pal-1.1:0"

 // Cam ID to return to when a scripted cutscene is finished
 s16 sReturnToCamId;
@@ -1,54 +1,87 @@
-#include "libc64/malloc.h"
-#include "libc64/qrand.h"
-#include "libu64/debug.h"
+#include "play_state.h"
+
+#include "versions.h"
+#include "actor.h"
+#include "animation.h"
 #include "array_count.h"
+#include "attributes.h"
+#include "audio.h"
+#include "bgcheck.h"
 #include "buffers.h"
+#include "camera.h"
+#include "collision_check.h"
 #include "color.h"
 #include "controller.h"
+#include "cutscene.h"
+#include "cutscene_flags.h"
+#include "debug_display.h"
+#include "dma.h"
+#include "effect.h"
+#include "environment.h"
 #include "fault.h"
 #include "file_select_state.h"
+#include "frame_advance.h"
+#include "game.h"
+#include "game_over.h"
 #include "gfx.h"
 #include "gfxalloc.h"
+#include "interface.h"
+#include "item.h"
 #include "kaleido_manager.h"
 #include "letterbox.h"
+#include "light.h"
 #include "line_numbers.h"
+#include "message.h"
 #if PLATFORM_N64
 #include "n64dd.h"
 #endif
+#include "object.h"
 #include "one_point_cutscene.h"
+#include "pause.h"
+#include "play_state.h"
+#include "player.h"
+#include "prerender.h"
 #include "printf.h"
 #include "quake.h"
 #include "regs.h"
+#include "room.h"
 #include "rumble.h"
+#include "save.h"
+#include "scene.h"
+#include "sched.h"
 #include "segmented_address.h"
 #include "sequence.h"
 #include "sfx.h"
+#include "sfx_source.h"
+#include "skybox.h"
+#include "sram.h"
+#include "stdbool.h"
 #include "sys_math3d.h"
 #include "sys_matrix.h"
 #include "terminal.h"
+#include "tha.h"
 #include "title_setup_state.h"
-#include "transition_circle.h"
-#include "transition_fade.h"
+#include "transition.h"
 #include "transition_tile.h"
-#include "transition_triforce.h"
-#include "transition_wipe.h"
 #include "translation.h"
-#include "versions.h"
-#include "z_actor_dlftbls.h"
-#include "zelda_arena.h"
-#include "audio.h"
-#include "cutscene_flags.h"
-#include "debug_display.h"
-#include "effect.h"
-#include "frame_advance.h"
-#include "light.h"
-#include "play_state.h"
-#include "player.h"
-#include "save.h"
+#include "view.h"
 #include "vis.h"
+#include "z_actor_dlftbls.h"
+#include "z_math.h"
+#include "zelda_arena.h"

-#pragma increment_block_number "gc-eu:218 gc-eu-mq:218 gc-jp:218 gc-jp-ce:218 gc-jp-mq:218 gc-us:218 gc-us-mq:218" \
-                               "ique-cn:218 ntsc-1.0:218 ntsc-1.1:218 ntsc-1.2:218 pal-1.0:218 pal-1.1:218"
+#include "libc64/malloc.h"
+#include "libc64/qrand.h"
+#include "libu64/debug.h"
+#include "libu64/pad.h"
+#include "ultra64.h"
+#include <assert.h>
+#include <math.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#pragma increment_block_number "gc-eu:171 gc-eu-mq:171 gc-jp:171 gc-jp-ce:171 gc-jp-mq:171 gc-us:171 gc-us-mq:171" \
+                               "ique-cn:171 ntsc-1.0:50 ntsc-1.1:50 ntsc-1.2:50 pal-1.0:50 pal-1.1:50"

 TransitionTile gTransitionTile;
 s32 gTransitionTileState;
@@ -63,7 +96,7 @@ s16 sTransitionFillTimer;

 #if DEBUG_FEATURES
 void* gDebugCutsceneScript = NULL;
-UNK_TYPE D_8012D1F4 = 0; // unused
+s32 D_8012D1F4 = 0; // unused
 #endif

 Input* D_8012D1F8 = NULL;