Skip to content

Enhanced cvdr.md documentation #483

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
Asquator wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Enhanced cvdr.md documentation #483

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
66d0d21
Enhanced cvdr.md and added common use cases
Asquator Oct 13, 2025
44e8852
Added newline for clarity
Asquator Oct 13, 2025
5388e2e
Document expected output for successful build
Asquator Oct 25, 2025
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
73 changes: 50 additions & 23 deletions docs/cvdr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,8 @@ remotely.
It wraps [Cloud Orchestrator](cloud_orchestrator.md), to provide user-friendly
interface.

Please run `cvdr --help` for advanced functionalities of `cvdr` not described
below, such as launching Cuttlefish with locally built image.

## Download cvdr
## Install cvdr
### Debian prebuilt packages

`cuttlefish-cvdremote` is available to download via `apt install` with adding
the apt repository at Artifact Registry.
Expand All @@ -29,29 +27,70 @@ sudo apt install cuttlefish-cvdremote
cvdr --help
```

### Manual build

To build `cvdr` manually, please run:
```bash
git clone https://github.com/google/cloud-android-orchestration.git
cd cloud-android-orchestration # Root directory of git repository
go build ./cmd/cvdr
```

## Configure cvdr

Please check and modify the configuration file(`~/.config/cvdr/cvdr.toml`).
Please check and modify the configuration file (defaults to `~/.config/cvdr/cvdr.toml`).
See either
[build/debian/cuttlefish_cvdremote/host/etc/cvdr.toml](/build/debian/cuttlefish_cvdremote/host/etc/cvdr.toml)
or
[scripts/on-premises/single-server/cvdr.toml](/scripts/on-premises/single-server/cvdr.toml)
as examples of how to write a configuration file.

## Use cvdr

Let's assume using the latest Cuttlefish x86_64 image enrolled in
[ci.android.com](https://ci.android.com/).
## Run CVD


```bash
CVDR_USER_CONFIG_PATH=/path/to/cvdr.toml ./cvdr --help
Copy link
Member

@jemoreira jemoreira Oct 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should also make cvdr try to read config files from the default locations when the variables are not defined.

```

## Create CVD examples

### Latest Cuttlefish x86_64 image enrolled in [ci.android.com](https://ci.android.com/)

Please run:
```bash
cvdr \
--branch=aosp-main \
--build_target=aosp_cf_x86_64_phone-trunk_staging-userdebug \
create
```

Then we expect the result like below.
### Custom AOSP build

Ensure you have completed an AOSP build as described in the [docs](https://source.android.com/docs/setup/build/building).
To start a Cuttlefish emulator based on this build, the following environment variables should be defined:
```
export ANDROID_BUILD_TOP=/path/to/your/AOSP/sources/root
export ANDROID_PRODUCT_OUT="${ANDROID_BUILD_TOP}/out/target/product/your_target"
Comment on lines +72 to +73
Copy link
Member

@jemoreira jemoreira Oct 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You shouldn't define these variables yourself, but let the android build system define them for you by running lunch $MY_BUILD_TARGET

```
Replace the latter with the your `OUT_DIR` if you override it.
Copy link
Member

@jemoreira jemoreira Oct 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: typo "the your"


<br>

To automatically fetch the [required images](https://cs.android.com/android/platform/superproject/+/master:device/google/cuttlefish/required_images) from your AOSP root and create an instance, please run:
Copy link
Member

@jemoreira jemoreira Oct 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: We typically use "fetch" when referring to images built in a build server remotely. For this case, please rewrite it as "To create an instance using the [build artifacts](link here) from your local AOSP repo, please run"


```bash
CVDR_USER_CONFIG_PATH=/path/to/cvdr.toml ./cvdr create --local_image
```

Alternatively, manually specify the images and create an instance:
```bash
CVDR_USER_CONFIG_PATH=/path/to/cvdr.toml ./cvdr --local_cvd_host_pkg_src="${ANDROID_PRODUCT_OUT}/dist/cvd-host_package.tar.gz --local_images_zip_src=${ANDROID_PRODUCT_OUT}/dist/your-target-img.zip"
```
For this to work, you have to build the .zip images using `m dist` in AOSP root beforehand.

<br>
On success, we expect the result like below.

```
Creating Host........................................ OK
Fetching main bundle artifacts....................... OK
Expand All @@ -69,16 +108,4 @@ and check if the page seems like below.
Also, you should be able to see the device is enrolled via `adb devices`.
![cvdr_cf_creation](resources/cvdr_cf_creation_example.png)

## Manually build and run cvdr

To build `cvdr` manually, please run:
```bash
git clone https://github.com/google/cloud-android-orchestration.git
cd cloud-android-orchestration # Root directory of git repository
go build ./cmd/cvdr
```

To run `cvdr`, please run:
```bash
CVDR_USER_CONFIG_PATH=/path/to/cvdr.toml ./cvdr --help
```
Please run `cvdr --help` for advanced functionalities of `cvdr`, including individual commands and their flags.