HiSH

Run Linux Shell on HarmonyOS devices! Based on harmony-qemu, both 2in1(PC), Tablet and Phone are supported.

Core Features

• Complete arm64 Linux kernel
• Networking (NAT)
• Alpine Linux rootfs
• Virtual Keys (Tab/Ctrl/Esc/Up/Down/Left/Right)

This is screenshot of HiSH on Tablet emulator:

How to use

Download hap from Releases page and signed by yourself, then install to your device or emulator.

How to build

• HAP bundle
• Linux kernel (optional)
• libqemu-system (optional)
• rootfs (optional)

Build HAP

• Clone this repo to local
• Copy build-profile.template.json5 to build-profile.json5
• Download files and move to corresponding location as following
  • entry/libs/arm64-v8a/libqemu-system-aarch64.so
  • entry/libs/x86_64/libqemu-system-aarch64.so
  • entry/src/main/resources/rawfile/vm/kernel_aarch64
  • entry/src/main/resources/rawfile/vm/rootfs_aarch64.qcow2
• Build project in DevEco Studio
• Sign and run in your device or emulator

Build libqemu-system (Optional)

Build your own libqemu-system-aarch64.so for entry/libs on Ubuntu (or WSL2 on Windows), for customizing libqemu

• Install dependencies

sudo apt install -y build-essential cmake curl wget unzip python3 libncurses-dev \
		git flex bison bash make autoconf libcurl4-openssl-dev tcl \
		gettext zip pigz meson

• Download "Command Line Tools" for Linux from https://developer.huawei.com/consumer/cn/download/
• Extract downloaded zip and set TOOL_HOME env variable to command-line-tools directory
• Change current directory to deps and run build.sh, for x86_64 emulator default
  • For real devices, you can change target to arm64 in build.sh by modifying OHOS_ARCH and OHOS_ABI

cd deps
./build.sh

• See *.so files in deps/output

ls -lh output

Build Linux Kernel (Optional)

Build your own Linux kernel for HiSH, for customizing Linux kernel

• Install dependencies

sudo apt install build-essential gcc bc bison flex libssl-dev libncurses5-dev libelf-dev gcc-aarch64-linux-gnu

• Clone linux kernel source to local

git clone --depth=1 -b v6.16 https://github.com/torvalds/linux

• Download linux kernel build config

cd linux
curl https://raw.githubusercontent.com/harmoninux/linux-config/refs/heads/master/arm64_tinydocker > .config

• Build Linux kernel

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -j$(nproc)

• The kernel image is at arch/arm64/boot/Image, copy it to entry/src/main/resources/rawfile/vm/kernel_aarch64

Build rootfs for Linux (Optional)

Build your own rootfs for HiSH

• Download and extract Alpine rootfs from downloads | Alpine Linux

mkdir alpine
tar xvf alpine-minirootfs-3.22.1-aarch64.tar.gz -C alpine

• Use qemu-img to create a rootfs.img file

qemu-img create -f raw rootfs.img 8G

• Make fs for rootfs.img file

mkfs.ext4 rootfs.img

• Mount rootfs.img as directory

sudo mkdir /mnt/rootfs
sudo mount rootfs.img /mnt/rootfs

• Copy files of rootfs to /mnt/rootfs

sudo cp -r alpine/* /mnt/rootfs

• Unmount /mnt/rootfs

sudo umount /mnt/rootfs

• Convert raw img to qcow2 format

qemu-img convert -p -f raw -O qcow2 rootfs.img rootfs.qcow2

• Put rootfs.qcow2 to entry/src/main/resources/rawfile/vm/rootfs_aarch64.qcow2

Screenshots

Screenshots of HiSH running on various HarmonyOS devices.

2in1(PC)

Tablet

Phone

Star History