diff --git a/src/chap02/arguments.md b/src/chap02/arguments.md index c9e33ce..034fd31 100644 --- a/src/chap02/arguments.md +++ b/src/chap02/arguments.md @@ -2,7 +2,7 @@ RuxOS 提供了看起繁杂但却灵活且明确的编译参数，来针对多种类型的应用进行构建和运行。 -**通用参数** ： +## 通用参数 | General Options | | | --- | --- | @@ -15,7 +15,7 @@ RuxOS 提供了看起繁杂但却灵活且明确的编译参数，来针对多 | ARGS | 命令行参数，使用逗号分隔，不允许空格，可以为空。用来给应用程序传递具体的参数，即 `argc`，`argv`。 | | ENVS | 环境变量参数，使用逗号分隔，不允许空格，可以为空。 | -**应用参数** ： +## 应用参数 | App Options | | | --- | --- | @@ -23,7 +23,7 @@ RuxOS 提供了看起繁杂但却灵活且明确的编译参数，来针对多 | FEATURES | RuxOS 模块的 feature。该参数用于在命令行开启用户想要的额外 feature，而不需要出现在具体应用的 `features.txt`文件中。 | | APP_FEATURES | rust 应用的额外 feature。 | -**Qemu 参数**： +## Qemu 参数 | Qemu Options | | |---|---| @@ -39,7 +39,7 @@ RuxOS 提供了看起繁杂但却灵活且明确的编译参数，来针对多 | START_PORT | qemu 开放的端口的起始端口号（默认是5555号端口）。 | | PORTS_NUM | qemu 开放的端口的数量（默认是5个）。 | -**9P 参数**： +## 9P 参数 | 9P Options | | |---|---| @@ -48,18 +48,72 @@ RuxOS 提供了看起繁杂但却灵活且明确的编译参数，来针对多 | ANAME_9P | 9pfs 的路径。 | | PROTOCOL_9P | 9p 协议类型。 | -**网络参数**，默认端口号为 5555： +## 网络参数（默认端口号 5555） | Network Options | | |---|---| | IP | Ruxos IPv4 地址（qemu user netdev，默认是 10.0.2.15）。 | | GW | 网关 IPv4 地址（qemu user netdev，默认是 10.0.2.2）。 | -**Libc 参数**： +## Libc 参数 | Libc Options | | |---|---| | MUSL | 使用 musl libc 来进行编译、链接。默认情况下 RuxOS 用的是 `ruxlibc` 。用户可以通过设置 `MUSL=y` 来使能 musl libc。 | +# 运行命令 + +RuxOS 提供了多种运行命令，以满足不同的需求，包含编译、运行、调试等。这些命令需要在 RuxOS 根目录下运行。 + +## make build + +编译指定的应用，默认为 `helloworld` 应用，生成可供 qemu 直接运行的二进制内核文件。 + +## make run + +运行指定的应用，包含了 `make build` 的过程，将生成的二进制内核文件传给 qemu，qemu 的参数根据用户声明的[编译参数](#编译参数说明)进行生成。 + +## make disasm + +将运行的二进制指令反汇编，生成文件包含了运行过程中的所有汇编指令。 + +## make debug + +启动 GDB 进行调试。 + +## make disk_img + +借助 `dd`，`mkfs` 命令生成一个 fat32 镜像文件，传给 qemu 作为磁盘文件。 + +当涉及到需要使用文件系统、块设备存储的程序时，需要提供给 qemu 一个块设备。 + +## make clean_c + +清除 `ruxlibc` 的 `libc.a` 以及 C 应用程序声明的 `app-objs`，如果对应的应用程序的 `axbuild.mk` 也写了 `clean_c` +也会相应的运行。 + +## make clean_musl + +清除 musl libc 生成的 install 目录和 build 目录，该命令之后，运行 musl libc 相关的应用时会重新编译 musl libc。 + +## make clean + +该命令包含 `make clean_c`，`make clean_musl`，同时会清除应用程序的 elf 文件和 bin 文件，并执行 `cargo clean`。 + +## make clippy + +借助 clippy 做代码规范检查。 + +## make fmt + +借助 `cargo fmt` 对调整 Rust 代码格式。 + +## make fmt_c + +对 C 代码格式进行规范。 + +## make test + +对 `apps/` 目录下的应用进行测试，并通过比对输出结果与相应的 `.out` 文件来判断是否正确。 diff --git a/src/chap02/getstarted.md b/src/chap02/getstarted.md index 62efe90..00003b9 100644 --- a/src/chap02/getstarted.md +++ b/src/chap02/getstarted.md @@ -3,6 +3,6 @@ 本章节将会介绍： -* RuxOS 的编译参数说明 +* RuxOS 的编译参数说明及常用的运行命令 * 如何使用 RuxOS 运行现有的应用 diff --git a/translations/en/chap02/arguments.md b/translations/en/chap02/arguments.md index 2523eb1..99e9d7a 100644 --- a/translations/en/chap02/arguments.md +++ b/translations/en/chap02/arguments.md @@ -1,62 +1,116 @@ - # Compilation Parameter Explanation -RuxOS provides a set of compilation parameters that may seem intricate but offer flexibility and clarity for building and running various types of applications. +RuxOS provides a set of comprehensive but flexible and explicit compilation parameters to build and run various types of applications. -**General Options:** +## General Options -| Option | Description | +| General Options | | | --- | --- | -| ARCH | Target architecture: x86_64, riscv64, aarch64. Default is x86_64. | -| PLATFORM | Target platform defined in the `platforms` directory. This parameter can be user-defined or generated based on the `ARCH` parameter, containing platform-specific parameter definitions. | -| SMP | Number of CPU cores. If greater than 1, it enables multi-core features. Default is 1. | +| ARCH | Target architecture: x86_64, riscv64, aarch64. The default architecture is x86_64. | +| PLATFORM | Target platform defined in the `platforms` directory. This parameter can be user-defined or generated based on the `ARCH` parameter. It contains platform-specific parameter definitions. | +| SMP | Number of CPU cores. If this parameter is greater than 1, multi-core features will be enabled. The default value is 1. | | MODE | Mode related to `cargo build`, default is release. | | LOG | Log level: warn, error, info, debug, trace. Default is warn. | | V | Verbose level: (empty), 1, 2 | -| ARGS | Command line arguments, comma-separated, no spaces, can be empty. Used to pass specific parameters to applications, i.e., `argc`, `argv`. | -| ENVS | Environment variable parameters, comma-separated, no spaces, can be empty. | +| ARGS | Command-line arguments, separated by commas without spaces, can be empty. Used to pass specific arguments to the application, i.e., `argc`, `argv`. | +| ENVS | Environment variable parameters, separated by commas without spaces, can be empty. | -**Application Options:** +## Application Options -| Option | Description | +| App Options | | | --- | --- | -| A/APP | Path to the application directory. Supports relative and absolute paths. Default points to `apps/c/helloworld.` | -| FEATURES | Features of RuxOS modules. Used to enable additional features desired by the user without needing to appear in the specific application's `features.txt` file. | +| A/APP | Path to the application directory. Supports both relative and absolute paths. Defaults to `apps/c/helloworld.`. | +| FEATURES | Features of RuxOS modules. This parameter is used to enable additional features desired by the user on the command line without needing to appear in the specific application's `features.txt` file. | | APP_FEATURES | Additional features for Rust applications. | -**Qemu Options:** +## Qemu Options -| Option | Description | +| Qemu Options | | |---|---| -| BLK | Enable qemu virtio-blk backend. Set if the application requires persistent data or passing configuration files through the file system. | -| NET | Enable qemu virtio-net backend. Set if the application requires network usage. | +| BLK | Enable qemu virtio-blk backend. Set this parameter if the application needs to persist data or pass configuration files through the file system. | +| NET | Enable qemu virtio-net backend. Set this parameter if the application needs to use networking. | | GRAPHIC | Enable qemu virtio-gpu backend for graphical output. | -| BUS | Select device bus type: mmio, pci. | +| BUS | Choose device bus type: mmio, pci. | | DISK_IMG | Path to the file system disk image. Default is `disk.img` in the root directory. | | ACCEL | Enable x86 KVM hardware acceleration. | -| QEMU_LOG | Enable qemu logs, default output to `qemu.log` file, containing executed assembly code. | -| NET_DUMP | Network packet capture, output to `netdump.pcap` file in the root directory. | +| QEMU_LOG | Enable qemu logging, default output to `qemu.log` file including executed assembly code. | +| NET_DUMP | Capture network packets, output to `netdump.pcap` file in the root directory. | | NET_DEV | Qemu network device type: user, tap. | +| START_PORT | Starting port number opened by qemu (default is port 5555). | +| PORTS_NUM | Number of ports opened by qemu (default is 5). | -**9P Options:** +## 9P Options -| Option | Description | +| 9P Options | | |---|---| -| V9P_PATH | File directory on the host for sharing. Default is the root directory. | -| NET_9P_ADDR| Address and port for 9p netdev. Default is `127.0.0.1:564`. | +| V9P_PATH | File directory for sharing on the host. Default is the root directory. | +| NET_9P_ADDR | Address and port for 9p netdev. Default is `127.0.0.1:564`. | | ANAME_9P | Path for 9pfs. | | PROTOCOL_9P | 9p protocol type. | -**Network Options**, default port is 5555: +## Network Options (Default Port 5555) -| Option | Description | +| Network Options | | |---|---| -| IP | RuxOS IPv4 address (qemu user netdev, default is 10.0.2.15). | +| IP | Ruxos IPv4 address (qemu user netdev, default is 10.0.2.15). | | GW | Gateway IPv4 address (qemu user netdev, default is 10.0.2.2). | -**Libc Options:** +## Libc Options -| Option | Description | +| Libc Options | | |---|---| | MUSL | Use musl libc for compilation and linking. By default, RuxOS uses `ruxlibc`. Users can enable musl libc by setting `MUSL=y`. | +# Commands + +RuxOS provides various run commands to meet different needs, including compilation, execution, and debugging. These commands should be run in the RuxOS root directory. + +## make build + +Compile the specified application, defaulting to the `helloworld` application, and generate a binary kernel file suitable for direct execution by qemu. + +## make run + +Run the specified application, including the `make build` process, and pass the generated binary kernel file to qemu. Qemu parameters are generated based on the [compilation parameters](#Compilation-Parameter-Explanation) declared by the user. + +## make disasm + +Disassemble the binary instructions executed and generate a file containing all assembly instructions executed during the run. + +## make debug + +Start GDB for debugging. + +## make disk_img + +Generate a FAT32 image file using `dd` and `mkfs` commands, and pass it to qemu as a disk file. + +When dealing with programs that require filesystems or block device storage, you need to provide qemu with a block device. + +## make clean_c + +Clean `libc.a` of `ruxlibc` and the `app-objs` declared by C applications. If the corresponding application's `axbuild.mk` also includes `clean_c`, it will be executed accordingly. + +## make clean_musl + +Clean the install directory and build directory generated by musl libc. After this command, musl libc-related applications will be recompiled when run. + +## make clean + +This command includes `make clean_c` and `make clean_musl`, and also cleans up elf files and bin files of applications, and executes `cargo clean`. + +## make clippy + +Perform code linting using clippy. + +## make fmt + +Format Rust code using `cargo fmt`. + +## make fmt_c + +Format C code according to standards. + +## make test + +Test the applications in the `apps/` directory by comparing their output with the corresponding `.out` files to determine whether they are correct. diff --git a/translations/en/chap02/getstarted.md b/translations/en/chap02/getstarted.md index bf200c3..a62c413 100644 --- a/translations/en/chap02/getstarted.md +++ b/translations/en/chap02/getstarted.md @@ -3,6 +3,6 @@ This chapter will cover: -* Explanation of RuxOS compilation parameters +* Explanation of compilation parameters for RuxOS and commonly used commands. * How to use RuxOS to run existing applications