テストスイートガイド¶

クイックスタート¶

テストを実行するには、litテストランナーが必要です。LLVMビルドから使用するか、

% <path to llvm build>/bin/llvm-lit --version
lit 0.8.0dev

Python仮想環境にPythonパッケージとしてインストールすることもできます。

% python3 -m venv .venv
% . .venv/bin/activate
% pip install git+https://github.com/llvm/llvm-project.git#subdirectory=llvm/utils/lit
% lit --version
lit 0.8.0dev

以下を使用してtest-suiteモジュールをチェックアウトします。
```
% git clone https://github.com/llvm/llvm-test-suite.git test-suite
```
ビルドディレクトリを作成し、CMakeを使用してスイートを構成します。CMAKE_C_COMPILERオプションを使用して、テストするコンパイラを指定します。キャッシュファイルを使用して、一般的なビルド構成を選択します。
```
% mkdir test-suite-build
% cd test-suite-build
% cmake -DCMAKE_C_COMPILER=<path to llvm build>/bin/clang \
        -C../test-suite/cmake/caches/O3.cmake \
        ../test-suite
```

注意！ビルド済みのclangを使用していて、MicroBenchmarks/XRayマイクロベンチマークをビルドして実行する場合は、compiler-rtをLLVM_ENABLE_RUNTIMES cmakeフラグに追加する必要があります。

ベンチマークをビルドします。

% make
Scanning dependencies of target timeit-target
[  0%] Building C object tools/CMakeFiles/timeit-target.dir/timeit.c.o
[  0%] Linking C executable timeit-target
...

litを使用してテストを実行します。

% llvm-lit -v -j 1 -o results.json .
-- Testing: 474 tests, 1 threads --
PASS: test-suite :: MultiSource/Applications/ALAC/decode/alacconvert-decode.test (1 of 474)
********** TEST 'test-suite :: MultiSource/Applications/ALAC/decode/alacconvert-decode.test' RESULTS **********
compile_time: 0.2192
exec_time: 0.0462
hash: "59620e187c6ac38b36382685ccd2b63b"
size: 83348
**********
PASS: test-suite :: MultiSource/Applications/ALAC/encode/alacconvert-encode.test (2 of 474)
...

注意！コンパイル時間の結果（コードサイズ、LLVM統計など）のみを取得する場合でも、上記のllvm-litコマンドを使用してテストを実行する必要があります。その場合、results.jsonファイルにはコンパイル時間メトリックが含まれます。

結果ファイルの表示と比較（オプション）

# Make sure pandas and scipy are installed. Prepend `sudo` if necessary.
% pip install pandas scipy
# Show a single result file:
% test-suite/utils/compare.py results.json
# Compare two result files:
% test-suite/utils/compare.py results_a.json results_b.json

構造¶

テストスイートには、ベンチマークプログラムとテストプログラムが含まれています。プログラムには参照出力も含まれているため、その正確性を確認できます。このスイートには、ベンチマーク実行時間、コンパイル時間、コードサイズなどのメトリックを収集するためのツールが含まれています。

テストスイートはいくつかのディレクトリに分割されています。

SingleSource/

サイズが単一のソースファイルのみのテストプログラムが含まれています。サブディレクトリには複数のプログラムが含まれている場合があります。
MultiSource/

複数のソースファイルを持つプログラム全体を含むサブディレクトリが含まれています。大規模なベンチマークやアプリケーション全体がここにあります。
MicroBenchmarks/

google-benchmarkライブラリを使用するプログラム。プログラムは、測定結果が統計的に有意になるまで複数回実行される関数を定義します。
External/

テストスイートに直接配布できないコードの説明とテストデータが含まれています。このディレクトリの最も重要なメンバーは、SPEC CPUベンチマークスイートです。外部スイートを参照してください。
Bitcode/

これらのテストはほとんどLLVMビットコードで記述されています。
CTMark/

コンパイルパフォーマンス測定のための代表的なサンプルを形成する他のベンチマークへのシンボリックリンクが含まれています。

ベンチマーク¶

すべてのプログラムは正確性のテストとして機能します。パフォーマンス測定には適さないプログラムもあります。TEST_SUITE_BENCHMARKING_ONLY CMakeオプションをONに設定すると、これらのプログラムは無効になります。

MultiSourceベンチマークは、次のアプリとベンチマークで構成されています。

MultiSource	言語	アプリケーション領域	備考
7zip	C/C++	圧縮/解凍
ASCI_Purple	C	SMG2000ベンチマークとソルバー	メモリ集約型アプリ
ASC_Sequoia	C	シミュレーションとソルバー
BitBench	C	uudecode/uuencodeユーティリティ	関数型コンパイラのためのビットストリームベンチマーク
Bullet	C++	Bullet 2.75物理エンジン
DOE-ProxyApps-C++	C++	HPC/科学アプリ	大規模なDOEワークロードの代表的な小型アプリケーション
DOE-ProxyApps-C	C	HPC/科学アプリ	“
Fhourstones	C	ゲーム/ソルバー	コネクト4ゲームの位置を効率的に解決する整数ベンチマーク
Fhourstones-3.1	C	ゲーム/ソルバー	“
FreeBench	C	ベンチマークスイート	レイトレーサー、4目並べ、ニューラルネットワーク、ファイル圧縮、高速フーリエ/コサイン/サイン変換
llubenchmark	C	連結リストマイクロベンチマーク
mafft	C	バイオインフォマティクス	多重配列アラインメントプログラム
MallocBench	C	ベンチマークスイート	cfrac、espresso、gawk、gs、make、p2c、perl
McCat	C	ベンチマークスイート	クイックソート、バブルソート、固有値
mediabench	C	ベンチマークスイート	adpcm、g721、gsm、jpeg、mpeg2
MiBench	C	組み込みベンチマークスイート	自動車、消費者、オフィス、セキュリティ、通信アプリ
nbench	C		BYTE MagazineのBYTEmarkベンチマークプログラム
NPB-serial	C	並列計算	NPB ISコードのシリアルバージョン
Olden	C	データ構造	OldenベンチマークのSGIバージョン
OptimizerEval	C	ソルバー	Preston Briggのオプティマイザ評価フレームワーク
PAQ8p	C++	データ圧縮
Prolangs-C++	C++	ベンチマークスイート	city、employ、life、NP、ocean、primes、simul、vcirc
Prolangs-C	C	ベンチマークスイート	agrep、archie-client、bison、gnugo、unix-smail
Ptrdist	C	ポインタ集約型ベンチマークスイート
Rodinia	C	科学アプリ	backprop、pathfinder、srad
SciMark2-C	C	科学アプリ	FFT、LU、モンテカルロ、疎行列積
sim	C	動的計画法	時間効率的で線形空間の局所類似性アルゴリズム
tramp3d-v4	C++	数値解析	FreePOOMAに基づくテンプレート集約型数値プログラム
Trimaran	C	暗号化	3des、md5、crc
TSVC	C	ベクトル化ベンチマーク	ベクトル化コンパイラ用テストスイート（TSVC）
VersaBench	C	ベンチマークスイート	8b10b、ビームフォーマ、bmm、dbms、ecbdes

すべてのMultiSourceアプリケーションはパフォーマンス測定に適しており、CMakeオプションTEST_SUITE_BENCHMARKING_ONLYが設定されている場合に実行されます。

設定¶

テストスイートには、ベンチマークのビルドと実行をカスタマイズするための設定オプションがあります。CMakeはそれらのリストを出力できます。

% cd test-suite-build
# Print basic options:
% cmake -LH
# Print all options:
% cmake -LAH

一般的な構成オプション¶

CMAKE_C_FLAGS

Cコンパイラの呼び出しに渡す追加のフラグを指定します。フラグはC++コンパイラとリンカの呼び出しにも渡されます。https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.htmlを参照してください。
CMAKE_C_COMPILER

使用するCコンパイラ実行可能ファイルを選択します。path/to/clangを指定する場合、CMakeは自動的にpath/to/clang++をC++コンパイラとして使用することに注意してください。https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.htmlを参照してください。
CMAKE_Fortran_COMPILER

使用するFortranコンパイラ実行可能ファイルを選択します。デフォルトでは設定されておらず、Fortranテストスイートを実行する場合以外は必要ありません。
CMAKE_BUILD_TYPE

OPTIMIZEまたはDEBUGなどのビルドタイプを選択し、定義済みのコンパイラフラグのセットを選択します。これらのフラグはCMAKE_C_FLAGSオプションに関係なく適用され、CMAKE_C_FLAGS_OPTIMIZEなどを変更することで変更できます。https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.htmlを参照してください。
TEST_SUITE_FORTRAN

Fortranテストを有効にします。これは進行中の作業です。詳細については、Flangドキュメントを参照してください。
TEST_SUITE_RUN_UNDER

指定されたツールでテスト呼び出しの前に接頭辞を付けます。これは通常、シミュレータツール内でクロスコンパイルされたテストを実行するために使用されます。
TEST_SUITE_BENCHMARKING_ONLY

パフォーマンス測定に適さないテストを無効にします。無効化されたテストは、非常に短い時間で実行されるか、I/Oパフォーマンスによって支配されるため、コンパイラのパフォーマンステストとしては適していません。
TEST_SUITE_SUBDIRS

含めるディレクトリのセミコロン区切りのリスト。これを使用して、テストスイートの一部のみをビルドするか、外部スイートを含めることができます。このオプションは、中間CMakeLists.txtファイルがスキップされる可能性があり、深くネストされたサブディレクトリでは信頼性が低いため、深くネストされたサブディレクトリでは正しく動作しません。
TEST_SUITE_COLLECT_STATS

内部LLVM統計を収集します。コンパイラを呼び出すときに-save-stats=objを追加し、litランナーが統計ファイルを収集してマージするようにします。
TEST_SUITE_RUN_BENCHMARKS

これがOFFに設定されている場合、litはテストを実行しませんが、コンパイル時間やコードサイズなどのビルド統計のみを収集します。
TEST_SUITE_USE_PERF

テストスイートに付属のtimeitツールの代わりに、時間測定にperfツールを使用します。perfは通常、Linuxシステムで使用できます。
TEST_SUITE_SPEC2000_ROOT、TEST_SUITE_SPEC2006_ROOT、TEST_SUITE_SPEC2017_ROOT、…

外部ベンチマークスイートのインストールディレクトリを指定します。期待されるバージョンまたは使用方法の詳細については、Externalディレクトリ（例：External/SPEC/README）のREADMEファイルを参照してください。

一般的なCMakeフラグ¶

-GNinja

ninjaビルドツール用のビルドファイルを生成します。
-Ctest-suite/cmake/caches/<cachefile.cmake>

CMakeキャッシュを使用します。テストスイートには、一般的なまたは複雑なビルド構成を事前に定義するいくつかのCMakeキャッシュが付属しています。

結果の表示と分析¶

compare.pyスクリプトは、結果ファイルを表示および比較します。結果ファイルは、-o filename.jsonフラグを使用してlitを呼び出すと生成されます。

使用例

基本的な使用方法

% test-suite/utils/compare.py baseline.json
Warning: 'test-suite :: External/SPEC/CINT2006/403.gcc/403.gcc.test' has No metrics!
Tests: 508
Metric: exec_time

Program                                         baseline

INT2006/456.hmmer/456.hmmer                   1222.90
INT2006/464.h264ref/464.h264ref               928.70
...
             baseline
count  506.000000
mean   20.563098
std    111.423325
min    0.003400
25%    0.011200
50%    0.339450
75%    4.067200
max    1222.896800

コンパイル時間またはテキストセグメントサイズのメトリックを表示します。

% test-suite/utils/compare.py -m compile_time baseline.json
% test-suite/utils/compare.py -m size.__text baseline.json

2つの結果ファイルを比較し、実行時間の短いテストをフィルターします。

% test-suite/utils/compare.py --filter-short baseline.json experiment.json
...
Program                                         baseline  experiment  diff

SingleSour.../Benchmarks/Linpack/linpack-pc     5.16      4.30        -16.5%
MultiSourc...erolling-dbl/LoopRerolling-dbl     7.01      7.86         12.2%
SingleSour...UnitTests/Vectorizer/gcc-loops     3.89      3.54        -9.0%
...

各実行時間の最小値を取得することで、複数のベースラインと実験結果ファイルをマージします。
```
% test-suite/utils/compare.py base0.json base1.json base2.json vs exp0.json exp1.json exp2.json
```

LNTを使用した継続的なトラッキング¶

LNTは、パフォーマンスを継続的に監視するためのクライアントとサーバーのツールのセットです。https://llvm.dokyumento.jp/docs/lntで詳細情報を見つけることができます。LLVMプロジェクトの公式LNTインスタンスはhttp://lnt.llvm.orgでホストされています。

外部スイート¶

SPECなどの外部スイートは、次のいずれかの方法で有効にすることができます。

test-suite/test-suite-externals/xxxディレクトリに配置（またはリンク）する（例：test-suite/test-suite-externals/speccpu2000）
-D TEST_SUITE_SPEC2000_ROOT=path/to/speccpu2000などの構成オプションを使用する

それぞれのREADMEファイル（例：test-suite/External/SPEC/README）で詳細情報を見つけることができます。

SPECベンチマークでは、TEST_SUITE_RUN_TYPE構成オプションを使用してtest、train、ref入力データセットを切り替えることができます。trainデータセットがデフォルトで使用されます。

カスタムスイート¶

テストスイートインフラストラクチャを使用して、カスタムスイートを構築できます。カスタムスイートは、最上位ディレクトリにCMakeLists.txtファイルを持っています。CMakeLists.txtは、テストスイートのサブディレクトリに配置した場合、またはTEST_SUITE_SUBDIRS変数を設定した場合に自動的に認識されます。

% cmake -DTEST_SUITE_SUBDIRS=path/to/my/benchmark-suite ../test-suite

プロファイルガイド付き最適化¶

プロファイルガイド付き最適化では、2回コンパイルして実行する必要があります。最初に、プロファイル生成インストルメンテーションを有効にして、トレーニングデータ用に設定してベンチマークをコンパイルします。litランナーはllvm-profdataを使用してプロファイルファイルをマージするため、2回目のコンパイル実行で使用できます。

例

# Profile generation run using LLVM IR PGO:
% cmake -DTEST_SUITE_PROFILE_GENERATE=ON \
        -DTEST_SUITE_USE_IR_PGO=ON \
        -DTEST_SUITE_RUN_TYPE=train \
        ../test-suite
% make
% llvm-lit .
# Use the profile data for compilation and actual benchmark run:
% cmake -DTEST_SUITE_PROFILE_GENERATE=OFF \
        -DTEST_SUITE_PROFILE_USE=ON \
        -DTEST_SUITE_RUN_TYPE=ref \
        .
% make
% llvm-lit -o result.json .

LLVM IR PGOではなくClangフロントエンドのPGOを使用するには、-DTEST_SUITE_USE_IR_PGO=OFFを設定します。

TEST_SUITE_RUN_TYPEの設定は、SPECベンチマークスイートのみに影響します。

クロスコンパイルと外部デバイス¶

コンパイル¶

CMakeを使用すると、ツールチェーンファイルを使用して異なるターゲットにクロスコンパイルできます。詳細は、以下を参照してください。

test-suite/cmake/caches/target-target-*-iphoneos-internal.cmake CMakeキャッシュファイルを使用すると、macOSからiOSへのクロスコンパイルが可能です。これは、内部iOS SDKを必要とします。

実行¶

クロスコンパイル設定でテストを実行するには、2つの方法があります。

外部デバイスへのSSH接続経由：TEST_SUITE_REMOTE_HOSTオプションをSSHホスト名に設定する必要があります。実行ファイルとデータファイルは、コンパイル後にデバイスに転送する必要があります。これは通常、rsync makeターゲットを使用して行われます。その後、ホストマシンでlitランナーを使用できます。ベンチマークと検証のコマンドラインには、sshコマンドが接頭辞として付加されます。

例
```
% cmake -G Ninja -D CMAKE_C_COMPILER=path/to/clang \
        -C ../test-suite/cmake/caches/target-arm64-iphoneos-internal.cmake \
        -D CMAKE_BUILD_TYPE=Release \
        -D TEST_SUITE_REMOTE_HOST=mydevice \
        ../test-suite
% ninja
% ninja rsync
% llvm-lit -j1 -o result.json .
```
TEST_SUITE_RUN_UNDER設定を使用して、ターゲットマシンのシミュレータを指定できます。litランナーは、すべてのベンチマーク呼び出しにそれを接頭辞として付加します。

LNTによるテストスイートの実行¶

LNTツールを使用してテストスイートを実行できます。LNTインスタンスにテスト結果を送信する際に使用します。詳細は、https://llvm.dokyumento.jp/docs/lnt/tests.html#llvm-cmake-test-suiteを参照してください。

Makefileによるテストスイートの実行（非推奨）¶

注記：テストスイートには、非推奨とされているMakefileのセットが付属しています。これらはBitcodeやMicrobenchmarksなどの新しいテストモードをサポートしておらず、使いにくいものです。

古いドキュメントは、test-suite Makefile ガイドでご覧いただけます。

ドキュメント

参加方法

追加リンク

このページ