# oh_utils

**Repository Path**: forantar/oh_utils

## Basic Information

- **Project Name**: oh_utils
- **Description**: Utility scripts for working with `OpenHarmony`.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-07-23
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# About

Provides CLI utilities for `OpenHarmony` development:

- **oh** — automates `OpenHarmony` building pipeline (clone, sync, build, sdk packaging)
- **rk** — manages devices and flashes `dayu200` dev boards and `Huawei Mate` phones

# oh

## Initial setup

Add `oh_utils` to `PATH`:
```bash
export PATH=/path/to/oh_utils:$PATH
```

Run the automated setup to install dependencies:
```bash
oh --setup
```

What it does:
1. Sets up auth credentials (`~/.auth.openlab`) for nexus/npm access
2. Configures the environment (locale, timezone, dash→bash, HOME, ccache, npmrc)
3. Installs `repo` launcher, Python venv, and pip deps
4. Installs `nvm`/`node` and `git-lfs`
5. Installs build apt packages

All the above artifacts are placed in `oh_utils/downloads/`.

Dump env vars or print config:
```bash
oh --dump-env              # dump oh_utils environment variables to be exported
      -f, --force-show-passwords   # show plain passwords
oh --config                # print the oh_utils config
```

Get help (it will generate initial `oh_utils/config`):
```bash
oh --help
```

Edit the generated `config` to meet your needs:
```bash
vi /path/to/oh_utils/config
```

Refer to the `config.template`:
```bash
cat /path/to/oh_utils/config.template
```

## Commands

All flags below are shown by `oh --help`. Flags marked *[global]* may be combined with any command.

### Global flags

| Flag | Description |
|---|---|
| `--dr, --dry-run` | Print requested actions only, do not execute them. |
| `-h, --help` | Print help. |

### Full pipeline

```bash
oh -a, --all           # (default) run the openharmony building pipeline (clone/sync/build etc.)
      -r, --root <path>     # use the existing openharmony root folder (or create new by default)
      -i, --interactive     # ask to perform a particular step
      -l, --label <name>    # add the label to the new openharmony root folder name
```

### Repo management

```bash
oh -i, --init          # init the openharmony repo
      -b, --branch <branch>   # use the branch (default: master)
      -m, --manifest <manifest>   # use the manifest
      -o, --mirror <path>     # use the openharmony git mirror
oh -s, --sync          # sync openharmony repo's
oh -r, --reset         # reset openharmony repo's
oh -l, --lfs           # pull lfs
oh -d, --prebuilts     # download prebuilts
```

### Build

```bash
oh -b, --build <target>   # build target from the list, or by its gn name:
                          #   image | ace | arkoala | sdk | sdk-linux | sdk-windows | sdk-mac
      -f, --fast          # use previously generated ninja files
```

For example, [re]build the `ace_engine` target:
```bash
cd /path/to/openharmony
oh -b ace
```

Build the OpenHarmony SDK for Linux:
```bash
cd /path/to/openharmony
oh -b sdk-linux
```

### SDK packaging and upload

```bash
oh --pack-sdk              # prepare the openharmony SDK archives
```

`--pack-sdk` archives the SDK produced by `--build sdk*` into:
```
out/sdk/ohos-sdk-packages/ohos-sdk-<os>.zip
out/sdk/ohos-sdk-packages/ohos-sdk-<os>.zip.version
```

By default both `windows` and `linux` are packed. To pack a single OS, set the `os_names` env var:
```bash
os_names="linux" oh --pack-sdk
```

Preview the actions without executing:
```bash
os_names="linux" oh --pack-sdk --dry-run
```

### Reporting

```bash
oh --report                # print openharmony build statistics report
oh --log                   # list the oh_utils global log
```

Every `oh` run log can be found in the global log:
```bash
/path/to/oh_utils/.log
# to list it:
oh --log
```

## Configure nightly builds with `cron`

Note that cron runs in the `root` env, so make sure you have the `repo` tool in the root `PATH`:
```bash
sudo which repo
/usr/local/bin/repo
```

```bash
crontab -e
# add the line:
0 4 * * * /path/to/oh_utils/oh -a
```

## `openharmony` git mirror

```bash
sudo oh -cm <root> <branch> [-c] [-s]   # create <root>/oh-mirror-<branch>, optionally add cron or NFS share
sudo oh -um <path>                 # update (sync) an existing mirror
sudo oh -mm <ip>:<path>            # mount an NFS mirror on a client
```

- **`-cm, --create-mirror`** — `repo init --mirror` + `repo sync` + `git lfs pull`
- **`-c, --cron`** (with `-cm`) — add a crontab entry for nightly sync
- **`-s, --share`** (with `-cm`) — export the mirror via NFS to the local subnet
- **`-um, --update-mirror`** — `repo sync` an existing mirror (runs nightly from cron)
- **`-mm, --mount-mirror`** — mount a remote NFS mirror, add `/etc/fstab` entry, print config line

After mounting on a client, set in `config`:
```
OH_MIRROR=/mnt/nfs/oh-mirror-<branch>
```

# rk

## Initial setup

Run the automated setup:

```bash
rk --setup
```

What it does:
1. Sets up auth credentials (`~/.auth.openlab`) for nexus access
2. Clones the `HiHope` repo (flashing tools) and sets `HIHOPE_PATH`
3. Downloads `oh-tool` (latest from nexus)
4. Downloads the `OHOS SDK` via `oh-tool` and sets `HDC_PATH`
5. Installs USB udev rules for device detection

All the above artifacts are placed in `oh_utils/downloads/`.

## Commands

Get help:

```bash
rk --help
```

### Flash

Flash a downloaded image:

```bash
rk -fi /path/to/OpenHarmony_img.tar.gz
# or pick from list:
rk -fi
```

Flash a build artifact:

```bash
rk -fb /path/to/build/dir
# or pick from list:
rk -fb
```

### Device management

```bash
rk -s            # show all connected devices
rk -s -v         # show devices with OS version info
rk -i            # identify device (blink LED / wake screen)
rk -c            # configure device (standby, brightness, language, etc.)
rk -u            # mount device for write
rk -a            # send build artifacts to device (configured in res/artifacts.conf)
```

### Other

```bash
rk -li           # list images from IMAGES_PATH
rk -lb           # list builds from BUILDS_PATH
rk -r            # create and apply udev rules (requires sudo)
rk -t            # show useful tips
```

## Multiple devices

When several boards are connected, target a specific one with `-d, --device <id>`. The id is the
serial reported by `rk -s` (same as `hdc list targets`). For a board in rockusb mode
(loader/maskrom), the numeric `DevNo` from `rk -s` is also accepted:

```bash
rk -d 2    -i       # identify DevNo=2
rk -d <id> -c       # configure a specific device
```

To run a command against **every** connected device, use `-d all`:

```bash
rk -d all -i        # identify every connected device
rk -d all -c        # configure every connected device
```

`-d all` is supported by `-c` (configure), `-u` (mount), and `-i` (identify). Without `-d`, a
single connected device is auto-selected; if several are connected and `-d` is omitted, `rk`
prompts you to pick one.

### Flashing requires a single board

`-fi` and `-fb` do **not** accept `-d`: the underlying `flash.py` cannot target a specific
rockusb device, and every connected dayu200 board stays visible to rockusb even when booted
(the OS exposes PID 0x5000 via `hdcd`). Leave only one board plugged in, then run:

```bash
rk -fi -p <path>
```


# tests

```bash
bash tests/test_pipeline.sh   # stub-based pipeline smoke test
```

Stubs heavy tools (`repo`, `python`, `node`, `build.sh`, etc.) and runs `oh -a` to verify
directory creation, step sequencing, `.oh_utils` logging, and `GLOBAL_LOG` without cloning
or compiling anything.

# docker/***

Decorized tools, which do their job in a virtualized environment (docker container).

The main tool is "docker/ubuntu-2204-koala/bash". (see details in [docker/README.md](docker/README.md))