README_EN.md

HiSH

GitHub | GitCode | Gitee | 中文

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

How to get

You can try one of following methods to get HiSH:

• Install from AppGallery (JIT not supported, run slower)
• Download hap from Releases page and signed by yourself, then install to your device or emulator (JIT suported, runs faster)
• Build from source code in DevEco Studio, see Build and install HAP (JIT suported, runs faster)

Core Features

• Complete arm64 Linux kernel
• Networking with port forwarding
• Alpine Linux rootfs
• Virtual Keys (Tab/Ctrl/Esc/Up/Down/Left/Right)
• Shared Folder
• JIT (Only available for developer)
• Image import（Ubuntu24.04 / Debian12）

How to build

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

Build HAP

• Download and install DevEco Studio
• Clone this repo to local
• Run git submodule update --init --recursive in HiSH directory
• Copy build-profile.template.json5 to build-profile.json5
• Download files and move to corresponding location as following (Notice: you should rename files as links)
  • entry/libs.zip(Extract to entry/libs)
  • 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. See Running Your App on a Local Real Device | Signing an App Not Associated with a Registered App

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 make, for x86_64 emulator default
  • For real devices(aarch64), you can run make aarch64

cd deps
make

• 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 \
 clang lld llvm make 

• Clone linux kernel source to local

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

• Download linux kernel build config

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

• Build Linux kernel

export KCFLAGS='-march=armv8.5-a+crc+crypto+lse+rcpc+rng+sm4+sha3+dotprod+fp16 -mtune=neoverse-n1 -O2 -falign-functions=64 -fno-strict-aliasing -mllvm -vectorize-loops -mllvm -force-vector-width=2'
env KCFLAGS="$KCFLAGS" make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- LLVM=1 LLVM_IAS=1 menuconfig
env KCFLAGS="$KCFLAGS" make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- LLVM=1 LLVM_IAS=1 -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

Star History