Patcher/README.md

162 lines
5.7 KiB
Markdown

<p align="center">
<img src="https://weforge.xyz/Spitfire/Branding/raw/branch/main/active/search/icon-alt4.svg" alt="Logo" width="64" height="64">
</p>
<p align="center" style="font-size: 32px;">
<strong>Spitfire Patcher</strong>
</p>
<p align="center">
This is a custom patcher for applying modifications to Firefox source code. It processes patch files located in the `./patches` directory and applies them to files in a specified root path.
</p>
## How to Use
1. Place your patch files in the `./patches` directory. Example of patch file:
```patch
i:/browser/branding/official/configure.sh
o:/browser/branding/official/configure.sh
-MOZ_APP_DISPLAYNAME=Firefox
+MOZ_APP_DISPLAYNAME=Spitfire
```
2. Run the patcher with the `--path` and `--patches` flags:
```sh
./run.sh --path ./mozilla-central/obj-x86_64-pc-linux-gnu/dist/bin --patches ./mozilla-central/patcher/post-compile-patches
```
- --path *Will be resolved to an absolute path, and patches will be applied relative to this path.*
- --patches *Specifies a path to a `.patch` file or a folder containing patches to be applied by this script*
## Parameters Explained
Here are the details of each parameter used in the patching system:
### **`i:` (Input)**
- Specifies the input file to which the patch should be applied.
- This is the file that will be read and modified based on the patch instructions.
- **Example:**
```patch
i:/browser/branding/official/configure.sh
```
- This means the input file is located at `/browser/branding/official/configure.sh`.
### **`o:` (Output)**
- Specifies the output file where the modified content will be saved.
- If the input and output paths are the same, the original file will be overwritten.
- **Example:**
```patch
o:/browser/branding/official/configure.sh
```
- This means the output file is `/browser/branding/official/configure.sh`.
### **`t:` (Type)**
- Defines the type of patch being applied. This parameter can be skipped if not applicable.
- Common types:
1. **`standard`:** Standard patching type that follows the `+` (add) and `-` (remove) syntax.
- Used for general file modifications.
- **Example:**
```patch
i: /browser/branding/official/configure.sh
o: /browser/branding/official/configure.sh
-MOZ_APP_DISPLAYNAME=Firefox
+MOZ_APP_DISPLAYNAME=Spitfire
```
Note: *Type will fallback to t:standard when no type is specified.*
2. **`pref`:** Indicates that the patch is modifying preference settings (e.g., Firefox `prefs.js`).
- When `t:pref` is specified, the script will search for existing preferences in the input file and replace them with the new ones provided in the patch. If a preference is not found, it will be added to the end of the file.
- **Example:**
```patch
t:pref
i:/browser/branding/nightly/pref/firefox-branding.js
o:/browser/branding/nightly/pref/firefox-branding.js
+pref("extensions.getAddons.showPane", false); // HIDDEN
```
3. **`new`:** Used for creating new files or overwriting existing files with specified content.
- Creates a new file at the `o:` location.
- **Example:**
```patch
t:new
o:/browser/branding/official/newfile.txt
+This is a new file created by Spitfire Patcher.
```
4. **`copy`:**: Copies files or directories from the input path to the output path, overwriting if necessary.
- Copies the contents of a file or directory from i: to o:.
- **Example:**
```patch
t:copy
i:/patcher/pre-compile-patches/branding
o:/browser/branding/official
```
5. **`marker`:** Modifies a file relative to a specific marker line.
- A line starting with # defines the marker.
- Lines starting with + are inserted immediately after the marker.
- Lines starting with - are removed from the file (after the marker).
- **Example:**
```patch
t:marker
i:/browser/locales/en-US/firefox-l10n.js
o:/browser/locales/en-US/firefox-l10n.js
#static const RedirEntry kRedirMap[] =
+ {"store", "http://localhost:20351/",
+ nsIAboutModule::ALLOW_SCRIPT |
+ nsIAboutModule::URI_MUST_LOAD_IN_CHILD |
+ nsIAboutModule::URI_CAN_LOAD_IN_PRIVILEGEDABOUT_PROCESS},
```
### Example Patch Files
```patch
t:pref
i:/browser/firefox.js
o:/browser/spitfire.js
+pref("browser.privatebrowsing.autostart", true);
```
```patch
t:standard
i:/browser/app/profile/firefox.js
o:/browser/app/profile/firefox.js
-MOZ_APP_DISPLAYNAME=Firefox
+MOZ_APP_DISPLAYNAME=Spitfire
```
```patch
t:new
o:/browser/branding/official/new-file.txt
+Welcome to Spitfire Browser Branding.
```
### Summary of Parameters
| Parameter | Purpose | Example |
| ----------- | ------------------------------------- | ------------------------------------- |
| `i:` | Specifies the input file path. | `i:/browser/app/profile/firefox.js` |
| `o:` | Specifies the output file path. | `o:/browser/app/profile/firefox.js` |
| `t:` | Defines the type of patch. | `t:pref`, `t:standard`, `t:new`, `t:marker` |
| `+` | Adds a line to the output file. | `+MOZ_APP_DISPLAYNAME=Spitfire` |
| `-` | Removes a line from the input file. | `-MOZ_APP_DISPLAYNAME=Firefox` |
| `#` | Marks a reference line for insertion (used in `marker` type). | `# 'settings',` |
### Workflow
1. **Define Input and Output:** Use `i:` and `o:` to specify which files to read and write.
2. **Specify Patch Type:** Use `t:` for special handling like preference modifications.
3. **Apply Modifications:** Use `+` to add lines and `-` to remove lines.