github.com/distbuild/reclient@v0.0.0-20240401075343-3de72e395564/third_party/patches/README.md (about)

     1  # Working with patches
     2  
     3  Patch files are used to apply the changes to repositories imported with Bazel's
     4  [`http_archive`](https://docs.bazel.build/versions/main/repo/http.html) rule.
     5  
     6  ## Generating the patch files
     7  
     8  The patch files are generated with `git diff` command which displays the diff
     9  between the workspace and the last committed version.
    10  
    11  Typical workflow for generating the patch files is described on example of
    12  `llvm` repository below. The repository is imported into reclient WORKSPACE from
    13  https://github.com/llvm/llvm-project/ and
    14  [`settings.bzl`](https://github.com/bazelbuild/reclient/tree/main/settings.bzl)
    15  file defines the commit that should be downloaded.
    16  
    17  To generate the patch file, the user should:
    18  
    19  1.  Clone the remote repository by running `git clone
    20      https://github.com/llvm/llvm-project/`
    21  1.  Checkout the same commit that's imported by reclient (e.g. `git checkout
    22      39e2e3bddbf459d16b00969af1415ebee11fcbdc`)
    23  1.  Make the necessary changes in `llvm-project` repository
    24  1.  Generate the patch file by running `git diff >
    25      <re-client-workspace>/third_party/patches/<patch-name>.patch`
    26  
    27  ## Applying patches
    28  
    29  Patches are applied after `http_archive` extracts the archive. To add the patch
    30  that you'd like to apply, add it to patches argument of the `http_archive` rule.
    31  Example:
    32  
    33  ```
    34  ...
    35  patch_args = ["-p1"],
    36  patches = [
    37          "//third_party/patches/llvm:llvm-status-is-for-dir.patch",
    38  ...
    39  ],
    40  ...
    41  ```
    42  
    43  **Notes:**
    44  
    45  1.  `patch_args = ["-p1"]` is required when applying patch files generated by
    46      `git diff` command. (see
    47      [`http_archive` documentation](https://docs.bazel.build/versions/main/repo/http.html)
    48      for more details).
    49  1.  Patches are applied in the same order as they're declared in the `patches`
    50      argument (`patches = ["//1.patch", "//2.patch"]` may produce different
    51      results than `patches = ["//2.patch", "//1.patch"]`).
    52  
    53  ## Updating the patched repository
    54  
    55  Sometimes, especially after updating the version imported by `http_archive`
    56  rule, applying existing patches may fail. In such cases it's useful to try to
    57  apply the patch in your local repository and manually fix the changes that were
    58  rejected by following steps below (`llvm` repo used as an example):
    59  
    60  1.  Clone the remote repository by running `git clone
    61      https://github.com/llvm/llvm-project/`
    62  1.  Checkout the same commit that's imported by reclient (e.g. `git checkout
    63      39e2e3bddbf459d16b00969af1415ebee11fcbdc`)
    64  1.  Try to apply the patch with `git apply --reject --whitespace=fix
    65      <re-client-workspace>/third_party/patches/<patch-name>.patch`. If the
    66      command failed to apply some of the changes, `<patch-name>.patch.rej` file
    67      will be generated.
    68  1.  Review the content of `<patch-name>.patch.rej` file and apply the changes
    69      manually
    70  1.  Remove `<patch-name>.patch.rej`
    71  1.  Generate updated patch file by running `git diff >
    72      <re-client-workspace>/third_party/patches/<patch-name>.patch`
    73  
    74  **Note:** Please note that the order of patches matters and they should be
    75  applied in the same order that they were declared in the `patches` parameter of
    76  `http_archive` rule.