DragonOS-Community/DragonOS
4
1
Fork 0
mirror of https://github.com/DragonOS-Community/DragonOS.git synced 2025-06-28 00:33:25 +00:00
Code Issues Releases Wiki Activity

doc: Add ai doc translate tool and add English doc. (#1168)

Browse Source 
- add tools/doc_translator.py
- translated docs into English

Signed-off-by: longjin <longjin@DragonOS.org>
This commit is contained in:
LoGin
2025-05-20 10:44:28 +08:00
committed by GitHub
parent fccfa6f7ff
commit 880720250e
98 changed files with 13972 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
docs/locales/en/introduction/build_system.md Normal file
View File

@ -0,0 +1,294 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: introduction/build_system.md
- Translation time: 2025-05-19 01:44:01
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Building DragonOS
## 1. Introduction
&emsp;&emsp;Regardless of which method you use to compile DragonOS in the following sections, you must first follow the steps in this section to initialize your development environment.
&emsp;&emsp;Before you start, you need a computer running Linux or macOS with an X86-64 processor architecture.
&emsp;&emsp;For Linux distributions, it is recommended to use newer distributions such as Ubuntu 22, Debian, or Arch Linux, which can save you a lot of trouble.
### 1.1 Downloading the DragonOS Source Code
Use `https` to clone:
```shell
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` to clone (please configure your GitHub SSH Key first) to avoid cloning failures due to network issues:
Use `ssh` to clone (please configure your GitHub SSH Key first):
```shell
# 使用ssh克隆
git clone git@github.com:DragonOS-Community/DragonOS.git
cd DragonOS
# 使用镜像源更新子模块
make update-submodules-by-mirror
```
## 2. Installation Using One-Click Initialization Script (Recommended)
&emsp;&emsp;We provide a one-click initialization script that can install everything with a single command. Just run the following command in the terminal:
```shell
cd DragonOS
cd tools
bash bootstrap.sh # 这里请不要加上sudo, 因为需要安装的开发依赖包是安装在用户环境而非全局环境
```
:::{note}
The one-click configuration script currently supports the following systems:
- Ubuntu/Debian/Deepin/UOS and other derivatives based on Debian
- Gentoo, due to the characteristics of the Gentoo system, when Gentoo encounters USE or circular dependency issues, please handle them according to the emerge prompt information. Official dependency handling examples [GentooWiki](https://wiki.gentoo.org/wiki/Handbook:AMD64/Full/Working/zh-cn#.E5.BD.93_Portage_.E6.8A.A5.E9.94.99.E7.9A.84.E6.97.B6.E5.80.99)
We welcome you to improve the build script for other systems!
:::
**If the one-click initialization script runs normally and outputs the final "Congratulations" interface (as shown below), please close the current terminal and then reopen it.**
```shell
|-----------Congratulations!---------------|
| |
| 你成功安装了DragonOS所需的依赖项! |
| |
| 请关闭当前终端, 并重新打开一个终端 |
| 然后通过以下命令运行: |
| |
| make run |
| |
|------------------------------------------|
```
**Then, please directly jump to {ref}`编译命令讲解 <_build_system_command>` for reading!**
## 3. Manual Installation
### 3.1 Dependency List
&emsp;&emsp;If the automatic installation script does not support your operating system, you need to manually install the required packages. The following is the list of dependencies:
&emsp;&emsp;Among the following dependencies, except for `docker-ce` and `Rust及其工具链`, the rest can be installed using the system's built-in package manager. For the installation of Docker and Rust, 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 that if your Linux system is running in a virtual machine, please make sure to enable the Intel VT-x or AMD-V option in the processor settings of your VMware/Virtual Box virtual machine, otherwise DragonOS will not be able to run.**
:::{note}
*In some Linux distributions, the Qemu built from the software repository may be incompatible with DragonOS due to an outdated version. 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 decompression, enter the source code directory and execute the following command:
```shell
# 安装编译依赖项
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 be linked via VNC mode, so you also need to install a VNC viewer on your computer to connect to the QEMU virtual machine.
:::
### 3.2 Installing Docker
&emsp;&emsp;You can download and install docker-ce from the Docker official website.
> For detailed information, please visit: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
### 3.3 Installing Rust
:::{warning}
**[Common Misconception]**: If you plan to compile using Docker, although the Docker image already includes a Rust compilation environment, to enable code hints in VSCode using Rust-Analyzer and for the `make clean` command to run normally, you still need to install the Rust environment on your client machine.
:::
&emsp;&emsp;You can install Rust by entering the following command in the terminal.
```shell
# 这两行用于换源，加速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 public dependencies have been installed. You can proceed to read the subsequent sections according to your needs.**
**For the usage of the compilation command, please refer to: {ref}`编译命令讲解 <_build_system_command>`**
## 4. Building from Docker (Not Recommended)
&emsp;&emsp;DragonOS provides a Docker compilation environment for developers to run DragonOS. However, since the coding process still needs to be performed on the client machine, you need to install the Rust compilation environment on your client machine.
&emsp;&emsp;This section assumes that all operations are performed under Linux.
### 4.1 Installing QEMU Virtual Machine
&emsp;&emsp;In this section, we recommend installing QEMU via the command line:
```shell
sudo apt install -y qemu qemu-system qemu-kvm
```
### 4.2 Creating a Disk Image
&emsp;&emsp;First, you need to use the `create_hdd_image.sh` script in the `tools` folder to create a virtual disk image. You need to run this command in the `tools` folder.
```shell
bash create_hdd_image.sh
```
### 4.3 Running DragonOS
&emsp;&emsp;If everything goes well, this will be the final step to run DragonOS. You just need to execute the following command in the DragonOS root directory to run DragonOS.
```shell
make run-docker
```
&emsp;&emsp;Wait a moment, DragonOS will be started.
&emsp;&emsp;After the QEMU virtual machine is started, you need to input the letter `c` in the console and press Enter. This will start the virtual machine.
:::{note}
1. During the first compilation, since it requires downloading Rust-related indexes (hundreds of MB in size), it will take some time. Please be patient!
2. Entering commands may require adding `sudo`
:::
**For the usage of the compilation command, please refer to: {ref}`编译命令讲解 <_build_system_command>`**
## 5. Other Notes
### 5.1 Creating a Disk Image
&emsp;&emsp;First, you need to run `tools/create_hdd_image.sh` with **normal user** permissions to create a disk image file for DragonOS. This script will automatically complete the creation of the disk image and move it to the `bin/` directory.
&emsp;&emsp;Please note that due to permission issues, you must run this script with **normal user** permissions. (After running, the system may prompt you to enter a password when you need to elevate permissions.)
### 5.2 Compiling and Running DragonOS
1. Install the compilation and runtime environment
2. Enter the DragonOS folder
3. Input `make run` to compile and write to the disk image, and run
&emsp;&emsp;After the QEMU virtual machine is started, you need to input the letter `c` in the console and press Enter. This will start the virtual machine.
:::{note}
During the first compilation, since it requires downloading Rust-related indexes (hundreds of MB in size), it will take some time. Please be patient!
:::
**For the usage of the compilation command, please refer to: {ref}`编译命令讲解 <_build_system_command>`**
(_translated_label___build_system_command_en)=
## 6. Explanation of Compilation Commands
- Local compilation, no execution: `make all -j 您的CPU核心数`
- Local compilation, write to disk image, no execution: `make build`
- Local compilation, write to disk image, and run in QEMU: `make run`
- Local compilation, write to disk image, and 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`
- Start directly from an existing disk image without compilation: `make qemu`
- Start directly from an existing disk image without compilation (headless mode): `make qemu-nographic`
- Clean up compiled files: `make clean`
- Compile documentation: `make docs` (requires manual installation of sphinx and dependencies in `requirements.txt`)
- Clean up documentation: `make clean-docs`
- Format code: `make fmt`
:::{note}
If you need to run DragonOS in VNC, add the `-vnc` suffix to the above command. For example: `make run-vnc`
The QEMU virtual machine will listen on port 5900 for VNC connections. You can connect to the QEMU virtual machine using a VNC viewer or Remmina.
:::
## 7. Compiling for riscv64
Since DragonOS has not been fully ported to riscv64 yet, the compilation needs to be done as follows:
1. Modify `env.mk` and `.vscode/settings.json`
Change the value of `ARCH` in `env.mk` to `riscv64`, and in `setting.json`, comment out `"rust-analyzer.cargo.target": "x86_64-unknown-none",` and change it to the line enabling riscv64.
2. Restart rust-analyzer
3. Clean up the compilation cache
Due to the differences between x86_64 and riscv64 architectures, there may be compilation issues caused by cache. Ensure that you clean up the cache before running.
```shell
make clean
```
4. Compile and run for riscv64
```shell
# 下载DragonStub
git submodule update --init --recursive --force
make run
```
Please note that since you are running QEMU in the console, when you want to exit, input `Ctrl+A` and press `X` to do so.

154
docs/locales/en/introduction/features.md Normal file
View File

@ -0,0 +1,154 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: introduction/features.md
- Translation time: 2025-05-19 01:42:30
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
(_translated_label___genreal_features_en)=
# Features of DragonOS
## Specifications
- [x] Bootloader: Multiboot2
- [x] Interface: POSIX 2008
## Kernel Layer
### Memory Management
- [x] Page Frame Allocator
- [x] Small Object Allocator
- [x] VMA (Virtual Memory Area)
- [x] Automatic MMIO Address Space Allocation
- [x] Page Mapper
- [x] Hardware Abstraction Layer
- [x] Independent User Address Space Management Mechanism
- [x] C Interface Compatibility Layer
### Multicore
- [x] Multicore Boot
- [x] IPI (Inter-Processor Interrupt) Framework
### Process Management
- [x] Process Creation
- [x] Process Reclamation
- [x] Kernel Threads
- [x] Fork
- [x] Exec
- [x] Process Sleep (Supports High-Precision Sleep)
- [x] Kthread Mechanism
- [x] Extensible Binary Loader
#### Synchronization Primitives
- [x] Mutex
- [x] Semaphore
- [x] Atomic Variables
- [x] Spinlock
- [x] Wait Queue
### Scheduling
- [x] CFS Scheduler
- [x] Real-Time Scheduler (FIFO, RR)
- [x] Single-Core Scheduling
- [x] Multi-Core Scheduling
- [x] Load Balancing
### IPC (Inter-Process Communication)
- [x] Anonymous Pipe
- [x] Signal
### File System
- [x] VFS (Virtual File System)
- [x] FAT12/16/32
- [x] Devfs
- [x] RamFS
- [x] Procfs
- [x] Sysfs
### Exception and Interrupt Handling
- [x] APIC
- [x] Softirq (Soft Interrupt)
- [x] Kernel Stack Traceback
### Kernel Utility Library
- [x] String Operation Library
- [x] ELF Executable Support
- [x] printk
- [x] Basic Math Library
- [x] Screen Manager
- [x] TextUI Framework
- [x] CRC Function Library
- [x] Notification Chain
### System Calls
&emsp;&emsp;[See System Call Documentation](https://docs.dragonos.org/zh_CN/latest/syscall_api/index.html)
### Test Framework
- [x] ktest
### Drivers
- [x] ACPI (Advanced Configuration and Power Interface) Module
- [x] IDE Hard Disk
- [x] AHCI Hard Disk
- [x] PCI, PCIe Bus
- [x] XHCI (USB 3.0)
- [x] PS/2 Keyboard
- [x] PS/2 Mouse
- [x] HPET (High Precision Event Timer)
- [x] RTC (Real-Time Clock)
- [x] Local APIC Timer
- [x] UART Serial Port
- [x] VBE (Video BIOS Extension) Display
- [x] VirtIO Network Card
- [x] x87 FPU
- [x] TTY Terminal
- [x] Floating Point Processor
## User Layer
### LibC
- [x] Basic System Calls
- [x] Basic Standard Library Functions
- [x] Partial Mathematical Functions
### Shell Command Line Programs
- [x] Parsing Based on String Matching
- [x] Basic Commands
### Http Server
- A simple Http Server written in C, capable of running static websites.
## Software Portability
- [x] GCC 11.3.0 (Currently only supports x86_64 Cross Compiler) [https://github.com/DragonOS-Community/gcc](https://github.com/DragonOS-Community/gcc)
- [x] binutils 2.38 (Currently only supports x86_64 Cross Compiler) [https://github.com/DragonOS-Community/binutils](https://github.com/DragonOS-Community/binutils)
- [x] gmp 6.2.1 [https://github.com/DragonOS-Community/gmp-6.2.1](https://github.com/DragonOS-Community/gmp-6.2.1)
- [x] mpfr 4.1.1 [https://github.com/DragonOS-Community/mpfr](https://github.com/DragonOS-Community/mpfr)
- [x] mpc 1.2.1 [https://github.com/DragonOS-Community/mpc](https://github.com/DragonOS-Community/mpc)
- [x] relibc [https://github.com/DragonOS-Community/relibc](https://github.com/DragonOS-Community/relibc)
- [x] sqlite3

34
docs/locales/en/introduction/index.rst Normal file
View File

@ -0,0 +1,34 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: introduction/index.rst
- Translation time: 2025-05-19 01:41:59
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
Introduction to DragonOS
====================================
DragonOS, the Dragon Operating System, is a 64-bit operating system designed for lightweight cloud computing scenarios. It features a fully self-developed kernel and provides Linux binary compatibility. Developed using the Rust programming language, it offers enhanced reliability. Currently, DragonOS ranks among the top three in the Rust operating system field on GitHub.
The DragonOS open-source community was established in July 2022. It is completely neutral in commercial matters. Our goal is to build a fully independent, open-source, high-performance, and highly reliable server operating system, **to create a fully self-controlled digital future!**
DragonOS has an excellent and well-designed architecture. Compared to other systems of similar size, DragonOS supports virtualization and has certain advantages in areas such as device model and scheduling subsystems. Currently, we are actively promoting cloud platform support, RISC-V support, as well as the porting of compilers and application software. We aim to achieve large-scale application in production environments within five years.
DragonOS is currently developing rapidly under the drive of the community. At present, DragonOS has already implemented about 1/4 of the Linux interface. In the future, we will provide 100% compatibility with Linux and introduce new features.
The goal of DragonOS is to build a fully independent, open-source, high-performance, and highly reliable server operating system, providing a completely self-controlled core power for the country's digital infrastructure construction.
As a community-driven open-source operating system, in order to promote the development of the open-source community and avoid potential infringement by commercial companies that do not comply with open-source agreements, we have decided to open the source code under the GPLv2 license, using a strict open-source agreement to protect DragonOS.
You may be interested in the features that have already been implemented in DragonOS. You can visit here: :ref:`功能特性 <_genreal_features>`
.. toctree::
:maxdepth: 1
features

22
docs/locales/en/introduction/mirrors.md Normal file
View File

@ -0,0 +1,22 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: introduction/mirrors.md
- Translation time: 2025-05-19 01:41:42
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# DragonOS Mirror Site
You can download the source code and other files of DragonOS from the following mirror sites:
- [DragonOS Mirror Site https://mirrors.dragonos.org/](https://mirrors.dragonos.org/)
- [DragonOS Domestic Mirror Site (RinGoTek)](https://mirrors.RinGoTek.cn)
- [Git Mirror Site](https://git.mirrors.dragonos.org/)