1(_build_dragonos)= 2# 构建DragonOS 3 4## 1.写在前面 5 6  无论您采用后文中的何种方式来编译DragonOS，您必须先按照本小节中的步骤，初始化您的开发环境。 7 8  开始之前，您需要一台运行Linux或MacOS的计算机，并且处理器架构为X86-64. 9 10  对于Linux发行版，建议使用Ubuntu22、Debian、Arch Linux这样的，仓库软件版本较新的发行版，这能为您减少很多麻烦。 11 12### 1.1 下载DragonOS的源代码 13 14  假设您的计算机上已经安装了git，您可以通过以下命令，获得DragonOS的最新的源代码： 15 16```shell 17git clone https://github.com/DragonOS-Community/DragonOS 18cd DragonOS 19``` 20 21:::{warning} 22DragonOS的源代码托管在Github上，但是，由于Github在国内的访问速度较慢。可能出现克隆失败的情况，这时只要重试即可。 23 24当然，我们建议您在github上绑定您的电脑的**ssh公钥**， 25然后通过以下命令来克隆代码，防止频繁出现git clone、pull、push失败的情况。 26 27```shell 28git clone git@github.com:DragonOS-Community/DragonOS.git 29``` 30::: 31 32## 2.使用一键初始化脚本进行安装（推荐） 33 34 35  我们提供了一键初始化脚本，可以一键安装，只需要在控制台运行以下命令： 36 37```shell 38cd tools 39bash bootstrap.sh # 这里请不要加上sudo, 因为需要安装的开发依赖包是安装在用户环境而非全局环境 40``` 41 42:::{note} 43一键配置脚本目前只支持以下系统： 44 45- Ubuntu/Debian/Deepin/UOS 等基于Debian的衍生版本 46 47欢迎您为其他的系统完善构建脚本！ 48::: 49 50**如果一键初始化脚本能够正常运行，并输出最终的“祝贺”界面(如下所示)，请关闭当前终端，然后重新打开。** 51 52 53```shell 54|-----------Congratulations!---------------| 55| | 56| 你成功安装了DragonOS所需的依赖项! | 57| | 58| 请关闭当前终端, 并重新打开一个终端 | 59| 然后通过以下命令运行: | 60| | 61| make run | 62| | 63|------------------------------------------| 64``` 65 66**接着，请直接跳到{ref}`编译命令讲解 <_build_system_command>`进行阅读！** 67 68## 3.手动安装 69 70### 3.1 依赖清单 71 72  如果自动安装脚本不能支持您的操作系统，那么您需要手动安装依赖程序。以下是依赖项的清单： 73 74  在以下依赖项中，除了`docker-ce`和`Rust及其工具链`以外，其他的都能通过系统自带的包管理器进行安装。关于docker以及rust的安装，请看后文。 75 76- docker-ce 77- llvm-dev 78- libclang-dev 79- clang 80- gcc-multilib 81- qemu qemu-system qemu-kvm 82- build-essential 83- fdisk 84- lsb-release 85- git 86- dosfstools 87- unzip 88- Rust以及其工具链 89 90**请留意，若您的Linux系统是在虚拟机中运行的，还请您在您的VMware/Virtual Box虚拟机的处理器设置选项卡中，开启Intel VT-x或AMD-V选项，否则，DragonOS将无法运行。** 91 92:::{note} 93 94 95*在某些Linux发行版的软件仓库中构建的Qemu可能由于版本过低而不兼容DragonOS，如果遇到这种问题，请卸载Qemu，并采用编译安装的方式重新安装Qemu* 96 97在该地址下载Qemu源代码： https://download.qemu.org/ 98 99解压后进入源代码目录，然后执行下列命令： 100 101```shell 102# 安装编译依赖项 103sudo apt install -y autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev \ 104 gawk build-essential bison flex texinfo gperf libtool patchutils bc \ 105 zlib1g-dev libexpat-dev pkg-config libglib2.0-dev libpixman-1-dev libsdl2-dev \ 106 git tmux python3 python3-pip ninja-build 107 108./configure --enable-kvm 109make -j 8 110sudo make install 111# 编译安装完成 112``` 113请注意，编译安装的QEMU，将通过VNC模式进行链接，因此，您还需要在您的计算机上安装VNC viewer以连接至QEMU虚拟机。 114::: 115 116### 3.2 安装Docker 117 118  您可以在docker官网下载安装docker-ce. 119 120> 详细信息请转到： [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) 121 122### 3.3 安装Rust 123 124:::{warning} 125**【常见误区】**：如果您打算采用docker进行编译，尽管docker镜像中已经安装了Rust编译环境，但是，为了能够在VSCode中使用Rust-Analyzer进行代码提示，以及`make clean`命令能正常运行，您的客户机上仍然需要安装rust环境。 126::: 127 128  您可以在控制台输入以下命令，安装rust。 129 130```shell 131# 这两行用于换源，加速Rust的安装过程 132export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static 133export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup 134# 安装Rust 135curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain nightly 136# 把Rustup加到环境变量 137echo "export PATH=\"\$HOME/.cargo/bin:\$PATH\"" >> ~/.bashrc 138source ~/.cargo/env 139source "$HOME/.cargo/env" 140 141# 更换cargo的索引源 142touch ~/.cargo/config 143echo -e "[source.crates-io] \n \ 144registry = \"https://github.com/rust-lang/crates.io-index\" \n \ 145\n \ 146replace-with = 'dragonos-gitee' \n \ 147[source.dragonos-gitee] \n \ 148registry = \"https://gitee.com/DragonOS/crates.io-index.git\" \n \ 149" > ~/.cargo/config 150 151# 安装DragonOS所需的工具链 152cargo install cargo-binutils 153rustup toolchain install nightly 154rustup default nightly 155rustup component add rust-src 156rustup component add llvm-tools-preview 157rustup target add x86_64-unknown-none 158# Rust安装完成 159``` 160 161**至此，公共依赖项已经安装完成，您可以根据自己的需要，阅读后续章节** 162 163**关于编译命令的用法，请见：{ref}`编译命令讲解 <_build_system_command>`** 164 165## 4.从Docker构建（不推荐） 166 167  DragonOS发布了一个Docker编译环境，便于开发者运行DragonOS。但是，由于编码过程仍需要在客户机上进行，因此，您需要在客户机上安装Rust编译环境。 168 169  本节假设以下操作均在Linux下进行。 170 171 172### 4.1 安装qemu虚拟机 173 174  在本节中，我们建议您采用命令行安装qemu： 175 176```shell 177sudo apt install -y qemu qemu-system qemu-kvm 178``` 179 180### 4.2 创建磁盘镜像 181 182  首先，您需要使用tools文件夹下的create_hdd_image.sh，创建一块虚拟磁盘镜像。您需要在tools文件夹下运行此命令。 183 184```shell 185bash create_hdd_image.sh 186``` 187 188### 4.3 运行DragonOS 189 190  如果不出意外的话，这将是运行DragonOS的最后一步。您只需要在DragonOS的根目录下方，执行以下命令，即可运行DragonOS。 191 192```shell 193make run-docker 194``` 195 196  稍等片刻，DragonOS将会被运行。 197 198  在qemu虚拟机被启动后，我们需要在控制台输入字母`c`，然后回车。这样，虚拟机就会开始执行。 199 200:::{note} 2011. 首次编译时，由于需要下载Rust相关的索引（几百MB大小），因此需要一定的时间，请耐心等候！ 2022. 输入命令可能需要加上sudo 203::: 204 205**关于编译命令的用法，请见：{ref}`编译命令讲解 <_build_system_command>`** 206 207## 5.其他注意事项 208 209### 5.1 创建磁盘镜像 210 211  首先，您需要使用**普通用户**权限运行`tools/create_hdd_image.sh`，为DragonOS创建一块磁盘镜像文件。该脚本会自动完成创建磁盘镜像的工作，并将其移动到`bin/`目录下。 212  请注意，由于权限问题，请务必使用**普通用户**权限运行此脚本。（运行后，需要提升权限时，系统可能会要求您输入密码） 213 214 215### 5.2 编译、运行DragonOS 216 2171. 安装编译及运行环境 2182. 进入DragonOS文件夹 2193. 输入`make run`即可编译并写入磁盘镜像，并运行 220 221 222  在qemu虚拟机被启动后，我们需要在控制台输入字母`c`，然后回车。这样，虚拟机就会开始执行。 223 224:::{note} 225首次编译时，由于需要下载Rust相关的索引（几百MB大小），因此需要一定的时间，请耐心等候！ 226::: 227 228**关于编译命令的用法，请见：{ref}`编译命令讲解 <_build_system_command>`** 229 230(_build_system_command)= 231## 6.编译命令讲解 232 233- 本地编译，不运行: `make all -j 您的CPU核心数` 234- 本地编译，并写入磁盘镜像，不运行: `make build` 235- 本地编译，写入磁盘镜像，并在QEMU中运行: `make run` 236- Docker编译，并写入磁盘镜像,: `make docker` 237- Docker编译，写入磁盘镜像，并在QEMU中运行: `make run-docker` 238- 不编译，直接从已有的磁盘镜像启动: `make qemu` 239- 清理编译产生的文件: `make clean` 240- 编译文档: `make docs` （需要手动安装sphinx以及docs下的`requirements.txt`中的依赖） 241- 清理文档: `make clean-docs` 242- 格式化代码: `make fmt` 243 244:::{note} 245如果您需要在vnc中运行DragonOS，请在上述命令后加上`-vnc`后缀。如：`make run-vnc` 246 247qemu虚拟机将在5900端口监听vnc连接。您可以使用vnc viewer或者Remmina连接至qemu虚拟机。 248::: 249