构建工作负载（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:

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:

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:

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"':

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:

#!/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:

# 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:

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:

# 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".