Merge pull request #5 from syswonder/dev

Add command explanations in chap02

src/chap02/arguments.md

@@ -2,7 +2,7 @@
 
 RuxOS 提供了看起繁杂但却灵活且明确的编译参数，来针对多种类型的应用进行构建和运行。
 
-**通用参数** ：
+## 通用参数
 
 | General Options | |
 | --- | --- |
@@ -15,15 +15,15 @@ RuxOS 提供了看起繁杂但却灵活且明确的编译参数，来针对多
 | ARGS | 命令行参数，使用逗号分隔，不允许空格，可以为空。用来给应用程序传递具体的参数，即 `argc`，`argv`。 |
 | ENVS | 环境变量参数，使用逗号分隔，不允许空格，可以为空。 |
 
-**应用参数** ：
+## 应用参数
 
 | App Options | |
 | --- | --- |
 | A/APP | 应用程序目录的路径。支持相对路径和绝对路径。默认指向 `apps/c/helloworld.`。 |
 | 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` 文件来判断是否正确。
 
 

src/chap02/getstarted.md

@@ -3,6 +3,6 @@
 
 本章节将会介绍：
 
-* RuxOS 的编译参数说明
+* RuxOS 的编译参数说明及常用的运行命令
 
 * 如何使用 RuxOS 运行现有的应用

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.

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