备注

AI Translation Notice

This document was automatically translated by hunyuan-turbos-latest model, for reference only.

  • Source document: introduction/build_system.md

  • Translation time: 2025-12-16 16:22:38

  • Translation model: hunyuan-turbos-latest

Please report issues via Community Channel

Building DragonOS

0. Quick Experience

  If you just want to quickly experience DragonOS without local development, we strongly recommend using DragonOS Playground for cloud-native development. This method is zero-configuration and one-click startup, requiring no local dependencies installation, allowing you to experience the latest nightly build of DragonOS in the cloud.

Using DragonOS Playground

Advantages:

  • ✅ Zero Configuration - No need to install QEMU, Docker, Rust, or other dependencies

  • ✅ Instant Experience - Run DragonOS within seconds

  • ✅ Cloud Environment - Access anytime, anywhere, without occupying local resources

  • ✅ Daily Updates - Automatically get the latest nightly build to experience the newest development version

备注

If you need to develop DragonOS or want to deeply understand its build process, please continue reading the following sections to learn how to build DragonOS in a local environment.

1. Preliminaries

  Regardless of which method you use to compile DragonOS from the following sections, you must first initialize your development environment by following the steps in this section.

  Before you begin, you need a computer running Linux or MacOS with an X86-64 processor architecture.

  For Linux distributions, it is recommended to use newer ones like Ubuntu 22, Debian, or Arch Linux, as they have more up-to-date repository software versions, which can save you a lot of trouble.

1.1 Downloading DragonOS Source Code

Using HTTPS clone:

git clone https://github.com/DragonOS-Community/DragonOS.git
cd DragonOS
# 使用镜像源更新子模块
make update-submodules-by-mirror

For convenience in subsequent development, we recommend using SSH clone (please configure your GitHub SSH key first) to avoid cloning failures due to network issues:

Using SSH clone (please configure your GitHub SSH key first):

# 使用ssh克隆
git clone git@github.com:DragonOS-Community/DragonOS.git
cd DragonOS
# 使用镜像源更新子模块
make update-submodules-by-mirror

3. Manual Installation

3.1 Dependency List

  If the automatic installation script does not support your operating system, you will need to manually install the required dependencies. Below is the list of dependencies:

  Among the following dependencies, all except docker-ce and Rust及其工具链 can be installed via your system’s package manager. For Docker and Rust installation, please refer to the following sections.

  • docker-ce

  • llvm-dev

  • libclang-dev

  • clang

  • gcc-multilib

  • qemu qemu-system qemu-kvm

  • build-essential

  • fdisk

  • lsb-release

  • git

  • dosfstools

  • unzip

  • Rust and its toolchain

Please note: If your Linux system is running in a virtual machine, make sure to enable the Intel VT-x or AMD-V option in the processor settings tab of your VMware/VirtualBox virtual machine. Otherwise, DragonOS will not run.

备注

The QEMU built from some Linux distribution repositories may be incompatible with DragonOS due to older versions. If you encounter this issue, uninstall QEMU and reinstall it by compiling from source.

Download the QEMU source code from this address: https://download.qemu.org/

After extracting, navigate to the source code directory and execute the following commands:

# 安装编译依赖项
sudo apt install -y autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev \
              gawk build-essential bison flex texinfo gperf libtool patchutils bc \
              zlib1g-dev libexpat-dev pkg-config  libglib2.0-dev libpixman-1-dev libsdl2-dev \
              git tmux python3 python3-pip ninja-build

./configure --enable-kvm
make -j 8
sudo make install
# 编译安装完成

Please note that the compiled QEMU will connect via VNC mode, so you will also need to install a VNC viewer on your computer to connect to the QEMU virtual machine.

3.2 Installing Docker

  You can download and install docker-ce from the Docker official website.

3.3 Installing Rust

警告

【Common Misconception】: If you plan to use Docker for compilation, although the Docker image already has the Rust compilation environment installed, your host machine still needs to have the Rust environment installed to enable Rust-Analyzer code suggestions in VSCode and for the make clean command to work properly.

  You can install Rust by entering the following command in the console.

# 这两行用于换源，加速Rust的安装过程
export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static
export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup
# 安装Rust
curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain nightly
# 把Rustup加到环境变量
echo "export PATH=\"\$HOME/.cargo/bin:\$PATH\"" >> ~/.bashrc
source ~/.cargo/env
source "$HOME/.cargo/env"

# 更换cargo的索引源
touch ~/.cargo/config
echo -e "[source.crates-io]   \n \
registry = \"https://github.com/rust-lang/crates.io-index\"  \n \
\n \
replace-with = 'dragonos-gitee' \n \
[source.dragonos-gitee] \n \
registry = \"https://gitee.com/DragonOS/crates.io-index.git\"	 \n \
" > ~/.cargo/config

# 安装DragonOS所需的工具链
cargo install cargo-binutils
rustup toolchain install nightly
rustup default nightly
rustup component add rust-src
rustup component add llvm-tools-preview
rustup target add x86_64-unknown-none
# Rust安装完成

At this point, the common dependencies have been installed. You can proceed to the following sections based on your needs.

For the usage of compilation commands, see: 编译命令讲解

5. Other Notes

5.1 Creating a Disk Image

  First, you need to run tools/create_hdd_image.sh with regular user privileges to create a disk image file for DragonOS. The script will automatically complete the creation of the disk image and move it to the bin/ directory.

  Please note that due to permission issues, you must run this script with regular user privileges. (When elevated permissions are required after running, the system may ask you for a password.)

5.2 Compiling and Running DragonOS

  1. Install the compilation and runtime environment

  2. Enter the DragonOS folder

  3. Enter make run to compile, write to the disk image, and run

  After the QEMU virtual machine is launched, you need to enter the letter c in the console and press Enter. The virtual machine will then begin execution.

备注

During the first compilation, it may take some time to download Rust-related indexes (several hundred MB in size). Please be patient!

For the usage of compilation commands, see: 编译命令讲解

6. Explanation of Compilation Commands

  • Local compilation, no run: make all -j 您的CPU核心数

  • Local compilation, write to disk image, no run: make build

  • Local compilation, write to disk image, and run in QEMU: make run

  • Local compilation, write to disk image, run in headless mode: make run-nographic

  • Docker compilation, write to disk image: make docker

  • Docker compilation, write to disk image, and run in QEMU: make run-docker

  • No compilation, directly boot from existing disk image: make qemu

  • No compilation, directly boot from existing disk image (headless mode): make qemu-nographic

  • Clean compiled files: make clean

  • Compile documentation: make docs (requires manual installation of sphinx and dependencies in requirements.txt under docs)

  • Clean documentation: make clean-docs

  • Format code: make fmt

  • Run and execute syscall tests: make test-syscall

备注

If you want to run DragonOS in VNC, add the -vnc suffix to the above commands. For example: make run-vnc

The QEMU virtual machine will listen for VNC connections on port 5900. You can use a VNC viewer or Remmina to connect to the QEMU virtual machine.

7. Compiling for riscv64

Since DragonOS has not yet been fully ported to riscv64, compilation requires the following steps:

  1. Modify env.mk and .vscode/settings.json

Change the value of ARCH in env.mk to riscv64, and comment out "rust-analyzer.cargo.target": "x86_64-unknown-none", in setting.json, replacing it with the line that enables riscv64.

  1. Restart rust-analyzer

  2. Clean the compilation cache

Due to architectural differences between x86_64 and riscv64, there may be compilation issues caused by caching. Ensure the cache is cleared before running.

make clean

  1. Compile and run for riscv64

# 下载DragonStub
git submodule update --init --recursive --force

make run

Please note that since QEMU runs in the console, to exit, enter Ctrl+A and press X.