docs: usages: 1.building_outputs

Author: xieby1

docs/usages/1.building_outputs.md

@@ -1,3 +1,239 @@
 # 构建工作负载（Building Workloads）
 
+Deterload是一套基于nix开发的工作负载构建系统。
+构建工作负载主要是使用nix，
+你可能会心头一紧，🙀“我就是想构建一些工作负载，还要需要一套新的编程语言/一个包管理器？”。
+😺放轻松！不用担心！
+尽管nix的完整学习曲线较陡峭，
+但在本项目中，你只需要掌握少量直观的nix命令和语法即可。
 
+Deterload is a workload building system developed based on nix.
+Building workloads mainly involves using nix.
+You might tense up, 🙀 "I just want to build some workloads, why do I need a new programming language/package manager?"
+😺 Relax! Don't worry!
+Although nix has a steep learning curve overall,
+in this project, you only need to master a few intuitive nix commands and syntax.
+
+## 基础构建（Basic Building）
+
+让我们从最简单的例子开始——构建一套OpenBLAS切片。
+只需一行命令：
+
+Let's start with the simplest example — building an OpenBLAS checkpoint.
+It only takes one command:
+
+```bash
+nix-build -A openblas.cpt
+```
+
+这行命令的组成：
+
+* `nix-build`是nix用于构建包的基础命令
+* `-A openblas.cpt`指定了构建目标
+* 提示1：如果你想看详细的构建信息（很酷炫的树形依赖图、任务数统计、时间统计等等），
+  你可以将`nix-build`替换为`nom-build`（一个`nix-build`的第三方包装命令`）。
+* 提示2：其中`openblas`是一个结构体（nix里被成为attribute set，类似python字典），
+  包含了多个OpenBLAS工作负载相关的包，比如`openblas.benchmark`、`openblas.linux`、`openblas.qemu`和`openblas.cpt`等等。
+* 提示3：如果你的shell有命令补全功能，`nix-build -A openblas.`敲tab键能给你补全出openblas里所有的包。
+  其中`openblas.cpt`是我们需要的切片。
+
+This command consists of:
+
+* `nix-build` is nix's basic command for building packages
+* `-A openblas.cpt` specifies the build target
+* Tip 1: If you want to see detailed build information (cool dependency trees, task statistics, time statistics, etc.),
+  you can replace `nix-build` with `nom-build` (a third-party wrapper for `nix-build`).
+* Tip 2: Here `openblas` is a structure (called attribute set in nix, similar to Python dictionary),
+  containing multiple OpenBLAS workload-related packages, such as `openblas.benchmark`, `openblas.linux`, `openblas.qemu`, and `openblas.cpt`, etc.
+* Tip 3: If your shell has command completion, pressing tab after `nix-build -A openblas.` will show all packages in openblas.
+  Among these, `openblas.cpt` is the checkpoint we need.
+
+构建OpenBLAS的切片需要几个小时。
+构建完成后会输出类似这样的路径：
+
+Building an OpenBLAS checkpoin takes several hours.
+After completion, it outputs a path like this:
+
+```
+/nix/store/6rbfs8nx9xiv1s7z5xbi7m6djbkn9sgh-openblas_gcc_1410_RISCV64_GENERIC_glibc_qemu_20M_maxK30_1core_cpt
+```
+
+nix会自动将该路径符号链接到`./result`。
+你可以通过`-o`选项来改变默认符号链接的目标地址：
+
+nix will automatically create a symbolic link to this path at `./result`.
+You can change the default symbolic link target using the `-o` option:
+
+```bash
+nix-build -A openblas.cpt -o result-openblas.cpt
+```
+
+值得注意的是，这一次构建`openblas.cpt`会非常快速。
+这是因为nix采用的确定性构建的机制。
+这一次构建和上一次构建除了名字以外没啥不同，所以nix直接复用之前的构建结果。
+
+Notably, this second build of `openblas.cpt` will be very quick.
+This is due to nix's deterministic build mechanism.
+Since this build is identical to the previous one except for the name, nix directly reuses the previous build result.
+
+## 配参数（Configuring Arguments）
+
+构建产物的路径名（如上面的例子）包含了多个标签，例如：
+
+* 编译器版本（gcc 14.1.0）
+* OpenBLAS的目标架构（RISCV64_GENERIC）
+* ...
+
+The build output path (as in the example above) contains multiple tags, such as:
+
+* Compiler version (gcc 14.1.0)
+* OpenBLAS target architecture (RISCV64_GENERIC)
+* ...
+
+这些标签都是默认配置中预设好的参数。
+我们可以根据自己的需求配置参数。
+Deterload支持三种配置方式：
+
+* 命令行
+* 配置文件
+* 命令行+配置文件
+
+These tags represent parameters set in the default configuration.
+We can configure these parameters according to our needs.
+Deterload supports three configuration methods:
+
+* Command line
+* Configuration file
+* Command line + Configuration file
+
+### 命令行（Command Line）
+
+使用`--arg key value`的方式配置参数，例如：
+
+Configure parameters using `--arg key value`, for example:
+
+```bash
+nix-build --arg enableVector true --arg cpt-maxK '"10"' -A openblas.cpt
+```
+
+* `--arg enableVector true`：启用编译器的自动向量化
+* `--arg cpt-maxK '"10"'：设置simpoint的maxK设为10
+
+注意：nix对参数类型有严格要求。
+比如`enableVector`是一个bool类型，接收true/false。
+`cpt-maxK`是一个字符串类型的参数，因此接收的参数需要加双引号（额外加单引号是为了shell不要吞掉双引号）。
+
+
+* `--arg enableVector true`: Enable compiler auto-vectorization
+* `--arg cpt-maxK '"10"'`: Set simpoint's maxK to 10
+
+Note: nix has strict type requirements for parameters.
+For instance, `enableVector` is a boolean type, accepting true/false.
+`cpt-maxK` is a string parameter, so it needs double quotes (with extra single quotes to prevent shell from stripping the double quotes).
+
+对于字符串类型的参数，双引号单引号过于麻烦，可以用`--argstr key value`来简化`--arg key '"value"'`：
+
+For string parameters, dealing with double and single quotes is cumbersome, so you can use `--argstr key value` to simplify `--arg key '"value"'`:
+
+```bash
+nix-build --arg enableVector true --argstr cpt-maxK 10 -A openblas.cpt
+```
+
+### 配置文件（Configuration File）
+
+你可能会想：“我可以把命令行写入写一个shell脚本，岂不是就有了‘配置文件’了嘛”。像这样：
+
+You might think: "I could write these command lines into a shell script, and that would be a 'configuration file', right?" Like this:
+
+```bash
+#!/usr/bin/env bash
+# 这是一个难以保证确定性构建的“配置文件”
+# This is a "configuration file" that can't guarantee deterministic builds
+nix-build \
+  --arg enableVector true \
+  --argstr cpt-maxK 10 \
+  -A openblas.cpt
+```
+
+这样的“配置文件”并不适合协同开发，因为：
+
+* 不同开发者用的Deterload版本可能不同，构建结果难以一致。
+* 参数名称和含义可能会因版本变化而有所不同。
+
+This type of "configuration file" isn't suitable for collaborative development because:
+
+* Different developers might use different Deterload versions, making build results inconsistent.
+* Parameter names and meanings might change between versions.
+
+为了解决这些问题，我们可以使用nix来编写配置文件。
+例如，以下是一个与上述命令行等价的配置文件：
+
+To solve these issues, we can use nix to write configuration files.
+Here's a configuration file equivalent to the above command line:
+
+```nix
+# vec_maxK10.nix
+{...}@args: import (builtins.fetchTarball {
+  url = "https://github.com/OpenXiangShan/Deterload/archive/v0.1.4.tar.gz";
+  # nix-prefetch-url --unpack https://github.com/OpenXiangShan/Deterload/archive/v0.1.4.tar.gz
+  sha256 = "0l7bfjqjjlxkg8addgm6gkjv7p1psisv1wy648xwa8nw3nmgaw5d";
+}) ({
+  enableVector = true;
+  cpt-maxK = "10";
+} // args)
+```
+
+这段代码主要分成两个部分：
+
+* 固定版本的部分：
+  * `url`设定了Deterload的源码来自GitHub，版本为v0.1.4。
+  * `sha256`是Deterload v0.1.4源码的sha256值，这个nix确定性构建的关键部分。
+    你可以用`nix-prefetch-url`获取此值（见代码注释）。
+* 配置参数的部分：
+  * 配置了`enableVector`和`cpt-maxK`，具体含义与前文一致。
+
+This code consists of two main parts:
+
+* Version fixing part:
+  * `url` specifies that Deterload's source code comes from GitHub, version v0.1.4.
+  * `sha256` is the sha256 value of Deterload v0.1.4 source code, crucial for nix's deterministic building.
+    You can get this value using `nix-prefetch-url` (see code comment).
+* Parameter configuration part:
+  * Configures `enableVector` and `cpt-maxK`, with meanings as explained earlier.
+
+将上述代码保存为文件（例如`vec_maxK10.nix`）。
+每个开发者只需运行以下命令，就能生成二进制级别一致的`openblas.cpt`切片：
+
+Save this code as a file (e.g., `vec_maxK10.nix`).
+Any developer can run the following command to generate a binary-identical `openblas.cpt` checkpoint:
+
+```bash
+nix-build vec_maxK10.nix -A openblas.cpt
+```
+
+比如在我的电脑上获得的结果路径，以及第一个切片的md5sum应该和你得到一样：
+
+For example, the checkpoint path of the result, and the md5sum of the first checkpoint on my computer should match yours:
+
+```bash
+# cd /nix/store/s3wxbj9rcxksn22v9ghlhikf1rvi4ybf-openblas_gcc_1410_RISCV64_ZVL128B_glibc_qemu_20M_maxK10_1core_cpt/miao && ls
+2  186  2343  3274  4093  4668  5991  6285  6357
+# md5sum 2/_2_0.168009.gz
+43305c3b69822ea9fd34b5e08078ad68  result/miao/2/_2_0.168009.gz
+```
+
+### 命令行+配置文件（Command Line + Configuration File）
+
+Deterload支持命令行+配置文件混合的配置方式。
+以上述`vec_maxK10.nix`为例，命令行参数的优先级高于配置文件参数：
+
+Deterload supports mixed configuration using command line and configuration files.
+Using the above `vec_maxK10.nix` as an example, command line parameters take precedence over configuration file parameters:
+
+```
+nix-build vec_maxK10.nix --argstr cpt-maxK 20 --argstr cpt-intervals 1000000 -A openblas.cpt
+```
+
+上述命令覆盖了原本配置文件的`cpt-maxK`改为了`"20"`，并将`cpt-intervals`设置为了`"1000000"`。
+
+This command overrides the original `cpt-maxK` in the configuration file to `"20"` and sets `cpt-intervals` to `"1000000"`.

docs/usages/2.configuring.md

@@ -1,3 +1,3 @@
-# 运行输出的工作负载（Running Output Workloads）
+# 运行工作负载（Running Workloads）
 
 TODO: