chromeos-base/nnapi/README.md

# NNAPI Updating Instructions

## Quick Note

If you're just updating code within `platform2/nnapi`, skip down to
[Uprev the ebuild](#uprev-the-ebuild).

## Background

To fully update the NNAPI dependencies, the following repos need
to be addressed:

* `aosp/platform/frameworks/native`
* `aosp/platform/system/core/libcutils`
* `aosp/platform/system/core/libutils`
* `aosp/platform/system/libbase`
* `aosp/platform/system/libfmq`
* `aosp/platform/system/libhidl`
* `aosp/platform/system/logging`

Most of these can be updated by merging the `upstream` branch of the
repo into the `master` branch. There are however, two cases where this
does not apply.

### The Two Copybara Cases

The NNAPI package depends on some repo's that are copybara'd from another
repo.

Specifically, the following repos:

* `aosp/system/core/libcutils`
* `aosp/system/core/libutils`

Are updated by a copybara process from `aosp/platform/system/core`.

You can see the status of this process on the [Copybara dashboard](https://copybara.corp.google.com/list-jobs?piperConfigPath=%2F%2Fdepot%2Fgoogle3%2Fthird_party%2Fcopybara-gsubtreed%2Faosp%2Fcopy.bara.sky).

In short, whenever the `master` branch of `aosp/platform/system/core` is
updated, the copybara process will (at some point in the future), propagate
those changes into `aosp/system/core/libcutils` and
`aosp/system/core/libutils`.

This means that we can't directly control when the downstream repo
will get updated by the copybara process. It is possible that builds of
NNAPI will start failing if the infrastructure tries to uprev NNAPI to
use updated versions of `libcutils` and `libutils` that are possibly
incompatible.

Due avoid this, and ensure we have explicit control over which version of
these copybara'd directories is built, we have introduced
CROS_WORKON_MANUAL_UPREV to the NNAPI package which means we need to
manually update the commit and tree id's of the non-9999 ebuild.
This decouples the updating of `aosp/platform/system/core` from the NNAPI
package.

## Process

### Update the forked repositories

| Repo | Local Dir | Upstream Branch |
| ---- | --------- | --------------- |
| `aosp/platform/frameworks/native` | `aosp/frameworks/native` | `cros/upstream/master` |
| `aosp/platform/system/libbase`    | `aosp/system/libbase` | `cros/upstream/master` |
| `aosp/platform/system/libfmq`     | `aosp/system/libfmq` | `cros/upstream/master` |
| `aosp/platform/system/libhidl`    | `aosp/system/libhidl` | `cros/upstream/master` |
| `aosp/platform/system/logging`    | `aosp/system/logging` | `cros/upstream/master` |

Steps:

1.  Change into the repo local directory
1.  Create a merge branch from `master`
1.  Do a non-ff git merge from the upstream branch into `master`
1.  `repo upload` to gerrit and process the CL as normal
1.  At this stage you don't need to make any code changes due to
    CROS_WORKON_MANUAL_UPREV. The package won't use this updated
    code yet.

Example:

```bash
cd src/aosp/system/libbase
git checkout -b merge cros/master
# This will ask for an appropriate commit msg
git merge cros/upstream/master --no-ff
# This may give you a scary warning about the number of commits. Say 'y'.
repo upload --cbr . --no-verify
```

### Update the aosp/system/core repo

As described earlier, `aosp/system/core/libcutils` and
`aosp/system/core/libutils` are updated by merging upstream into the master
of `aosp/platform/system/core`. This is a bit more involved than the previous
cases, since this repo isn't mapped into the ChromeOS tree. It's quite
similar though...

Steps:

1.  Check out the core repo.
1.  Create a merge branch from `origin/master`.
1.  Do a non-ff git merge from `origin/upstream`.
1.  Upload to gerrit.
1.  Force submit / 'chump' the change since CQ won't process it.
1.  Within a few minutes, copybara should update `libcutils` and `libutils`.
1.  Check the [Copybara dashboard](https://copybara.corp.google.com/list-jobs?piperConfigPath=%2F%2Fdepot%2Fgoogle3%2Fthird_party%2Fcopybara-gsubtreed%2Faosp%2Fcopy.bara.sky).

```bash
cd /tmp
git clone https://chromium.googlesource.com/aosp/platform/system/core
# Set up the commit hooks
cd core
f=`git rev-parse --git-dir`/hooks/commit-msg
mkdir -p $(dirname $f)
curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg
chmod +x $f
# Done setting up the repo
git checkout -b merge
git merge origin/upstream --no-ff
# This will ask for an appropriate commit msg
git commit
# This will upload to gerrit
git push origin HEAD:refs/for/master
```

### Uprev the ebuild

Once you have any code changes and dependencies submitted via CQ, do a
`repo sync` and you'll be able to uprev the ebuild. This is important, since
you will not be able to get the git commit id's you need until this is done.

There is a script in this directory, `get_git_ids.sh` that will print out the
two lines you need to replace.

Steps:

1.  Run `get_git_ids.sh`.
1.  Rename `nnapi-0.0.2-r<N>.ebuild` to `nnapi-0.0.2-r<N+1>.ebuild`.
1.  Replace CROS_WORKON_COMMIT and CROS_WORKON_TREE in that ebuild with the
    output of the `get_gid_ids.sh` script.
1.  Fix any build issues by creating ebuild patches (see the `files` dir).
1.  Upload to gerrit and review as normal.