rnx-kit/incubator/patcher-rnmacos

@rnx-kit/patcher-rnmacos

🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧

This tool is EXPERIMENTAL - USE WITH CAUTION

Please refer to this issue for the list of wanted improvements. DO NOT use it unless you know what you are doing.

🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧

Context

This tool is an updated & cleaned up version of https://github.com/mganandraj/office-android-patches. This tool was created a few years ago, heavily inspired by patch-package but repurposed to be used locally within the react-native-macos.

There are two core ideas in this tool:

1. you can do some local changes, even across multiple files, then you can save them up in a patch folder for future usage. (via diff)
2. you can reapply all the patch folders that you want via a separate command (via patch)

You can find more details about how it's used by react-native-macos here.

Usage

This tool has mainly two commands, diff and patch. You can find the full list of functionalities by invoking the command npx @rnx-kit/patcher-rnmacos --help.

The commands have an option --log-folder that allows the user to point a folder in which a set of files with different levels of logging will be stored. According to each level of gravity, the files are going to be error.log, all.log, warn.log, and exceptions.log.

diff

This command will take a folder and a "clean-copy" of it (that needs to be separate) to generate a set of patch files that can be applied. The idea is to be able to re-apply the changes programmatically via the other command, patch.

When using this command, you will need to pass a series of parameters to ensure it's successful:

npx @rnx-kit/patcher-rnmacos diff <path-of-folder> <path-of-clean-copy-folder> --patch-name <name-for-patch-folder>

Along with these core options, you might want to pass the following params:

• --inclusion-list-dirs, relative path within the folder with the changes to focus on (instead of having the tool look everywhere inside it)
• --log-folder, path in which to store logs of the execution of this command
• --git-executable and --diff-executable, these by default try to find the Git tool in Windows. So, if you are in a Unix-based solution like macos, you will want to pass something like --git-executable /usr/local/bin/git --diff-executable /usr/local/Cellar/git/2.34.0/libexec/git-core/git-diff

A complete example of this script on macos is the following:

npx @rnx-kit/patcher-rnmacos diff ../../../react-native-macos-main/ ../../../react-native-macos-clean-copy --inclusion-list-dirs ./ReactAndroid --patch-name TEST --log-folder ./logs --git-executable /usr/local/bin/git --diff-executable /usr/local/Cellar/git/2.34.0/libexec/git-core/git-diff

A more complete explanation of all the params can be found via npx @rnx-kit/patcher-rnmacos diff --help.

patch

This command allows to apply to the codebase all the various folder patches (via their names) - like so:

npx @rnx-kit/patcher-rnmacos patch <path-of-codebase> <array-of-patches-folder-names> --patch-store <path-of-folder-containing-patches> --log-folder <path-to-folder-where-to-store-logs> --confirm true

The --confirm true param at the end is necessary to allow the tool write the changes.

A complete example of this script on macos is the following:

npx @rnx-kit/patcher-rnmacos patch ../../../react-native-macos-main Build OfficeRNHost V8 Focus MAC ImageColor --patch-store ../../../react-native-macos-main/android-patches/patches --log-folder ../../../react-native-macos-main/android-patches/logs --confirm true

A more complete explanation of all the params can be found via npx @rnx-kit/patcher-rnmacos patch --help.

patchfile

This command is similar to patch, but targets a specific file:

patchfile [options] <targetFilePath> <patchFilePath>

A more complete explanation of all the params can be found via npx @rnx-kit/patcher-rnmacos patchfile --help.