build: Implement patching for the project-local Meson installation

Makefile

@@ -26,9 +26,7 @@ SUBPROJ_DIR := subprojects
 
 MESON_VER := 1.10.0
 MESON_DIR := $(SUBPROJ_DIR)/meson-$(MESON_VER)
-MESON_SUB := $(MESON_DIR)/meson.py
-
-MESON ?= $(MESON_SUB)
+MESON := $(MESON_DIR)/meson.py
 NINJA ?= ninja
 GIT ?= git
 
@@ -130,12 +128,8 @@ distclean:
 
 purge: distclean
 	rm -rf $(SKREW_DIR)
-ifeq ($(MESON),$(MESON_SUB))
 	! test -f $(MESON) || $(MESON) subprojects purge --confirm
 	rm -rf $(MESON_DIR)
-else
-	$(MESON) subprojects purge --confirm
-endif
 
 update: meson skrewup
 	$(MESON) subprojects update || true
@@ -165,13 +159,12 @@ $(ROOT_INI): | $(BUILD)
 $(BUILD):
 	mkdir -p -- $(BUILD)
 
-meson: ;
-ifeq ($(MESON),$(MESON_SUB))
-meson: $(MESON_SUB)
-endif
+meson: $(MESON)
 
-$(MESON_SUB):
+$(MESON):
 	$(GIT) clone --depth=1 -b $(MESON_VER) https://github.com/mesonbuild/meson $(@D)
+	cd $(MESON_DIR) ; find ../packagefiles/meson_patch -name '*.patch' -exec $(GIT) apply {} \;
+	cd $(MESON_DIR) ; $(GIT) add .
 
 skrew: $(SKREW_EXE)
 

docs/meson/patching.md

@@ -0,0 +1,78 @@
+# Patching Meson
+
+We make use of a locally-cloned installation of Meson rather than asking a user
+to install it themselves via a package manager. This enables us to patch Meson
+for features that are slated for an upcoming release or to customize
+functionality that we otherwise find desirable.
+
+## Rules for Patching
+
+1. Patches for features must be applied from a commit from the upstream Meson
+   repository: <https://github.com/mesonbuild/meson>. The content of the patch
+   may be stripped down to remove changes to documentation, automated tests, etc.
+2. When filing a PR to introduce your patch, provide a link to the commit or PR
+   in Meson's upstream repository for tracking.
+3. Patches which add new features *must* have a forward-path for merging into
+   the main Meson release. This ensures that we do not bloat the set of patches
+   that we apply.
+4. Patches for bug-fixes or small changes to functionality suitable for our
+   use-cases do not necessarily need links to upstream commits or PRs. Such
+   changes should be small in scope. This is a bit on the gray side and subject
+   to discretion from the maintainers, but it allows us to make changes to Meson
+   that fit our use-case but may not align with Meson's own goals.
+
+## Fetching a Patch
+
+If you already have a PR filed to the upstream Meson repository, then you may
+use `tools/scripts/fetch_meson_diff.sh` to pull the content of that PR into a
+local patch. The script requires a single argument, which is the GitHub PR
+number.
+
+As an example, the following command would create
+`subprojects/packagefiles/meson_patch/15402.patch`:
+
+```bash
+./tools/scripts/fetch_meson_diff.sh 15402
+```
+
+Before submitting any patches created using this script for review, you must
+give the output file a meaningful name (that is, not just its PR ID). You may
+also want to consider doctoring your patch, if it requires changes that are
+present in the `master` branch of the Meson repository but not in our base
+revision.
+
+## Writing a Patch
+
+Apply your changes to a clean, un-patched copy of the Meson installation.
+
+1. Modify the `Makefile`:
+
+```diff
+$(MESON):
+$(GIT) clone --depth=1 -b $(MESON_VER) https://github.com/mesonbuild/meson $(@D)
+-	cd $(MESON_DIR) ; find ../packagefiles/meson_patch -name '*.patch' -exec $(GIT) apply {} \;
+```
+
+2. Remove your current installation:
+
+```bash
+rm -rf subprojects/meson-*
+```
+
+3. Run `make meson` to re-clone a fresh copy of the current base version.
+4. Make your changes to the checkout and verify that they work as expected with
+   a small toy-example. You likely won't be able to do this with the
+   `pokeplatinum` build itself.
+5. Stage the relevant changes with `git add`, then output them to a patch:
+
+```bash
+git diff HEAD > ../packagefiles/meson_patch/name-of-your-patch.patch
+```
+
+## Additional Considerations
+
+1. Generally, prefix feature-patches with `feat-` and fix-patches with `fix-`.
+   This helps us delineate the purpose of each patch at-a-glance.
+2. Provide a comment as the first line of your patch-file which links to the
+   upstream Meson PR, if any exists. The patch-fetching script will do this for
+   you automatically.

res/battle/meson.build

@@ -2,34 +2,5 @@
 # to the index for the battle particles NARC.
 subdir('particles')
 
-# This generator is shared by both move-specific animations (in the `moves`
-# directory) and common animations (in the `scripts/common_anims` directory).
-battle_anim_script_bin_gen = generator(make_script_bin_sh,
-    arguments: [
-        '-i', relative_source_root / 'include',
-        '-i', relative_source_root / 'asm',
-        '-i', '.' / 'res' / 'text',
-        '-i', '.' / 'res',
-        '-i', '.',
-        '--depfile',
-        '--assembler', arm_none_eabi_gcc_exe.full_path(),
-        '--objcopy', arm_none_eabi_objcopy_exe.full_path(),
-        '@EXTRA_ARGS@',
-        '@INPUT@',
-    ],
-    depends: [
-        text_banks,
-        c_consts_generators,
-        h_headers,
-        battle_particles_narc[1],
-        anim_ncer_narc_files[1],
-        anim_nanr_narc_files[1],
-        anim_ncgr_narc_files[1],
-        anim_nclr_narc_files[1],
-    ],
-    output: '@BASENAME@',
-    depfile: '@BASENAME@.d',
-)
-
 subdir('moves')
 subdir('scripts')

res/battle/moves/meson.build

@@ -97,10 +97,17 @@ anim_scripts_narc = custom_target(anim_scripts_narc_name,
     output: [
         anim_scripts_narc_name,
     ],
-    input: battle_anim_script_bin_gen.process(
+    input: script_bin_gen.process(
         anim_script_srcs,
         extra_args: ['--out-dir', anim_scripts_private_dir, '--parent-dir'],
         preserve_path_from: anim_scripts_root,
+        depends: [
+            battle_particles_narc,
+            anim_ncer_narc_files,
+            anim_nanr_narc_files,
+            anim_ncgr_narc_files,
+            anim_nclr_narc_files,
+        ],
     ),
     command: [
         nitroarc_exe,

res/battle/scripts/common_anims/meson.build

@@ -65,9 +65,16 @@ anim_subscripts_narc = custom_target(anim_subscripts_narc_name,
         anim_subscripts_narc_name,
         anim_subscripts_naix_name,
     ],
-    input: battle_anim_script_bin_gen.process(
+    input: script_bin_gen.process(
         anim_subscript_files,
-        extra_args: [ '--out-dir', anim_subscripts_private_dir, ]
+        extra_args: [ '--out-dir', anim_subscripts_private_dir ],
+        depends: [
+            battle_particles_narc,
+            anim_ncer_narc_files,
+            anim_nanr_narc_files,
+            anim_ncgr_narc_files,
+            anim_nclr_narc_files,
+        ],
     ),
     command: [
         nitroarc_exe,

res/field/frontier_scripts/meson.build

@@ -1,32 +1,4 @@
 relative_build_dir = fs.relative_to(meson.current_build_dir(), meson.project_build_root())
-#
-# NOTE: This is a functional copy of script_bin_gen, which is separated from the
-# base generator due to an additional dependency on headers generated for
-# events IDs. Meson unfortunately does not have a clean way to copy an existing
-# object and tweak a single property.
-# WARN: If you update this generator, you should also consider updating its parent
-# in res/meson.build
-frontier_script_bin_gen = generator(make_script_bin_sh,
-    arguments: [
-        '-i', relative_source_root / 'include',
-        '-i', relative_source_root / 'asm',
-        '-i', '.' / 'res' / 'text',
-        '-i', '.' / 'res',
-        '-i', '.',
-        '--depfile',
-        '--assembler', arm_none_eabi_gcc_exe.full_path(),
-        '--objcopy', arm_none_eabi_objcopy_exe.full_path(),
-        '@EXTRA_ARGS@',
-        '@INPUT@',
-    ],
-    depends: [
-        c_consts_generators,
-        frontier_particles_narc[1],
-        text_banks,
-    ],
-    output: '@BASENAME@',
-    depfile: '@BASENAME@.d',
-)
 
 fr_script_target_name = 'fr_script.narc'
 fr_script_private_dir = relative_build_dir / fr_script_target_name + '.p'
@@ -37,23 +9,27 @@ fr_script_narc = custom_target('fr_script.narc',
         'fr_script.naix',
     ],
     input: [
-        frontier_script_bin_gen.process(files(
-            'frontier_scripts_battle_castle.s',
-            'frontier_scripts_battle_factory.s',
-            'frontier_scripts_battle_hall.s',
-            'frontier_scripts_battle_arcade.s',
-        ), extra_args: ['--out-dir', fr_script_private_dir]),
-        copy_gen.process(files(
-            'frontier_scripts_unused_04.bin',
-            'frontier_scripts_unused_05.bin',
-        )),
-        script_bin_gen.process(files(
-            'frontier_scripts_battle_tower_corridor.s',
-            'frontier_scripts_battle_tower_corridor_multi.s',
-            'frontier_scripts_battle_tower_battle_room.s',
-            'frontier_scripts_battle_tower_multi_battle_room.s',
-            'frontier_scripts_unknown_10.s',
-        ), extra_args: ['--out-dir', fr_script_private_dir]),
+        script_bin_gen.process(
+            files(
+                'frontier_scripts_battle_castle.s',
+                'frontier_scripts_battle_factory.s',
+                'frontier_scripts_battle_hall.s',
+                'frontier_scripts_battle_arcade.s',
+                'frontier_scripts_battle_tower_corridor.s',
+                'frontier_scripts_battle_tower_corridor_multi.s',
+                'frontier_scripts_battle_tower_battle_room.s',
+                'frontier_scripts_battle_tower_multi_battle_room.s',
+                'frontier_scripts_unknown_10.s',
+            ),
+            extra_args: ['--out-dir', fr_script_private_dir],
+            depends: [frontier_particles_narc],
+        ),
+        copy_gen.process(
+            files(
+                'frontier_scripts_unused_04.bin',
+                'frontier_scripts_unused_05.bin',
+            ),
+        ),
     ],
     command: [
         nitroarc_exe,

res/field/scripts/meson.build

@@ -1,34 +1,5 @@
 relative_build_dir = fs.relative_to(meson.current_build_dir(), meson.project_build_root())
 
-# NOTE: This is a functional copy of script_bin_gen, which is separated from the
-# base generator due to an additional dependency on headers generated for
-# events IDs. Meson unfortunately does not have a clean way to copy an existing
-# object and tweak a single property.
-# WARN: If you update this generator, you should also consider updating its parent
-# in res/meson.build
-field_script_bin_gen = generator(make_script_bin_sh,
-    arguments: [
-        '-i', relative_source_root / 'include',
-        '-i', relative_source_root / 'asm',
-        '-i', '.' / 'res' / 'text',
-        '-i', '.' / 'res',
-        '-i', '.',
-        '--depfile',
-        '--assembler', arm_none_eabi_gcc_exe.full_path(),
-        '--objcopy', arm_none_eabi_objcopy_exe.full_path(),
-        '@EXTRA_ARGS@',
-        '@INPUT@',
-    ],
-    depends: [
-        text_banks,
-        c_consts_generators,
-        h_headers,
-        events_headers,
-    ],
-    output: '@BASENAME@',
-    depfile: '@BASENAME@.d',
-)
-
 scr_seq_target_name = 'scr_seq.narc'
 scr_seq_private_dir = relative_build_dir / scr_seq_target_name + '.p'
 
@@ -1164,9 +1135,10 @@ scr_seq_narc = custom_target('scr_seq.narc',
         'scr_seq.narc',
         'scr_seq.naix',
     ],
-    input: field_script_bin_gen.process(
+    input: script_bin_gen.process(
         scr_seq_files,
-        extra_args: ['--depfile', '--out-dir', scr_seq_private_dir]
+        extra_args: ['--depfile', '--out-dir', scr_seq_private_dir],
+        depends: [events_headers],
     ),
     command: [
         nitroarc_exe,

res/meson.build

@@ -89,8 +89,6 @@ relative_source_root = fs.relative_to(meson.project_source_root(), meson.project
 # *breaks* the dependency-chain if any of these files are edited. However, because
 # this generator produces a depfile, the build back-end will still see the correct
 # granular headers on which each input source file depends.
-# WARN: If you update this generator, you should also consider updating its child
-# in res/field/scripts/meson.build
 script_bin_gen = generator(make_script_bin_sh,
     arguments: [
         '-i', relative_source_root / 'include',