System Prerequisites

Successful compilation requires a Windows host environment running the 64-bit version of Windows 10 or later, utilized via a Linux subsystem. The recommended guest OS is Ubuntu 20.04 LTS on an x86_64 architecture.

• Memory: Minimum 16 GB RAM is strongly advised for Ubuntu to handle build proceses efficienttly.
• User Account: The system username must not contain non-ASCII characters.
• Compatibility Note: Ubuntu versions higher than 20.04 (specifically 22.04) are currently unsupported for this build configuration.

Shell and Repository Configuration

Switching Default Shell

To ensure compatibility with certain build scripts, configure the default shell to bash:

sudo dpkg-reconfigure dash

Select "No" when prompted to use bash as the primary interpreter.

Updating Package Sources

Configure domestic mirrors to accelerate dependency downloads.

1. Download the latest repository definition from the mirror utility site relevant to your Ubuntu release.
2. Replace the contents of /etc/apt/sources.list with the newly fetched data.
3. Refresh the package index:

sudo apt update

4. Configure PIP for PyPI mirrors by editing ~/.pip/pip.conf:

[global]
index-url = https://repo.huaweicloud.com/repository/pypi/simple
trusted-host = repo.huaweicloud.com
timeout = 120

Dependency Installasion

Install the core toolchain and libraries required for cross-compilation. Ensure these are installed before proceeding, as missing packages will trigger build failures.

sudo apt-get install binutils binutils-dev git git-lfs gnupg flex bison gperf build-essential zip curl zlib1g-dev libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z1-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip m4 bc gnutls-bin python3.8 python3-pip ruby genext2fs device-tree-compiler make libffi-dev e2fsprogs pkg-config perl openssl libssl-dev libelf-dev libdwarf-dev u-boot-tools mtd-utils cpio doxygen liblz4-tool openjdk-8-jre gcc g++ texinfo dosfstools mtools default-jre default-jdk libncurses5 apt-utils wget scons python3.8-distutils tar rsync git-core libxml2-dev lib32z-dev grsync xxd libglib2.0-dev libpixman-1-dev kmod jfsutils reiserfsprogs xfsprogs squashfs-tools pcmciautils quota ppp libtinfo-dev libtinfo5 libncurses5-dev libncursesw5 libstdc++6 gcc-arm-none-eabi vim ssh locales libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev

Additionally, install the specific ARM Linux cross-compilers:

sudo apt-get install gcc-arm-linux-gnueabi gcc-9-arm-linux-gnueabi

Python and Build Tool Integration

Configuring Python Runtime

Set Python 3.8 as the default interpreter for system-wide commands:

sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.8 1
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.8 1
python --version

Ensure pip is available for package management:

sudo apt install python3-pip

Apply custom mirror settings globally using pip configuration:

mkdir ~/.pip
pip3 config set global.index-url https://mirrors.huaweicloud.com/repository/pypi/simple
pip3 config set global.trusted-host mirrors.huaweicloud.com
pip3 config set global.timeout 120

Git and Repo Tool Setup

Initialize necessary version control tools:

sudo apt install git-lfs
git config --global credential.helper store
git config --global --add safe.directory "*"

Download the Gitee manifest tool (repo):

mkdir ~/bin
curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > ~/bin/repo
chmod a+x ~/bin/repo

Add the script directory to your PATH in ~/.bashrc and refresh the session.

Authentication and Source Synchronization

SSH Key Generation

Create a new Ed25519 key pair for authentication with the code repository:

ssh-keygen -t ed25519 -C "developer@example.com"

Retrieve the public key content:

cat ~/.ssh/id_ed25519.pub

Copy the output and register it within your Gitee developer account dashboard under SSH Public Keys. Verify the connection successfully:

ssh -T git@gitee.com

A response indicating successful authentication confirms the setup.

Cloning the Project

Define the workspace and fetch the source tree:

mkdir -p ~/openharmony/4.0
cd ~/openharmony/4.0
repo init -u git@gitee.com:openharmony/manifest.git -b OpenHarmony-4.0-Release --no-repo-verify
repo sync -c
repo forall -c 'git lfs pull'

Once synchronized, execute the prebuilt binary downloader script located in the project root:

bash build/prebuilts_download.sh

This script resolves and extracts toolchains to the designated prebuilts directory.

Building Tools Preparation

Install the Harbin build command-line interface:

python3 -m pip install --user build/hb

Append the local binary path to your shell environment:

echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Compilation Workflow

Initiate the build process specifying the target product board:

./build.sh --product-name rk3568 --ccache

Build times may vary significantly depending on hardware resources.

Troubleshooting Common Issues

If build interruptions occur (e.g., error codes around 3000 or 4000), follow these remediation steps:

1. Clean Previous Artifacts: Remove temporary build files to ensure a fresh state.

   hb clean --all
   # OR manually remove build caches
   rm -rf out build/resources/args/*.json
   

2. Synchronize Submodules: Run repo sync again to verify all dependencies are current.
3. Verify LFS Objects: Ensure large binaries are correctly pulled.

   repo forall -c 'git lfs pull'
   

4. Re-download Prebuilts: Re-execute the prebuilt installation script if toolchains are corrupted.

   bash build/prebuilts_download.sh
   

Memory Allocation Errors

Specific error scenarios related to resource exhaustion (often Error 4000) indicate insufficient virtual memory during compilation.\nTo resolve this on a WSL-based setup:

1. Navigate to %UserProfile% in Windows Explorer.
2. Create a configuration file named .wslconfig.
3. Insert the following parameters to limit memory consumption:

   [wsl2]
   memory=7G
   swap=7G
   

4. Shut down the active Linux instance from the command prompt:

   wsl --shutdown
   

5. Restart the Bash environment and monitor memory usage via free -m. Retry the compilation after increasing allocated resources.