Skip to content

update documentation #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: 13
Choose a base branch
from
Open

update documentation #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 29 additions & 22 deletions docs/pixel-bringup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,14 @@
# Bringing up a new Pixel device

This guide assumes basic familiarity with Android platform development. You must already have adevtool [installed](../README.md#installation).
This guide assumes basic familiarity with Android platform development.

To install adevtool, download the GrapeheneOS source and run these commands in the root of your tree:

```bash
yarn install --cwd vendor/adevtool/
source script/envsetup.sh
m aapt2
```

This guide is only for initial bringup; see [Generating or updating an existing device](pixel-generate.md) for subsequent updates.

Expand All @@ -10,13 +18,13 @@ All commands that accept stock system images, with the exception of comparison c

## 1. Download factory images

In order to extract proprietary files and other data, you need a copy of the stock ROM for your device. Download the latest factory images package for your device, replacing `raven` with your device's codename:
In order to extract proprietary files and other data, you need a copy of the stock OS for your device. Download the latest factory images package for your device, replacing `DEVICE` with your device's codename and `BUILD_ID` with the one from the [Google Developers Factory Images Page](https://developers.google.com/android/images):

```bash
adevtool download ~/stock_images -d raven
vendor/adevtool/bin/run download vendor/adevtool/dl/ -d DEVICE -b BUILD_ID -t factory
```

The factory images ZIP will be saved in `~/stock_images`. Full OTA packages are not currently supported.
The factory images ZIP will be saved in `vendor/adevtool/dl`.

## 2. Create a config

Expand All @@ -35,27 +43,30 @@ platform:
- device/google/gs101-sepolicy
```

Replace `product_makefile` with the path to your device's product makefile (including the `aosp_` prefix). All Pixel devices use `hardware/google/pixel-sepolicy`, but check your device tree for the device-specific SELinux policies and replace the path accordingly. Most Qualcomm Pixel devices follow a format similar to `device/google/redbull-sepolicy`.
Replace `product_makefile` with the path to your device's product makefile (including the `aosp_` prefix). All Pixel devices use `hardware/google/pixel-sepolicy`, but check your device tree for the device-specific SELinux policies and replace the path accordingly. Most modern Pixel devices follow a format similar to `device/google/redbull-sepolicy`.

You can optionally follow the modular format of existing configs in config/pixel to reuse common Pixel configs as much as possible. This vastly simplifies making all features work, as most parts are the same across all Pixel devices.

## 3. Prepare for reference build

You must disable inline carrier extraction from the GrapheneOS device tree. To do this, just open the relevant device tree and find the inline extraction commit. For an example commit, see [use inline carrier extraction](https://github.com/GrapheneOS/device_google_redbull/commit/d9c30ca9245c7e011441bfc10555f87909f15fbe).

To find missing files, properties, and overlays automatically, adevtool needs a reference build of AOSP to compare with the stock ROM. Navigate to the root of your AOSP tree and generate a vendor module to prepare for this:

```bash
adevtool generate-prep -s ~/stock_images -b sq1d.211205.017 tools/adevtool/config/pixel/raven.yml
sudo vendor/adevtool/bin/run generate-prep -s vendor/adevtool/dl -b BUILD_ID vendor/adevtool/config/DEVICE.yml
chown -R $(logname):$(logname) vendor/
```

Replace `~/stock_images` with the directory containing your factory images package, `sq1d.211205.017` with the build ID, and `raven` with your device's codename. We recommend keeping a copy of adevtool at `tools/adevtool` so the config is easy to find, but you should also adjust the path if your configs are located somewhere else.
Replace `BUILD_ID` with the build ID, and `DEVICE` with your device's codename.

## 4. Attempt to build

After generating the vendor module, build the ROM to get a reference build. Make sure to do a `user` build using the device codename as it appears on the stock ROM (i.e. no `aosp_` prefix; you can build with a different device name and variant later if you want, but the reference build has strict requirements):
After generating the vendor module, build the system with `m` to get a reference build. Make sure to do a `user` build using the device codename as it appears on the stock ROM (i.e. no `aosp_` prefix; you can build with a different device name and variant later if you want, but the reference build has strict requirements):

```bash
lunch raven-user
m installclean
rm -rf out
lunch DEVICE-user
m
```

Expand All @@ -70,7 +81,8 @@ Even when successful, the reference build **will not boot.** That's normal; this
Use the reference build to create a state file, which contains all necessary information from the build:

```bash
adevtool collect-state ~/raven.json -d raven
touch vendor/state/DEVICE.json # you only need this for new bringups
vendor/adevtool/bin/run collect-state vendor/state/DEVICE.json -d DEVICE
```

Once you have a state file, the reference build is no longer necessary, so you can safely discard it.
Expand All @@ -80,28 +92,23 @@ Once you have a state file, the reference build is no longer necessary, so you c
Some privileged apps have special SELinux domains assigned by signing certificate, and the default AOSP certificates don't match. Update the certificates:

```bash
adevtool fix-certs -d raven -s ~/stock_images -b sq1d.211205.017 -p hardware/google/pixel-sepolicy device/google/gs101-sepolicy
vendor/bin/adevtool/run fix-certs -d DEVICE -s vendor/adevtool/dl -b BUILD_ID -p hardware/google/pixel-sepolicy device/google/gs101-sepolicy ...
```

Pass the list of `sepolicy_dirs` in your config as arguments after `-p`.
Pass the list of `sepolicy_dirs` in your config as arguments after `-p`. The above list is just an example

This only needs to be done once as it modifies SELinux policies to update certificates as necessary. You may want to fork the modified repositories.

## 7. Generate vendor module
Please remove your changes to inline carrier extraction from the device tree and follow the instructions in the [GrapheneOS build guide](https://grapheneos.org/build#extracting-vendor-files-for-pixel-devices).

Now that you have a reference state file, generate the actual vendor module:

```bash
adevtool generate-all -s ~/stock_images -c ~/raven.json -b sq1d.211205.017 tools/adevtool/config/pixel/raven.yml
```

## 8. Build the actual ROM
## 8. Build the final system

You can now do an actual ROM build. We recommend doing an engineering build (`eng`) for easier debugging:
You can now do an actual build. We recommend doing a userdebug build (`userdebug`) for easier debugging. Deleting the special state collection build is required to avoid weird behaviour:

```bash
rm -rf out
lunch raven-user
m installclean
m
```

Expand Down
76 changes: 1 addition & 75 deletions docs/pixel-generate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,77 +1,3 @@
# Generating or updating an existing device

This guide assumes basic familiarity with Android platform development. You must already have adevtool [installed](../README.md#installation).

While the focus of this guide is on a single device, examples are also shown for working on multiple devices at the same time. If you're working on multiple devices, many commands can be sped up by adding the `-p` argument to do the work for each device in parallel.

Most commands should be run at the root of your ROM tree, so `aapt2` and other files can be discovered automatically.

All commands that accept stock system images, with the exception of comparison commands (diff-files, diff-props, diff-vintf), support [the source formats listed here](system-source.md).

## 1. Download factory images

In order to extract proprietary files and other data, you need a copy of the stock ROM for your device. Download the latest factory images package for your device, replacing `raven` with your device's codename:

```bash
adevtool download ~/stock_images -d raven

# For multiple devices
adevtool download ~/stock_images -d raven oriole
```

The factory images ZIP will be saved in `~/stock_images`. Full OTA packages are not currently supported.

## 2. Collect state from a reference build

**Skip to [step 3](#3-generate-vendor-module) if you already have a state file. This is a one-time step.**

To find missing files, properties, and overlays automatically, adevtool needs a reference build of AOSP to compare with the stock ROM. Navigate to the root of your AOSP tree and generate a vendor module to prepare for this:

```bash
adevtool generate-prep -s ~/stock_images -b sq1d.211205.017 tools/adevtool/config/pixel/raven.yml

# For multiple devices
adevtool generate-prep -s ~/stock_images -b sq1d.211205.017 tools/adevtool/config/pixel/2021.yml
```

Replace `~/stock_images` with the directory containing your factory images package, `sq1d.211205.017` with the build ID, and `raven` with your device's codename. We recommend keeping a copy of adevtool at `tools/adevtool` so the config is easy to find, but you should also adjust the path if your configs are located somewhere else.

After generating the vendor module, build the ROM to get a reference build. Make sure to do a `user` build using the device codename as it appears on the stock ROM (i.e. no `aosp_` prefix; you can build with a different device name and variant later if you want, but the reference build has strict requirements):

```bash
lunch raven-user
m installclean
m
```

Then use the reference build to create a state file, which contains all necessary information from the build:

```bash
adevtool collect-state ~/raven.json -d raven

# For multiple devices (device_states is a directory)
adevtool collect-state ~/device_states -d raven oriole
```

Once you have a state file, the reference build is no longer necessary, so you can safely discard it.

### For future updates

This step is only necessary across major Android version upgrades (e.g. Android 12 to 13), or occasionally quarterly feature drops for the latest Pixel generation of Pixel devices. It's also necessary when the format of the state file changes, but we try to keep the format stable when possible.

In all other cases, you can reuse the same state file for future updates without needing to do reference builds again. You can also share the file, so other people building for the same device don't need to do their own reference builds.

## 3. Generate vendor module

Now that you have a reference state file, generating the actual vendor module is easy:

```bash
adevtool generate-all -s ~/stock_images -c ~/raven.json -b sq1d.211205.017 tools/adevtool/config/pixel/raven.yml

# For multiple devices
adevtool generate-all -s ~/stock_images -c ~/device_states -b sq1d.211205.017 tools/adevtool/config/pixel/2021.yml
```

Replace `~/raven.json` with the path to your state file if you're building for a single device, or the directory containing your state files if you have multiple devices. Other arguments are the same as in previous steps.

You should now have everything you need to do a full custom ROM build!
Please see pixel-bringup.md and follow steps 1,3-5,7-8