Add the Ruxgo book and update README.md

.gitignore

@@ -5,4 +5,5 @@ compile_commands.json
 ruxos_bld
 sqlite-amalgamation-3410100
 file.sqlite
-dump.rdb
+dump.rdb
+iperf

README.md

@@ -1,8 +1,8 @@
 # Ruxgo
 
-Ruxgo is a Cargo-like build tool for building C and C++ applications that relies solely on a toml file. It abandons the complex syntax and rule-dependent construction in the original MAKE tool, exposing the most original compilation process. If you hate using Makefile, might as well try Ruxgo to build applications, just take a few minutes!
+Ruxgo is a Cargo-like build tool for building C and C++ applications that relies solely on a Toml file. 
 
-For a project you want to build, you just need to figure out the source file path, header file path, cflags and ldflags, then fill them into the appropriate places in the toml file. Ruxgo does the rest, so easy!
+**To start using Ruxgo**, learn more at The Ruxgo Book.
 
 🚧 Working In Progress. 
 
@@ -16,7 +16,7 @@ Once you have installed Rust, the following command can be used to build and ins
 cargo install --git https://github.com/Ybeichen/ruxgo.git ruxgo
 ```
 
-This will automatically download `ruxgo`, build it, and install it in Cargo's global binary directory (`~/.cargo/bin/` by default).
+This will automatically download Ruxgo, build it, and install it in Cargo's global binary directory (`~/.cargo/bin/` by default).
 
 To uninstall, run the command `cargo uninstall ruxgo`.
 
@@ -32,55 +32,9 @@ To uninstall, run the command `cargo uninstall ruxgo`.
 * [x] Supported ruxlibc and ruxmusl
 * [ ] Create new project
 
-## Usage
+## Quickstart & Ruxgo-apps
 
-Write a `config_linux.toml` for linux and `config_win32.toml` for windows in the project directory.
-
-You can then build the project with:
-```console
-ruxgo -b
-```
-
-Once built, you can execute the project via:
-```console
-ruxgo -r
-```
-
-For help:
-```console
-ruxgo --help
-```
-
-The help command will show you the following:
-```sh
-Usage: ruxgo [OPTIONS] [CHOICES]... [COMMAND]
-
-Commands:
-  init    Initialize a new project Defaults to C++ if no language is specified
-  config  Configuration settings
-  help    Print this message or the help of the given subcommand(s)
-
-Arguments:
-  [CHOICES]...  Choose which parts to delete
-
-Options:
-  -b, --build                   Build your project
-  -c, --clean                   Clean the obj and bin intermediates
-  -r, --run                     Run the executable
-      --bin-args <BIN_ARGS>...  Arguments to pass to the executable when running
-      --gen-cc                  Generate compile_commands.json
-      --gen-vsc                 Generate .vscode/c_cpp_properties.json
-      --update-packages         Update packages
-      --restore-packages        Restore packages
-  -h, --help                    Print help
-  -V, --version                 Print version
-```
-
-You can also configure the log level with the environment variable `"RUXGO_LOG_LEVEL"`, the default log level is "Info".
-
-## Ruxgo-apps
-
-The `apps/` directory places all the toml files that have been tested. Currently, there are two ways to build an app: locally and on ruxos
+The `apps/` directory places all the Toml files that have been tested, you can switch to either directory and follow the instructions to build the application. Currently, there are two ways to build an app:
 
 - If building locally, you'll need to download the apps source code and then use ruxgo to build and run it.
 
@@ -98,128 +52,23 @@ The `apps/` directory places all the toml files that have been tested. Currently
 * [x] nginx
 * [ ] python3
 
-## TOML Module Description
-
-Toml file consists of one **[build]** module and multiple **[targets]** modules. If you want to run on ruxos, you can add the **[os]** module. Here is a description of each module:
-
-The **[build]** module describes the compiler type and remote library packages. It contains two parts: `compiler` and `packages`.
-
-- `compiler`: Specifies the compiler type, for example: "gcc".
-- `packages`: Optional, mainly used to get the app source code from Github, and then by parsing the `config_linux.toml` file in it to get the required libraries. When using packages, you need to specify the remote repository and branch.
-
-The **[targets]** module is the core part of the Toml and is used to describe the source build process and dependencies between libraries, as described below:
-
-- `name`: Specifies the target name, if it is of the "dll" type, must begin with "lib_".
-- `src`：Specifies the path to the target source code.
-- `src_excluded`：Optional. if you want to exclude some source files or directories, you can specify here.
-- `include_dir`：Specifies the path to the header file in the target source code, which allows string and vector types.
-- `type`：Specifies the type of the target, which can be of type "static", "dll", "object", or "exe". It should be noted that there can be only one "exe" target in a toml file, but there can be multiple targets of other types.
-- `cflags`：Specifies the compilation options of the target.
-- `archive`：Optional. If the targets type is static, you can specify an archive tool to create the static library.
-- `linker`: Optional. Specifies the linking tool is used to link object files, static libraries, and dynamic libraries. If the value is missing, it is specified according to the `compiler`.
-- `ldflags`：Specifies the link options of the target.
-- `deps`：Specifies other targets to depend on.
-
-The **[os]** module is optional. If you want to run locally, **[config]** and **[targets]** are completely satisfied, if you want to run on ruxos, you can add the **[os]** module. After adding the **[os]** module, the original content of the corresponding **[targets]** modules will be changed. Ruxgo runs smoothly on ruxos by changing compiler, cflags, and ldflags in the backend, such as:
-
-When the platform of the **[os]** module is "x86_64-qemu-q35", the compiler is no longer "gcc", it becomes "x86_64-linux-musl-gcc". Also, all **[targets]** cflags are added with "-nostdinc -fno-builtin -ffreestanding -Wall" by default, you do not need to add them manually. Accordingly, when the type of **[targets]** is "exe", ldflags adds "-nostdlib -static -no-pie --gc-sections" by default. Of course, there are other default additions depending on architecture and platform. Just like, you just need to splice the **[os]** module onto a module that can run locally! The details are as follows:
-
-- `name`: Specifies the name of the os.
-- `services`: Specifies the services that the os can provide, similar to the features in ruxos.
-- `ulib`: The user library you want to use, the options are: "ruxlibc", "ruxmusl".
-- `platform`：If needed, configure it in **[os.platform]**.
-
-If you want to configure the platform further, you can do so in **[os.platform]** , if empty, take the default value. The details are as follows:
-
-- `name`: Specifies what platform you want the os to run on, including: "x86_64-qemu-q35", "aarch64-qemu-virt", "riscv64-qemu-virt". The default value is "x86_64-qemu-q35".
-- `smp`: Specifies the number of CPUs. The default value is "1".
-- `mode`: Specifies the build mode, including: "release","debug". The default value is "release".
-- `log`: Specifies the log level, including: "warn", "error", "info", "debug", and "trace". The default value is "warn".
-- `v`: Specifies the Verbose level, including: "", "1", "2". The default value is "".
-- `qemu`: If needed, configure it in **[os.platform.qemu]**.
-
-If your platform depends on qemu, you'll need to configure it further in **[os.platform.qemu]**, if empty, take the default value. The details are as follows:
-
-- `blk`: Specifies whether to enable storage devices (virtio-blk). The default value is "n".
-- `net`: Specifies whether to enable network devices (virtio-net). The default value is "n".
-- `graphic`: Specifies whether to enable display devices and graphic output (virtio-gpu). The default value is "n".
-- `disk_img`: Specifies the path to the virtual disk image. The default value is "./disk_img".
-- `v9p`: Specifies whether to enable virtio-9p devices. The default value is "n".
-- `v9p_path`: Specifies the host path for backend of virtio-9p. The default value is "./".
-- `qemu_log`: Specifies whether to enable QEMU logging (log file is "qemu.log"). The default value is "n".
-- `net_dump`: Specifies whether to enable network packet dump (log file is "netdump.pcap"). The default value is "n".
-- `net_dev`: Specifies QEMU netdev backend types: "user" or "tap". The default value is "user".
-- `ip`: Specifies IPv4 address of os. The default value is "10.0.2.15" for QEMU user netdev.
-- `gw`: Specifies gateway of IPv4 address. The default value is "10.0.2.2" for QEMU user netdev.
-- `args`: Specifies the command-line arguments, separated by comma. It is used to pass specific variables, like `argc`, `argv`. The default value is "".
-- `envs`: Specifies the environment variables, separated by comma between key value pairs. The default value is "".
-
-Sample file with a library and an executable (run locally):
-
-```toml
-[build]
-compiler = "gcc"
-
-[[targets]]
-name = "libsqlite3"
-src = "./sqlite-amalgamation-3410100"
-src_excluded = ["shell.c"]
-include_dir = "./sqlite-amalgamation-3410100"
-type = "static"
-cflags = "-w -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_FLOATING_POINT -DSQLITE_OMIT_LOAD_EXTENSION -DSQLITE_DEBUG"
-archive = "ar"
-ldflags = "rcs"
-
-[[targets]]
-name = "local_sqlite3"
-src = "./"
-src_excluded = ["sqlite-amalgamation-3410100"]
-include_dir = "./"
-type = "exe"
-cflags = ""
-ldflags = ""
-deps = ["libsqlite3"]
+## Usage
+
+Write a `config_linux.toml` for linux and `config_win32.toml` for windows in the project directory.
+
+You can then build the project with:
+```console
+ruxgo -b
+```
+
+Once built, you can execute the project via:
+```console
+ruxgo -r
 ```
 
-Sample file with a library and an executable (run on ruxos):
-
-```toml
-[build]
-compiler = "gcc"
-
-[os]
-name = "ruxos"
-services = ["fp_simd","alloc","paging","fs","blkfs"]
-ulib = "ruxlibc"
-
-[os.platform]
-name = "x86_64-qemu-q35"
-smp = "4"
-mode = "release"
-log = "error"
-
-[os.platform.qemu]
-blk = "y"
-graphic = "n"
-
-[[targets]]
-name = "libsqlite3"
-src = "./sqlite-amalgamation-3410100"
-src_excluded = ["shell.c"]
-include_dir = "./sqlite-amalgamation-3410100"
-type = "static"
-cflags = "-w -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_FLOATING_POINT -DSQLITE_OMIT_LOAD_EXTENSION -DSQLITE_DEBUG"
-archive = "ar"
-ldflags = "rcs"
-
-[[targets]]
-name = "ruxos_sqlite3"
-src = "./"
-src_excluded = ["sqlite-amalgamation-3410100"]
-include_dir = "./"
-type = "exe"
-cflags = ""
-linker = "rust-lld -flavor gnu"
-ldflags = ""
-deps = ["libsqlite3"]
+For help:
+```console
+ruxgo --help
 ```
+
+You can also configure the log level with the environment variable `"RUXGO_LOG_LEVEL"`, the default log level is "Info".

apps/iperf/README.md

@@ -5,13 +5,12 @@
 Firstly, clone github repository of iperf and configure it: 
 
 ```bash
-git clone -b 3.1-STABLE https://github.com/esnet/iperf.git
-./configure
+git clone -b 3.1-STABLE https://github.com/esnet/iperf.git && cd iperf && ./configure
 ```
 
 Then, you need to copy `config_linux.toml` from `ruxgo/apps/iperf/local` and place it in the `iperf/` directory you just downloaded. 
 
-Finally, execute the following commands to build and run it:
+Finally, cd into `iperf/` and execute the following commands to build and run it:
 
 ```bash
 # Build and Run

apps/redis/README.md

@@ -2,15 +2,15 @@
 
 ## 1. Build and run locally
 
-Firstly, clone github repository of redis and configure it: 
+Firstly, get the redis source code and configure it: 
 
 ```bash
 wget https://github.com/redis/redis/archive/7.0.12.tar.gz
 tar -zxvf 7.0.12.tar.gz && rm -f 7.0.12.tar.gz
 cd redis-7.0.12/src && ./mkreleasehdr.sh && cd ../..
 ```
 
-Then, you need to copy `config_linux.toml` from `ruxgo/apps/redis/local` and place it in the `redis-7.0.12/` directory you just downloaded. 
+Then, you need to copy `config_linux.toml` from `ruxgo/apps/redis/local` and place it in the `redis-7.0.12/` directory that you just downloaded. 
 
 Finally, cd into `redis-7.0.12`/ and execute the following commands to build and run it:
 

apps/sqlite3/README.md

@@ -8,8 +8,9 @@ Firstly, get the sqlite3 source code:
 wget https://sqlite.org/2023/sqlite-amalgamation-3410100.zip
 unzip sqlite-amalgamation-3410100.zip && rm -f sqlite-amalgamation-3410100.zip
 ```
+Then, you need to copy `config_linux.toml` and `main.c` from `ruxgo/apps/redis/local` into the same directory as `sqlite-amalgamation-3410100` that you just downloaded.
 
-Then, execute the following commands to build and run it (the main.c already exists):
+Finally, execute the following commands to build and run it:
 
 ```bash
 # Build and Run

doc/README.md

@@ -0,0 +1,24 @@
+# Ruxgo documentation
+
+This directory contains Ruxgo's documentation: The Ruxgo Book which is built with [mdbook](https://github.com/rust-lang/mdBook) .
+
+## Building the book
+
+Building the book requires mdBook. To get it:
+
+```
+$ cargo install mdbook
+```
+
+To build the book:
+
+```
+$ mdbook build
+```
+
+`mdbook` provides a variety of different commands and options to help you work on the book:
+
+- `mdbook build --open`: Build the book and open it in a web browser.
+- `mdbook serve`: Launches a web server on localhost. It also automatically rebuilds the book whenever any file changes and automatically reloads your web browser.
+
+The book contents are driven by the `SUMMARY.md` file, and every file must be linked there.

doc/ruxgo_book/.gitignore

@@ -0,0 +1 @@
+book

doc/ruxgo_book/assets/elasticlunr.js

@@ -0,0 +1,28 @@
+/**
+ * @see https://github.com/HillLiu/docker-mdbook
+ */
+window.elasticlunr.Index.load = (index) => {
+    const FzF = window.fzf.Fzf;
+    const storeDocs = index.documentStore.docs;
+    const indexArr = Object.keys(storeDocs);
+    const ofzf = new FzF(indexArr, {
+      selector: (item) => {
+        const res = storeDocs[item];
+        res.text = `${res.title}${res.breadcrumbs}${res.body}`;
+        return res.text;
+      },
+    });
+    return {
+      search: (searchterm) => {
+        const entries = ofzf.find(searchterm);
+        return entries.map((data) => {
+          const { item, score } = data;
+          return {
+            doc: storeDocs[item],
+            ref: item,
+            score,
+          };
+        });
+      },
+    };
+  };

doc/ruxgo_book/book.toml

@@ -0,0 +1,13 @@
+[book]
+authors = ["Ybeichen"]
+language = "zh"
+multilingual = false
+src = "src"
+title = "Ruxgo 手册"
+
+[output.html]
+curly-quotes = true # Enable smart-punctuation feature for more than quotes.
+git-repository-url = "https://github.com/syswonder/ruxgo"
+search.use-boolean-and = true
+git-repository-icon = "fa-github"
+additional-js = ["assets/fzf.umd.js","assets/elasticlunr.js"]

doc/ruxgo_book/src/SUMMARY.md

@@ -0,0 +1,30 @@
+# Ruxgo Book
+
+[简介](./introduction.md)
+
+* [Ruxgo 安装](./installation.md)
+
+* [Ruxgo 指南](guide/index.md)
+    * [​设计理念](guide/design_principle.md)
+        * [借鉴 Cargo](guide/learn_from_cargo.md)
+        * [C/C++ 构建过程的思考](guide/reflections_on_construct.md)
+        * [Ruxgo 要实现的功能](guide/ruxgo_functionality.md)
+        * [作为 RuxOS 的伴生工具](guide/companion_tool_to_ruxos.md)
+    * [​设计特性](guide/design_features.md)
+    * [TOML 文件说明](guide/toml_file.md)
+        * [builder 模块](guide/builder_module.md)
+        * [target 模块](guide/target_module.md)
+        * [os 模块](guide/os_module.md)
+    * [TOML 文件示例](guide/toml_example.md)
+
+* [Ruxgo 命令](commands/index.md)
+    * [通用命令](commands/general-commands.md)
+        * [ruxgo help](commands/ruxgo-help.md)
+        * [ruxgo version](commands/ruxgo-version.md)
+    * [构建命令](commands/build-commands.md)
+        * [ruxgo build](commands/ruxgo-build.md)
+        * [ruxgo run](commands/ruxgo-run.md)
+        * [ruxgo clean](commands/ruxgo-clean.md)
+
+* [运行不同的app](./run_apps.md)
+

doc/ruxgo_book/src/commands/build-commands.md

@@ -0,0 +1,7 @@
+# 构建命令
+
+* [ruxgo build](./ruxgo-build.md)
+
+* [ruxgo run](./ruxgo-run.md)
+
+* [ruxgo clean](./ruxgo-clean.md)

doc/ruxgo_book/src/commands/general-commands.md

@@ -0,0 +1,5 @@
+# 通用命令
+
+* [ruxgo help](./ruxgo-help.md)
+
+* [ruxgo version](./ruxgo-version.md)