1# About `external/wayland` 2 3## What this is. 4 5This Android repository contains minimally modified snapshots of official 6release of the core Wayland system code, and its core protocol. It is 7configured to easily build for use in Android projects. 8 9Official home page: <https://wayland.freedesktop.org> 10 11Official source code home: <https://gitlab.freedesktop.org/wayland/wayland.git> 12 13## Changes from the official version 14 15### Android Open Source Metadata 16 17These files should always be present. 18 19- `./LICENSE` (symlinks to COPYING) 20- `./METADATA` 21- `./MODULE_LICENSE_MIT` 22 23Note that `./METADATA` should be updated with the latest version and time 24imported. If using `import_official_snapshot.py`, this will be updated by the 25script automatically. 26 27For further details about these files, refer to 28<https://opensource.google/docs/thirdparty/android#how-to-add-new-third-party-code-to-android> 29 30### Android Build Files 31 32These files are NOT in the official source code, and have been added to make it 33usable in Android. These should always be present, according to the current 34open source rules, and are not really functional changes. 35 36- `./Android.bp` 37 38 The Android Soong blueprint file which builds the libraries. 39 40- `./config.h` 41 42 A fixed `config.h` to use in all Android builds, defining C preprocessor 43 macros for features generally available on the Android platform. 44 45- `./import_official_snapshot.py` 46 47 A helper Python script useful to import updated official versions of the 48 source code, while still preserving all needed Android changes. See below 49 for usage. 50 51- `./wayland-version.h` 52 53 A static expansion of `src/wayland-version.h.in` for the current Wayland 54 version here. If using `./import_official_snapshot.py`, this will be updated 55 by the script automatically. 56 57- `./OWNERS` 58 59 The list of OWNERS for the code here. 60 61- `./PREUPLOAD.cfg` 62 63 A `repo` preupload hook. Mostly just exists to strongly recommend making 64 changes in the AOSP master branch. 65 66- `./README.android.md` 67 68 This document, describing the differences from the official sources, and 69 giving instructions for upgrading. 70 71### Additional patches for Android 72 73These are any additional changes to the Wayland core sources that might be 74helpful for use with the Android platform. 75 76These differences are stored in `./patches/`, and are expected to cleanly apply 77to the current version of Wayland used here. 78 79## Importing a new snapshot 80 81`./import_official_snapshot.py` can be used to automate the work of pulling in 82an updated snapshot. Its only dependencies are a standard Python3 installation, 83along with command-line git. 84 85Usage: 86 87``` 88./import_official_snapshot.py <version-tag> 89``` 90 91For example, to import the "1.18.0" version tag from the official sources: 92 93``` 94./import_official_snapshot.py 1.18.0 95``` 96 97The script will create a new branch based on your current checkout, and commit 98a series of changes to it: 99 100- An inital empty commit with a simple import message. 101 102- A commit removing all existing files, and adding in a clean import of the 103 **CURRENT** version from the official sources. 104 105- A commit adding (back) the various required Android files 106 107- Additional commits for each patch in `./patches/` 108 109The script will then validate that there are no differences between the branch 110start (committed code) and a cleanly-patched import of the current version. If 111there is a difference, it should mean that there is some patch to the code not 112in `./patches`. 113 114Assuming success, the script will continue commiting to the branch: 115 116- A commit removing all existing files, and adding in a clean import of 117 the **NEW** version from the official sources. 118 119- A commit adding (back) the various required Android files, including 120 updating `./METADATA` and `./wayland-version.h`. 121 122- A commit for each patch in `./patches/`, if there are any. 123 124If there were no problems needing manual intervention, the script will then 125execute a final `git rebase -i --autosquash` to squash the CL into a single 126commit for upload review. Otherwise, you should do that squash it to a single 127commit yourself. 128 129There may be failures in applying the patches if there are conflicts, in 130which case they need to be resolved before squashing. Please update the files 131in `./patches/` with the new patches. 132 133Additionally, there may be additional changes needed to `./Android.bp` for 134the client and server libraries to build. 135 136## Adding new patches 137 138Please maintain the list of patch files in `./patches` against the current 139version of Wayland if you make any changes to the official sources. 140 141With no arguments, `./import_official_snapshot.py` will do a clean import of the 142current version, and apply the current list of patches WITHOUT squashing the 143commits involved. 144 145You can then make the changes to the sources, and do a clean reexport of the 146patch files for the last N commits. 147 148``` 149# Remove the current patch files 150git rm patches/* 151 152# Export the last five commits as patches. You should adjust this number. 153git format-patch HEAD~5 --no-stat --numbered --zero-commit --no-signature \ 154 --suffix=.diff --output-directory patches/ 155``` 156 157Create a new commit that adds those same patches, and squash all the commits 158together. You should end up with a commit that makes the changes as well as adds 159the patch file. 160 161If you want, you can then run `./import_official_snapshot.py` again to validate 162that your patch will be applied. If there is a difference, it will be reported. 163 164