doc: 添加用户程序构建文档 & 环境变量介绍文档 (#92)

Signed-off-by: longjin <[email protected]>

README.md

@@ -11,21 +11,12 @@ DADK是一个用于开发DragonOS应用的工具包，设计目的是为了让
 
 DADK的文档托管在[DADK Docs](https://docs.dragonos.org.cn/p/dadk/)上。
 
-### DADK做什么？
+## DADK有什么用？
 
-- 自动配置libc等编译用户程序所需的环境
-- 自动处理软件库的依赖关系
-- 自动处理软件库的编译
-- 一键将软件库安装到DragonOS系统中
+- 管理DragonOS应用的编译与安装
+- 对DragonOS内核进行profiling
+- 管理DragonOS的镜像构建、虚拟机运行
 
-### DADK不做什么？
-
-- DADK不会帮助开发者编写代码
-- DADK不提供任何开发DragonOS应用所需的API。这部分工作由libc等库来完成
-
-## License
-
-DADK is licensed under the [GPLv2 License](LICENSE).
 
 ## 快速开始
 
@@ -42,56 +33,12 @@ cargo install dadk
 
 ```
 
-## DADK的工作原理
-
-DADK使用(任务名，任务版本）来标识每个构建目标。当使用DADK构建DragonOS应用时，DADK会根据用户的配置文件，自动完成以下工作：
-
-- 解析配置文件，生成DADK任务列表
-- 根据DADK任务列表，进行拓扑排序。这一步会自动处理软件库的依赖关系。
-- 收集环境变量信息，并根据DADK任务列表，设置全局环境变量、任务环境变量。
-- 根据拓扑排序后的DADK任务列表，自动执行任务。
-
-### DADK与环境变量
-
-环境变量的设置是DADK能正常工作的关键因素之一，您可以在您的编译脚本中，通过引用环境变量，来获得其他软件库的编译信息。
-这是使得您的应用能够自动依赖其他软件库的关键一步。
-
-只要您的编译脚本能够正确地引用环境变量，DADK就能够自动处理软件库的依赖关系。
-
-#### 全局环境变量
+然后，转到[Quick Start](https://docs.dragonos.org.cn/p/dadk/user-manual/quickstart.html)以开始使用DADK。
 
-DADK会设置以下全局环境变量：
-
-- `DADK_CACHE_ROOT`：DADK的缓存根目录。您可以在编译脚本中，通过引用该环境变量，来获得DADK的缓存根目录。
-- `DADK_BUILD_CACHE_DIR_任务名_任务版本`：DADK的任务构建结果缓存目录。当您要引用其他软件库的构建结果时，可以通过该环境变量来获得。
-同时，您也要在构建您的app时，把构建结果放到您的软件库的构建结果缓存目录（通过对应的环境变量获得）中。
-- `DADK_SOURCE_CACHE_DIR_任务名_任务版本`：DADK的某个任务的源码目录。当您要引用其他软件库的源码目录时，可以通过该环境变量来获得。
-
-#### 任务环境变量
-
-- DADK会为每个任务设置其自身在配置文件中指定的环境变量。
-- DADK会设置`DADK_CURRENT_BUILD_DIR`环境变量，其值与`DADK_BUILD_CACHE_DIR_任务名_任务版本`相同。方便您在编译脚本中引用，把构建结果拷贝到这里。
-
-
-
-#### 全局环境变量命名格式
-
-全局环境变量中的任务名和任务版本，都会被转换为大写字母，并对特殊字符进行替换。替换表如下：
-
-| 原字符 | 替换字符 |
-| ------ | -------- |
-| `.`    | `_`      |
-| `-`    | `_`      |
-| `\t`   | `_`      |
-| 空格   | `_`      |
-| `+`    | `_`      |
-| `*`    | `_`      |
-
-**举例**：对于任务`libc-0.1.0`，其构建结果的全局环境变量名为`DADK_BUILD_CACHE_DIR_LIBC_0_1_0`。
+## License
 
+DADK is licensed under the [GPLv2 License](LICENSE).
 
-## TODO
+## Contributing
 
-- 支持从在线归档文件下载源码、构建好的软件库
-- 支持自动更新
-- 完善clean命令的逻辑
+欢迎贡献代码！请参阅[开发者指南](https://docs.dragonos.org.cn/p/dadk/dev-guide/)以了解如何贡献代码。

docs/.vuepress/config.js

@@ -50,6 +50,8 @@ export default defineUserConfig({
                         children: [
                             '/user-manual/quickstart.md',
                             '/user-manual/profiling.md',
+                            '/user-manual/user-prog-build.md',
+                            '/user-manual/envs.md',
 
                         ]
                     }

docs/user-manual/README.md

@@ -7,3 +7,5 @@
 
 - [Quick Start - 快速开始！](./quickstart.md)
 - [对DragonOS内核进行性能分析](./profiling.md)
+- [构建用户程序](./user-prog-build.md)
+- [环境变量](./envs.md)

docs/user-manual/envs.md

@@ -0,0 +1,51 @@
+# 环境变量
+
+## 1. DADK为什么设置环境变量？
+
+在构建用户程序的过程中，DADK会设置一些环境变量，使得：
+
+- 构建脚本能够知道把构建产物放到哪里。
+- 构建脚本能够知道它的依赖项的构建输出目录在哪里，以便引用它们。
+
+## 2. 环境变量的分类
+
+在DADK构建用户程序的过程中，环境变量分为两种：
+
+- 全局环境变量：这些变量在所有构建任务中都可用。
+- 任务环境变量：这些变量仅在当前任务中可用。通过[dadk用户程序配置文件](https://github.com/DragonOS-Community/DADK/blob/main/dadk-config/templates/config/userapp_config.toml)的`envs`字段设置。
+
+## 3. 全局环境变量
+
+
+
+### 3.1 变量列表
+
+DADK在构建用户程序的过程中，将会设置以下全局环境变量：
+
+- `DADK_CACHE_ROOT`：DADK的缓存根目录。您可以在编译脚本中，通过引用该环境变量，来获得DADK的缓存根目录。
+- `DADK_BUILD_CACHE_DIR_任务名_任务版本`：DADK的任务构建结果缓存目录。当您要引用其他软件库的构建结果时，可以通过该环境变量来获得。
+同时，您也要在构建您的app时，把构建结果放到您的软件库的构建结果缓存目录（通过对应的环境变量获得）中。
+- `DADK_SOURCE_CACHE_DIR_任务名_任务版本`：DADK的某个任务的源码目录。当您要引用其他软件库的源码目录时，可以通过该环境变量来获得。
+- `DADK_CURRENT_BUILD_DIR`：当前任务的构建结果输出目录。您可以在编译脚本中，通过引用该环境变量，来获得当前任务的构建结果输出目录。构建完成时，您的构建脚本应当把构建结果放到该目录中。
+
+### 3.2 名称字符替换
+
+由于环境变量的名称不能包含某些字符，而全局环境变量会引用任务的名称、版本号信息。
+因此，在设置环境变量时，DADK会对变量名称进行字符替换。
+
+具体规则如下：
+
+- 将所有字母转为大写。
+- 按照下表对其他字符进行替换
+
+
+| 原字符 | 替换字符 |
+| ------ | -------- |
+| `.`    | `_`      |
+| `-`    | `_`      |
+| `\t`   | `_`      |
+| 空格   | `_`      |
+| `+`    | `_`      |
+| `*`    | `_`      |
+
+**举例**：对于任务`libc-0.1.0`，其构建结果缓存目录的全局环境变量名为`DADK_BUILD_CACHE_DIR_LIBC_0_1_0`。

docs/user-manual/user-prog-build.md

@@ -0,0 +1,31 @@
+# 构建用户程序
+
+::: tip
+在阅读本文之前，请确保你已经读过了[Quick Start](./quickstart.md)
+:::
+
+## DADK的工作原理
+
+DADK使用`(任务名，任务版本）`二元组来标识每个构建目标。
+
+当使用DADK构建DragonOS应用时，DADK会根据用户的配置文件，自动完成以下工作：
+
+- 解析配置文件，生成DADK任务列表
+- 根据DADK任务列表，进行拓扑排序。这一步会自动处理任务的依赖关系。
+- 收集环境变量信息，并根据DADK任务列表，设置全局环境变量、任务环境变量。
+- 根据拓扑排序后的DADK任务列表，自动执行任务。
+- 从各个任务的输出缓存目录中，收集构建结果，拷贝到`bin/sysroot`目录下。
+
+## 我该如何编写我的构建脚本？
+
+你可以参考这个示例：
+
+- [http server示例程序](https://code.dragonos.org.cn/xref/DragonOS-0.1.10/user/apps/http_server/Makefile)
+
+原理就是，在构建阶段时，把程序拷贝到`DADK_CURRENT_BUILD_DIR`目录下。
+
+## 我该如何编写dadk用户程序编译配置文件？
+
+DADK用户程序编译配置文件的模版里面，有详细的注释，你可以参考这个：
+
+- [userapp_config.toml](https://github.com/DragonOS-Community/DADK/blob/main/dadk-config/templates/config/userapp_config.toml)