diff --git a/docs/includes.md b/docs/includes.md new file mode 100644 index 0000000000..50674627fc --- /dev/null +++ b/docs/includes.md @@ -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 +``` + +## 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` diff --git a/include/actor.h b/include/actor.h index c3a9a6de87..08904a20ed 100644 --- a/include/actor.h +++ b/include/actor.h @@ -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" diff --git a/include/dma.h b/include/dma.h index 83a79619c8..f4e4164667 100755 --- a/include/dma.h +++ b/include/dma.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) diff --git a/include/transition.h b/include/transition.h index ae7d329514..ad8a1851b2 100644 --- a/include/transition.h +++ b/include/transition.h @@ -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) diff --git a/include/ultra64.h b/include/ultra64.h index c7607ac921..af38a354af 100644 --- a/include/ultra64.h +++ b/include/ultra64.h @@ -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; diff --git a/src/code/z_demo.c b/src/code/z_demo.c index fb1f3645a7..c92da90417 100644 --- a/src/code/z_demo.c +++ b/src/code/z_demo.c @@ -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 +#include 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; diff --git a/src/code/z_play.c b/src/code/z_play.c index acacb71745..42bf337c95 100644 --- a/src/code/z_play.c +++ b/src/code/z_play.c @@ -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 +#include +#include +#include + +#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;