測試套件指南¶

快速入門¶

執行測試需要 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	遊戲/求解器	能夠有效解決四子棋遊戲位置的整數基準測試
Fhourstones-3.1	C	遊戲/求解器	“
FreeBench	C	基準測試套件	光線追蹤器、四子棋、神經網路、檔案壓縮器、快速傅立葉/餘弦/正弦變換
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 雜誌的 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、Montecarlo、稀疏矩陣乘法
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.dev.org.tw/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html
CMAKE_C_COMPILER

選取要使用的 C 編譯器可執行檔。請注意，C++ 編譯器會自動推斷，也就是說，當指定 path/to/clang 時，CMake 會自動使用 path/to/clang++ 作為 C++ 編譯器。請參閱 https://cmake.dev.org.tw/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.dev.org.tw/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

使用 perf 工具進行時間測量，而不是使用測試套件隨附的 timeit 工具。 perf 工具通常在 Linux 系統上可用。
TEST_SUITE_SPEC2000_ROOT、TEST_SUITE_SPEC2006_ROOT、TEST_SUITE_SPEC2017_ROOT…

指定外部基準測試套件的安裝目錄。您可以在 External 目錄中的 README 檔案（例如 External/SPEC/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

顯示 compile_time 或文字區段大小指標

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

比較兩個結果檔案並篩選執行時間較短的測試

% 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.dev.org.tw/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

設定檔導引最佳化¶

設定檔導引最佳化需要編譯和執行兩次。首先，應該在啟用設定檔產生工具的情況下編譯基準測試，並設定訓練資料。lit 執行器會使用 llvm-profdata 合併設定檔檔案，以便第二次編譯執行時可以使用它們。

範例

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

若要使用 Clang 前端的 PGO 而不是 LLVM IR 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。

執行¶

有兩種方法可以在交叉編譯設定中執行測試

透過 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.dev.org.tw/docs/lnt/tests.html#llvm-cmake-test-suite。

透過 Makefile 執行測試套件（已棄用）¶

**注意**：測試套件附帶一組被視為已棄用的 Makefile。它們不支援較新的測試模式，例如 Bitcode 或 Microbenchmarks，而且更難使用。

舊版文件可在測試套件 Makefile 指南中找到。

文件

參與

其他連結

本頁