Option to make incbins relative to the src path instead of data path (#…

…378)

* Add use_src_path attribute to incbins

* docs

* changelog and docs

* black

* Update docs/Segments.md

CHANGELOG.md

@@ -1,5 +1,10 @@
 # splat Release Notes
 
+### 0.24.5
+
+* New `use_src_path` option for incbins segments.
+  * Allows to make the generated assembly files relative to the `src_path` directory instead of the default `data_path`.
+
 ### 0.24.4
 
 * New yaml option: `matchings_path`

README.md

@@ -21,7 +21,7 @@ The brackets corresponds to the optional dependencies to install while installin
 If you use a `requirements.txt` file in your repository, then you can add this library with the following line:
 
 ```txt
-splat64[mips]>=0.24.4,<1.0.0
+splat64[mips]>=0.24.5,<1.0.0
 ```
 
 ### Optional dependencies

docs/Segments.md

@@ -275,6 +275,31 @@ While this kind of segment can be represented by other segment types ([`asm`](#a
 - [0x00B250, pad, nops_00B250]
 ```
 
+## incbins
+
+incbin segments correpond to a family of segments used for extracting binary blobs.
+
+Their main advantage over the [`bin`](#bin) segment is the incbins allows to specify a specific section type instead of defaulting to simply `.data`. This is done by generating an assembly file that uses the `.incbin` asm directive to include the binary blob.
+
+Generating assembly files enables better customization of these binaries, like allowing different sections or to define a symbol for the binary blob.
+
+If a known symbol (via a symbol_addrs file) matches the vram of a incbin segment then it will be emitted accordingly at the top. If the symbol contains a [`name_end`](Adding-Symbols.md#name_end) property then it will be emitted after the `.incbin` (useful for Nintendo64's RSP ucodes).
+
+Curretly there are 3 types of incbins, `textbin`, `databin` and `rodatabin`, which are intended for binary blobs of `.text`, `.data` and `.rodata` sections.
+
+If a `textbin` section has a corresponding `databin` and/or `rodatabin` section with the same name then those will be included in the same generated assembly file.
+
+By default the generated assembly file will be written relative to the configured [`data_path`](docs/Configuration.md#data_path). The per segment `use_src_path` option allows to tell splat that a given incbin should be relative to the [`src_path`](docs/Configuration.md#src_path) instead. This behavior can be useful to allow committing those assembly files to the repo since splat will not override them if they already exist, and still extract the binary blobs.
+
+```yaml
+- { start: 0x06C4B0, type: textbin, use_src_path: True, name: rsp/rspboot }
+- [0x06C580, textbin, rsp/aspMain]
+
+# ...
+
+- [0x093D60, databin, rsp/aspMain]
+```
+
 ## PS2 exclusive segments
 
 ### `lit4`

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "splat64"
 # Should be synced with src/splat/__init__.py
-version = "0.24.4"
+version = "0.24.5"
 description = "A binary splitting tool to assist with decompilation and modding projects"
 readme = "README.md"
 license = {file = "LICENSE"}

src/splat/__init__.py

@@ -3,7 +3,7 @@
 __package_name__ = __name__
 
 # Should be synced with pyproject.toml
-__version__ = "0.24.4"
+__version__ = "0.24.5"
 __author__ = "ethteck"
 
 from . import util as util

src/splat/segtypes/common/textbin.py

@@ -7,6 +7,29 @@
 
 
 class CommonSegTextbin(CommonSegment):
+    def __init__(
+        self,
+        rom_start: Optional[int],
+        rom_end: Optional[int],
+        type: str,
+        name: str,
+        vram_start: Optional[int],
+        args: list,
+        yaml,
+    ):
+        super().__init__(
+            rom_start,
+            rom_end,
+            type,
+            name,
+            vram_start,
+            args=args,
+            yaml=yaml,
+        )
+        self.use_src_path: bool = isinstance(yaml, dict) and yaml.get(
+            "use_src_path", False
+        )
+
     @staticmethod
     def is_text() -> bool:
         return True
@@ -18,6 +41,9 @@ def get_section_flags(self) -> Optional[str]:
         return "ax"
 
     def out_path(self) -> Optional[Path]:
+        if self.use_src_path:
+            return options.opts.src_path / self.dir / f"{self.name}.s"
+
         return options.opts.data_path / self.dir / f"{self.name}.s"
 
     def bin_path(self) -> Path: