test-suite Makefile 指南 (已弃用)

概述

首先，所有测试都在 LLVM 对象目录树中执行。它们不会在 LLVM 源代码树内部执行。这是因为测试套件在执行期间会创建临时文件。

要运行测试套件，您需要使用以下步骤

  1. 使用以下命令检出 test-suite 模块

    % git clone https://github.com/llvm/llvm-test-suite.git test-suite

  2. FIXME: 这些指示已过时，并且无法工作。弄清楚正确的做法是什么，并在此处写下来。

  3. 配置和构建 llvm。

  4. 配置和构建 llvm-gcc。

  5. 将 llvm-gcc 安装到某个位置。

  6. 在您要运行测试套件的每个构建树（LLVM 对象目录树）的顶层重新配置 llvm，就像在构建 LLVM 之前所做的那样。

    在重新配置期间，您必须：（1）将您刚刚构建的 llvm-gcc 放在您的路径中，或者（2）使用 --with-llvmgccdir=$LLVM_GCC_DIR 指定您刚刚构建的 llvm-gcc 的安装目录。

    您还必须告知配置机制测试套件可用，以便可以为您的构建树配置它

    % cd $LLVM_OBJ_ROOT ; $LLVM_SRC_ROOT/configure [--with-llvmgccdir=$LLVM_GCC_DIR]

    [请记住 $LLVM_GCC_DIR 是您安装 llvm-gcc 的目录，而不是其 src 或 obj 目录。]

  7. 现在，您可以从您的构建树中运行测试套件，如下所示

    % cd $LLVM_OBJ_ROOT/projects/test-suite
% make

请注意，第二步和第三步只需要完成一次。在您检出并配置了套件之后，您无需再次执行（除非测试代码或配置脚本发生更改）。

配置外部测试

为了运行 test-suite 模块中的外部测试，您必须指定 –with-externals。这必须在重新配置步骤（见上文）期间完成，并且 llvm 重新配置必须识别先前构建的 llvm-gcc。如果缺少或忽略了任何一项，外部测试将无法工作。

  • –with-externals

  • –with-externals=<目录>

这告诉 LLVM 在哪里可以找到任何外部测试。 它们应该在 <directory> 的特定命名的子目录中。 如果 directory 未指定，configure 将使用默认值 /home/vadve/shared/benchmarks/speccpu2000/benchspec。 LLVM 已知的子目录名称包括

  • spec95

  • speccpu2000

  • speccpu2006

  • povray31

其他子目录会不时添加，可以从 configure 中确定。

运行不同的测试

除了常规的“整个程序”测试之外，test-suite 模块还提供了一种以不同方式编译程序的机制。 如果在 gmake 命令行上定义了变量 TEST，则测试系统将包含一个名为 TEST.<TEST 变量的值>.Makefile 的 Makefile。 此 Makefile 可以修改构建规则以产生不同的结果。

例如，LLVM 夜间测试器使用 TEST.nightly.Makefile 来创建夜间测试报告。 要运行夜间测试，请运行 gmake TEST=nightly。

树中提供了几个 TEST Makefile。 其中一些是为 LLVM 内部研究而设计的，在 LLVM 研究组之外无法工作。 然而，它们仍然可能很有价值，可以作为为您使用 LLVM 开发的任何优化或分析 Pass 编写您自己的 TEST Makefile 的指南。

生成测试输出

有很多方法可以运行测试并生成输出。 最简单的方法是简单地运行不带参数的 gmake。 这将编译并使用多种不同的方法运行树中的所有程序，并比较结果。 任何失败都会在输出中报告，但很可能淹没在其他输出中。 Pass 不会显式报告。

稍好一点的方法是运行 gmake TEST=sometest test，它运行指定的测试，并且通常会在输出中添加每个程序的摘要（取决于您使用的 sometest）。 例如，nightly 测试在每个程序之后显式输出 TEST-PASS 或 TEST-FAIL。 尽管这些行仍然淹没在输出中，但在 Output 目录中 grep 输出日志很容易。

更好的是 report 和 report.format 目标（其中 format 是 html、csv、text 或 graphs 之一）。 报告的确切内容取决于您正在运行的 TEST，但文本结果始终在运行结束时显示，结果始终存储在 report.<type>.format 文件中（当使用 TEST=<type> 运行时）。 report 还会生成一个名为 report.<type>.raw.out 的文件，其中包含整个测试运行的输出。

为 test-suite 编写自定义测试

假设您可以运行测试套件（例如，“gmake TEST=nightly report”应该可以工作），那么针对树中的每个程序运行优化或代码生成器组件，收集统计信息或运行自定义正确性检查非常容易。 基本上，这就是夜间测试器的工作方式，它只是一个通用框架的示例。

假设您有一个 LLVM 优化 Pass，并且您想查看它触发了多少次。 您应该做的第一件事是向您的 Pass 添加一个 LLVM 统计信息，它将统计您关心的事物的计数。

接下来，您可以设置一个测试和一个报告，以收集这些信息并将其格式化以便于查看。 这由两个文件组成，一个“test-suite/TEST.XXX.Makefile”片段（其中 XXX 是您的测试名称）和一个“test-suite/TEST.XXX.report”文件，该文件指示如何将输出格式化为表格。 测试套件中包含许多不同复杂程度的示例报告，并且该框架非常通用。

如果您有兴趣测试优化 Pass，请查看 “libcalls” 测试作为示例。 它可以像这样运行

% cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level
% make TEST=libcalls report

这将执行一堆操作，然后最终打印一个类似这样的表格

Name                                  | total | #exit |
...
FreeBench/analyzer/analyzer           | 51    | 6     |
FreeBench/fourinarow/fourinarow       | 1     | 1     |
FreeBench/neural/neural               | 19    | 9     |
FreeBench/pifft/pifft                 | 5     | 3     |
MallocBench/cfrac/cfrac               | 1     | *     |
MallocBench/espresso/espresso         | 52    | 12    |
MallocBench/gs/gs                     | 4     | *     |
Prolangs-C/TimberWolfMC/timberwolfmc  | 302   | *     |
Prolangs-C/agrep/agrep                | 33    | 12    |
Prolangs-C/allroots/allroots          | *     | *     |
Prolangs-C/assembler/assembler        | 47    | *     |
Prolangs-C/bison/mybison              | 74    | *     |
...

这基本上是 grep -stats 输出并将其显示在表格中。 您还可以使用 “TEST=libcalls report.html” 目标以 HTML 格式获取表格，对于 report.csv 和 report.tex 也是如此。

此源代码位于 test-suite/TEST.libcalls.* 中。 格式非常简单：Makefile 指示如何运行测试（在本例中为 “opt -simplify-libcalls -stats”），并且报告包含输出的每一列的一行。 第一个值是列的标题，第二个值是 grep 命令输出的正则表达式。 有很多示例报告可以执行复杂的操作。