Patcher/README.md

Spitfire Patcher

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.

How to Use

1. Place your patch files in the ./patches directory. Example of patch file:

   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:

   ./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:

  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:

  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:

       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 not found, it will add the new preference.
     • Example:

       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:

       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:

       t:copy
       i:/patcher/pre-compile-patches/branding
       o:/browser/branding/official
       

Example Patch Files

t:pref
i:/browser/firefox.js
o:/browser/spitfire.js

-pref("browser.privatebrowsing.autostart", false);
+pref("browser.privatebrowsing.autostart", true);

t:standard
i:/browser/app/profile/firefox.js
o:/browser/app/profile/firefox.js

-MOZ_APP_DISPLAYNAME=Firefox
+MOZ_APP_DISPLAYNAME=Spitfire

t:new
o:/browser/branding/official/new-file.txt

+Welcome to Spitfire Browser Branding.

Summary of Parameters

Parameter	Required	Purpose	Example
i:	Yes	Specifies the input file path.	i:/browser/app/profile/firefox.js
o:	Yes	Specifies the output file path.	o:/browser/app/profile/firefox.js
t:	No	Defines the type of patch.	t:pref, t:standard, t:new, or t:move
+	Yes	Adds a line to the output file.	+MOZ_APP_DISPLAYNAME=Spitfire
-	Yes	Removes a line from the input file.	-MOZ_APP_DISPLAYNAME=Firefox

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.