Revamp test-suite documentation

[MatzeB]

Summary

• Remove duplication: Both TestingGuide and TestSuiteMakefileGuide would give a similar overview over the test-suite.
• Present cmake/lit as the default/normal way of running the test-suite:
• Move information about the cmake/lit testsuite into the new TestSuiteGuide.rst file. Mark the remaining information in TestSuiteMakefilesGuide.rst as deprecated.
• General simplification and shorting of language.
• Remove paragraphs about tests known to fail as everything should pass nowadays.
• Remove paragraph about zlib requirement; it's not required anymore since we copied a zlib source snapshot into the test-suite.
• Remove paragraph about comparison with "native compiler". Correctness is always checked against reference outputs nowadays.
• Change cmake/lit quickstart section to recommend pip for installing lit and use CMAKE_C_COMPILER and a cache file in the example as that is what most people will end up doing anyway. Also a section about compare.py to quickstart.
• Document Bitcode and MicroBenchmarks directories.
• Add section about commonly used cmake configuration options.
• Add section about showing and comparing result files via compare.py.
• Add section about using external benchmark suites.
• Add section about using custom benchmark suites.
• Add section about profile guided optimization.
• Add section about cross-compilation and running on external devices.

[rengolin]

AWESOME!

Very detailed, using the modern infrastructure and helpful even to those not using clang or wanting to run external benchmarks.

I haven't reviewed the whole text (non-English speaker), nor I ran the commands to validate the setup (I'm assuming you did, extensively!:), but this looks right on the money. Thank you!

Feel free to ping me again if no one takes any interest in this, but for the record, overall, LGTM.

Thanks,
--renato

docs/CMake.rst

613

Do we want at least a hint here that there are more tests? A link to the new page with a short paragraph would do.

[thegameg]

Thanks a lot Matthias, this looks really great! I hopefully did not miss anything, it LGTM!

docs/TestSuiteGuide.rst

113 ↗

(On Diff #163218)

We could have a link to External Suites somewhere here.

[kristof.beyls]

I am as excited by this as the other reviewers.
Thank you very much for this, Matthias!

I only have a few nitpicks, see comments inline. Feel free to ignore my nitpicks - they're mostly personal opinion on my side, not essential.

Thanks!

Kristof

docs/TestSuiteGuide.rst

19–20 ↗

(On Diff #163218)

I tend to prefer documentation that shows how to set up a virtualenv, so that copy pasting commands from the documentation doesn't change your system set up by default.
However, in this case, I can also see the argument to not do that and keep documentation more concise.

I'm happy either way - just thought I'd share my thought.

33 ↗

(On Diff #163218)

s/Use/use/

134 ↗

(On Diff #163218)

s/option/cmake option/ ?

288 ↗

(On Diff #163218)

Maybe a pointer to LNT might be worthwhile here as a system that knows how to drive running the test-suite, collecting results, storing in a database, and analyzing it further?

402–407 ↗

(On Diff #163218)

I wonder if it wouldn't be better to have this note at the start.
I started thinking that when seeing that in docs/SourceLevelDebugging.rst in this patch, you changed a pointer to this guide, which explains the cmake/lit system, and then on the next line in docs/SourceLevelDebugging.rst, there is a command line with make, using the deprecated system.
Maybe it'll be less frustrating for people coming through that link to be notified immediately that there is an old, deprecated system based on make?

[Meinersbur]

Thanks for investing time into the documentation

docs/TestSuiteGuide.rst

55 ↗

(On Diff #163218)

There will be no more TEST_SUITE_HOST_CC after D51080.

224 ↗

(On Diff #163218)

The file cachefile.cmake does not exist. Maybe use an existing example such as Release.cmake or use a wildcard/placeholder such as <cachefile>.cmake?

309–316 ↗

(On Diff #163218)

Maybe it is worth pointing out that one cannot point into arbitrary subdirs of SingleSource/MultSource/MicroBenchmarks/Bitcode since these have custom lit.local.cfg on their level.

(CTMark unfortunately skips MultiSource/lit.local.cfg)

344 ↗

(On Diff #163218)

... SPEC benchmark suites

[tra]

Looks great. Thank you for updating the docs.

docs/TestSuiteGuide.rst

19–20 ↗

(On Diff #163218)

Is installing lit directly from llvm a hard requirement?
I've been using pip install lit and that appears to work.

[paquette]

Added some style nits.

They're mostly personal though, so LGTM.

docs/CMake.rst

612–613

Capitalization:

Executing the Tests

docs/SourceLevelDebugging.rst

118–120

We should make it clear that when we say "test-suite" later in the docs, we're talking about this.

:doc:LLVM test suite <TestSuiteMakefileGuide> (test-suite)

Also we should choose one of "test-suite" and "test suite" and stick to it throughout the document.

119

"to test the optimizer's handling"

Also maybe active voice would be better here? "The LLVM test suite provides a framework for testing how the optimizer handles debugging information."

docs/TestSuiteGuide.rst

12 ↗

(On Diff #163218)

This is kind of awkward given that the list below is partially a list of necessary things, and partially a list of instructions. Might be good to revise the items in a way that makes it sound like a list of necessary things.

e.g

#. The lit test runner.

... (stuff)

#. The test suite module.

... (stuff)

#. A build directory, configured with CMake.

... (stuff)

etc.

45 ↗

(On Diff #163218)

I think this shouldn't be in the same list as above, because now you're not describing what you need, but rather how to run the test suite.

It can probably be broken up with something like "After this, you can build and execute the test suite as follows..."

90–91 ↗

(On Diff #163218)

"a number" isn't necessary.

The `test-suite` module contains programs that can be compiled and executed.

92 ↗

(On Diff #163218)

Avoid starting sentences with "and" if possible.

This can also be simplified:
"The suite comes with tools to collect metrics such as benchmark runtime, compilation time, and code size."

100 ↗

(On Diff #163218)

"such" isn't necessary

117–118 ↗

(On Diff #163218)

Which other means?

132 ↗

(On Diff #163218)

some of the programs -> some programs

140 ↗

(On Diff #163218)

We should be consistent when using "suite" to refer to the test suite and "test-suite". There are a few places where you use "suite", and a few where you use "test-suite". I think that just using "test-suite" everywhere would be more consistent.

157–158 ↗

(On Diff #163218)

Second sentence can be simplified.

"These flags are also passed to C++ compiler and linker invocations."

189 ↗

(On Diff #163218)

Semicolon separated -> Semicolon-separated

191 ↗

(On Diff #163218)

Can be simplified:

"Using this option does not work reliably with deeper subdirectories..."

(This could probably be split into two sentences, but meh.)

197 ↗

(On Diff #163218)

Colon should be a period.

209 ↗

(On Diff #163218)

coming with -> that comes with

226 ↗

(On Diff #163218)

After a colon (or semicolon), you don't have to capitalize the first word.

e.g

The test-suite comes with several cache files: they...

227 ↗

(On Diff #163218)

This can be simplified:

"Use a CMake cache. The test-suite comes with several CMake caches which predefine common or tricky build configurations."

234 ↗

(On Diff #163218)

"little" is unnecessary

235 ↗

(On Diff #163218)

"You should" is unnecessary.

"Invoke `lit`..."

293 ↗

(On Diff #163218)

remove semicolon; they should only be used before a list when you have a full sentence

298 ↗

(On Diff #163218)

Versions of what?

309–310 ↗

(On Diff #163218)

Can be simplified:

Custom tests must contain a `CMakeLists.txt file at the top directory. The CMakeLists.txt` file will be automatically picked up...

322 ↗

(On Diff #163218)

colon -> no capitalization.

Should probably be a proper sentence anyway (with a period). This gives better separation of the two-item list.

Right now the structure is like

[statement of list + item 1][item 2]

While if we split it up, it'd be more

[statement of list][item 1][item 2]

326 ↗

(On Diff #163218)

run: Example -> run. Example:

Also "Example:" probably deserves its own paragraph.

(I'd normally say remove the semicolon too, since it's not a sentence. Idiomatically speaking though, people write "Example:" all the time.)

344 ↗

(On Diff #163218)

Should this be

.. NOTE::

like on line 402?

360 ↗

(On Diff #163218)

Should be consistent in hyphenation of cross-compilation. Above, this, there's no hyphen twice.

362 ↗

(On Diff #163218)

don't need to capitalize "however"

367 ↗

(On Diff #163218)

Don't need "currently".

369 ↗

(On Diff #163218)

Capitalize SSH.

Can be simplified:

"Via SSH connection to an external device."

370 ↗

(On Diff #163218)

ssh->SSH

host name -> hostname

372–374 ↗

(On Diff #163218)

I think that this can be split up.

"After this, the lit runner can be used on the host machine. The lit runner will prefix benchmark and verification command lines with a `ssh` command."

Also I think "Example:" deserves its own paragraph.

391 ↗

(On Diff #163218)

Hmmmm, capitalization, if we're not committed to "test-suite":
Running the Test Suite via LNT

Otherwise:
Running the test-suite via LNT

394–395 ↗

(On Diff #163218)

simplification:

"The LNT tool can run the test-suite. Use this when submitting results to a LNT database."

399 ↗

(On Diff #163218)

Same as the other capitalization confusion. If it's "test-suite", then it's fine since that's the name...

407 ↗

(On Diff #163218)

Simplification:
Old documentation is available in the :doc:TestSuiteMakefileGuide.

docs/TestSuiteMakefileGuide.rst

91–92

Running Different Tests

111–112

Generating Test Output

137–138

Writing Custom Tests for the Test Suite

or

Writing Custom Tests for the test-suite

docs/TestingGuide.rst

29

LLVM Testing Infrastructure Organization

98–100

Simplification:
The `test-suite` module contains a more comprehensive test suite including whole C and C++ programs.

[MatzeB]

Thanks for the detailed review comments!

• Convert document to markdown (I assume that is the recommended way to do things after rL338977).
• Addressed review feedback.

docs/CMake.rst

613

There is already a link to the TestingGuide two paragraphs below which explains the differences between the unit tests, lit tests and the test-suite.

(Also I my original intention with this patch was not to change any of the other documentation files; but this heading felt so misleading because the whole section was about the lit tests and not the test-suite...)

docs/SourceLevelDebugging.rst

119

I changed it, though again I would like to keep changes in unrelated parts of the documentation minimal. This one just needed to be changed to reference the makefile guide, as the modern cmake/lit suite has no equivalent for this testing mode yet...

docs/TestSuiteGuide.rst

12 ↗

(On Diff #163218)

I just went ahead and dropped the whole sentence :)
So now you can just read it as a step by step instruction list (instead of a mix of requirements and steps).

19–20 ↗

(On Diff #163218)

Oh, I thought we stopped distributing lit to pypi out of concerns that without update processes in place it would get out of date. Indeed pip install lit still works today, but I think I'm not gonna suggest it :)

19–20 ↗

(On Diff #163218)

Thinking about this again, I would expect most people just use llvm-lit from their llvm build directory. I thus present that as the first possibility now and changed the name to llvm-lit in all the examples.

I present a virtualenv based setup as an alternative now.

45 ↗

(On Diff #163218)

As above, I hope it makes now sense as a step by step introduction.

55 ↗

(On Diff #163218)

See my comment there.

90–91 ↗

(On Diff #163218)

I took the recommendation and also dropped "module".

113 ↗

(On Diff #163218)

added.

117–118 ↗

(On Diff #163218)

Dropped the sentence since we have a link to whole section now which explains things.

140 ↗

(On Diff #163218)

I changed most of them to test-suite now.

157–158 ↗

(On Diff #163218)

Yeah I added the awkward "currently the test-suite" because I always considered this behavior strange/odd and because it is specific to the test-suite and does not happen in any cmake project...

But indeed this is not the place to leak these opinions and it's unlikely that we actually change it given that it would be quite a churn on users... Will go for the simpler sentence.

288 ↗

(On Diff #163218)

I added a section about LNT immediately below this.

309–316 ↗

(On Diff #163218)

I mentioned this when describing the TEST_SUITE_SUBDIRS option. I'm not sure I want to repeat it here as this section is about using custom suites not subdirectories of the test-suite.

(And I would consider CTMark lacking its own lit.local.cfg a bug. I guess we only ever used it as compile time benchmark and never tried running it. Will fix this soon.)

344 ↗

(On Diff #163218)

I don't think this particular one needs the emphasis of a whole block. I removed the "Note:" now.

362 ↗

(On Diff #163218)

used lowercase and dropped "however".

402–407 ↗

(On Diff #163218)

• I changed the SourceLevelDebugging.rst thing to point to the deprecated makefile guide not this new one. I don't think we have an equivalent to this specialized use case in the cmake/lit version yet.
• I'd like to keep the section at the bottom as I'd prefer people to stumble upon this and know about it unless they really have to :)

[homerdin]

Thanks for working on this! LGTM

docs/TestSuiteGuide.md

34

Do we want to mention that the test-suite should be able to build with other compilers?

[MatzeB]

• Address remaining review feedback, shorten some terminal dumps.
• I will commit this after landing D51080 (the remote section here describes the situation after that patch)

docs/TestSuiteGuide.md

34

Do you know whether the test-suite actually works with non-clang compilers? I can imagine it mostly works, but I also wouldn't be surprised if some clang specific flag or extension is used in few of the benchmarks...

I changed the wording to "custom compiler" but will not explicitely call out support for non-clang compilers for now.

[homerdin]

docs/TestSuiteGuide.md

34

As you suspect it mostly works but gets some errors. Also after fixing the errors you still get some misleading performance results. Some tests use clang specific pragmas and one test just prints the reference output if you are not using clang.

The language led me to believe the test-suite is only for clang. I had the impression the test-suite was not meant to be specific to clang (though its buggy on other compilers).

I'm good with the wording as is and agree with not explicitly calling out support for non-clang compilers.

[MatzeB]

docs/TestSuiteGuide.md

34

I'd accept patches to the test-suite that disable clang specific benchmarks if someone cares enough to make them :)

(Should be possible to do in a similar way like TEST_SUITE_BENCHMARKING_ONLY disables programs unsuitable for performance testing)

docs/CMake.rst

 - All -D arguments will override cache file settings
 - CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command
   line arguments
 - It is recommended that all -D options should be specified *before* -C
 
 For more information about some of the advanced build configurations supported
 via Cache files see :doc:`AdvancedBuilds`.
 
-Executing the test suite
-========================
+Executing the Tests
+===================
 
 Testing is performed when the *check-all* target is built. For instance, if you are
 using Makefiles, execute this command in the root of your build directory:
 
 .. code-block:: console
 
   $ make check-all
 

docs/SourceLevelDebugging.rst

 "``-O0 -g``" and get full debug information, allowing you to arbitrarily modify
 the program as it executes from a debugger.  Compiling a program with
 "``-O3 -g``" gives you full debug information that is always available and
 accurate for reading (e.g., you get accurate stack traces despite tail call
 elimination and inlining), but you might lose the ability to modify the program
 and call functions which were optimized out of the program, or inlined away
 completely.
 
-The :ref:`LLVM test suite <test-suite-quickstart>` provides a framework to test
-optimizer's handling of debugging information.  It can be run like this:
+The :doc:`LLVM test-suite <TestSuiteMakefileGuide>` provides a framework to
+test the optimizer's handling of debugging information.  It can be run like
+this:
 
 .. code-block:: bash
 
   % cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level
   % make TEST=dbgopt
 
 This will test impact of debugging information on optimization passes.  If
 debugging information influences optimization passes then it will be reported

docs/TestSuiteGuide.md

+test-suite Guide
+================
+
+Quickstart
+----------
+
+1. The lit test runner is required to run the tests. You can either use one
+   from an LLVM build:
+
+   ```bash
+   % <path to llvm build>/bin/llvm-lit --version
+   lit 0.8.0dev
+   ```
+
+   An alternative is installing it as a python package in a python virtual
+   environment:
+
+   ```bash
+   % mkdir venv
+   % virtualenv -p python2.7 venv
+   % . venv/bin/activate
+   % pip install svn+http://llvm.org/svn/llvm-project/llvm/trunk/utils/lit
+   % lit --version
+   lit 0.8.0dev
+   ```
+
+2. Check out the `test-suite` module with:
+
+   ```bash
+   % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
+   ```
+
+3. Create a build directory and use CMake to configure the suite. The
+   `CMAKE_C_COMPILER` option can be used to test a custom clang build.
+   The cache file provides a typical build configuration:
+
+   ```bash
+   % 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
+   ```
+
+4. Build the benchmarks:
+
+   ```text
+   % 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
+   [  0%] Built target timeit-target
+   Scanning dependencies of target fpcmp-host
+   [  0%] [TEST_SUITE_HOST_CC] Building host executable fpcmp
+   [  0%] Built target fpcmp-host
+   Scanning dependencies of target timeit-host
+   [  0%] [TEST_SUITE_HOST_CC] Building host executable timeit
+   [  0%] Built target timeit-host
+   ```
+
+5. Run the tests with lit:
+
+   ```text
+   % 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)
+   ```
+
+6. Show and compare result files (optional):
+
+   ```bash
+   % sudo pip install pandas
+   # 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
+   ```
+
+
+Structure
+---------
+
+The test-suite contains benchmark and test programs.  The programs come with
+reference outputs so that their correctness can be checked.  The suite comes
+with tools to collect metrics such as benchmark runtime, compilation time and
+code size.
+
+The test-suite is divided into several directories:
+
+-  `SingleSource/`
+
+   Contains test programs that are only a single source file in size.  A
+   subdirectory may contain several programs.
+
+-  `MultiSource/`
+
+   Contains subdirectories which entire programs with multiple source files.
+   Large benchmarks and whole applications go here.
+
+-  `MicroBenchmarks/`
+
+   Programs using the [google-benchmark](https://github.com/google/benchmark)
+   library. The programs define functions that are run multiple times until the
+   measurement results are statistically significant.
+
+-  `External/`
+
+   Contains descriptions and test data for code that cannot be directly
+   distributed with the test-suite. The most prominent members of this
+   directory are the SPEC CPU benchmark suites.
+   See [External Suites](#external-suites).
+
+-  `Bitcode/`
+
+   These tests are mostly written in LLVM bitcode.
+
+-  `CTMark/`
+
+   Contains symbolic links to other benchmarks forming a representative sample
+   for compilation performance measurements.
+
+### Benchmarks
+
+Every program can work as a correctness test. Some programs are unsuitable for
+performance measurements. Setting the `TEST_SUITE_BENCHMARKING_ONLY` CMake
+option to `ON` will disable them.
+
+
+Configuration
+-------------
+
+The test-suite has configuration options to customize building and running the
+benchmarks. CMake can print a list of them:
+
+```bash
+% cd test-suite-build
+# Print basic options:
+% cmake -LH
+# Print all options:
+% cmake -LAH
+```
+
+### Common Configuration Options
+
+- `CMAKE_C_FLAGS`
+
+  Specify extra flags to be passed to C compiler invocations.  The flags are
+  also passed to the C++ compiler and linker invocations.  See
+  [https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html)
+
+- `CMAKE_C_COMPILER`
+
+  Select the C compiler executable to be used. Note that the C++ compiler is
+  inferred automatically i.e. when specifying `path/to/clang` CMake will
+  automatically use `path/to/clang++` as the C++ compiler.  See
+  [https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html)
+
+- `CMAKE_BUILD_TYPE`
+
+  Select a build type like `OPTIMIZE` or `DEBUG` selecting a set of predefined
+  compiler flags. These flags are applied regardless of the `CMAKE_C_FLAGS`
+  option and may be changed by modifying `CMAKE_C_FLAGS_OPTIMIZE` etc.  See
+  [https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html]](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html)
+
+- `TEST_SUITE_RUN_UNDER`
+
+  Prefix test invocations with the given tool. This is typically used to run
+  cross-compiled tests within a simulator tool.
+
+- `TEST_SUITE_BENCHMARKING_ONLY`
+
+  Disable tests that are unsuitable for performance measurements. The disabled
+  tests either run for a very short time or are dominated by I/O performance
+  making them unsuitable as compiler performance tests.
+
+- `TEST_SUITE_SUBDIRS`
+
+  Semicolon-separated list of directories to include. This can be used to only
+  build parts of the test-suite or to include external suites.  This option
+  does not work reliably with deeper subdirectories as it skips intermediate
+  `CMakeLists.txt` files which may be required.
+
+- `TEST_SUITE_COLLECT_STATS`
+
+  Collect internal LLVM statistics. Appends `-save-stats=obj` when invocing the
+  compiler and makes the lit runner collect and merge the statistic files.
+
+- `TEST_SUITE_RUN_BENCHMARKS`
+
+  If this is set to `OFF` then lit will not actually run the tests but just
+  collect build statistics like compile time and code size.
+
+- `TEST_SUITE_USE_PERF`
+
+  Use the `perf` tool for time measurement instead of the `timeit` tool that
+  comes with the test-suite.  The `perf` is usually available on linux systems.
+
+- `TEST_SUITE_SPEC2000_ROOT`, `TEST_SUITE_SPEC2006_ROOT`, `TEST_SUITE_SPEC2017_ROOT`, ...
+
+  Specify installation directories of external benchmark suites. You can find
+  more information about expected versions or usage in the README files in the
+  `External` directory (such as `External/SPEC/README`)
+
+### Common CMake Flags
+
+- `-GNinja`
+
+  Generate build files for the ninja build tool.
+
+- `-Ctest-suite/cmake/caches/<cachefile.cmake>`
+
+  Use a CMake cache.  The test-suite comes with several CMake caches which
+  predefine common or tricky build configurations.
+
+
+Displaying and Analyzing Results
+--------------------------------
+
+The `compare.py` script displays and compares result files.  A result file is
+produced when invoking lit with the `-o filename.json` flag.
+
+Example usage:
+
+- Basic Usage:
+
+  ```text
+  % 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
+  ```
+
+- Show compile_time or text segment size metrics:
+
+  ```bash
+  % test-suite/utils/compare.py -m compile_time baseline.json
+  % test-suite/utils/compare.py -m size.__text baseline.json
+  ```
+
+- Compare two result files and filter short running tests:
+
+  ```bash
+  % 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%
+  ...
+  ```
+
+- Merge multiple baseline and experiment result files by taking the minimum
+  runtime each:
+
+  ```bash
+  % test-suite/utils/compare.py base0.json base1.json base2.json vs exp0.json exp1.json exp2.json
+  ```
+
+### Continuous Tracking with LNT
+
+LNT is a set of client and server tools for continuously monitoring
+performance. You can find more information at
+[http://llvm.org/docs/lnt](http://llvm.org/docs/lnt). The official LNT instance
+of the LLVM project is hosted at [http://lnt.llvm.org](http://lnt.llvm.org).
+
+
+External Suites
+---------------
+
+External suites such as SPEC can be enabled by either
+
+- placing (or linking) them into the `test-suite/test-suite-externals/xxx` directory (example: `test-suite/test-suite-externals/speccpu2000`)
+- using a configuration option such as `-D TEST_SUITE_SPEC2000_ROOT=path/to/speccpu2000`
+
+You can find further information in the respective README files such as
+`test-suite/External/SPEC/README`.
+
+For the SPEC benchmarks you can switch between the `test`, `train` and
+`ref` input datasets via the `TEST_SUITE_RUN_TYPE` configuration option.
+The `train` dataset is used by default.
+
+
+Custom Suites
+-------------
+
+You can build custom suites using the test-suite infrastructure. A custom suite
+has a `CMakeLists.txt` file at the top directory. The `CMakeLists.txt` will be
+picked up automatically if placed into a subdirectory of the test-suite or when
+setting the `TEST_SUITE_SUBDIRS` variable:
+
+```bash
+% cmake -DTEST_SUITE_SUBDIRS=path/to/my/benchmark-suite ../test-suite
+```
+
+
+Profile Guided Optimization
+---------------------------
+
+Profile guided optimization requires to compile and run twice. First the
+benchmark should be compiled with profile generation instrumentation enabled
+and setup for training data. The lit runner will merge the profile files
+using `llvm-profdata` so they can be used by the second compilation run.
+
+Example:
+```bash
+# Profile generation run:
+% cmake -DTEST_SUITE_PROFILE_GENERATE=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 .
+```
+
+The `TEST_SUITE_RUN_TYPE` setting only affects the SPEC benchmark suites.
+
+
+Cross Compilation and External Devices
+--------------------------------------
+
+### Compilation
+
+CMake allows to cross compile to a different target via toolchain files. More
+information can be found here:
+
+- [http://llvm.org/docs/lnt/tests.html#cross-compiling](http://llvm.org/docs/lnt/tests.html#cross-compiling)
+
+- [https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html)
+
+Cross compilation from macOS to iOS is possible with the
+`test-suite/cmake/caches/target-target-*-iphoneos-internal.cmake` CMake cache
+files; this requires an internal iOS SDK.
+
+### Running
+
+There are two ways to run the tests in a cross compilation setting:
+
+- Via SSH connection to an external device: The `TEST_SUITE_REMOTE_HOST` option
+  should be set to the SSH hostname.  The executables and data files need to be
+  transferred to the device after compilation.  This is typically done via the
+  `rsync` make target.  After this, the lit runner can be used on the host
+  machine. It will prefix the benchmark and verification command lines with an
+  `ssh` command.
+
+  Example:
+
+  ```bash
+  % cmake -G Ninja -D CMAKE_C_COMPILER=path/to/clang \
+          -C ../test-suite/cmake/caches/target-arm64-iphoneos-internal.cmake \
+          -D TEST_SUITE_REMOTE_HOST=mydevice \
+          ../test-suite
+  % ninja
+  % ninja rsync
+  % llvm-lit -j1 -o result.json .
+  ```
+
+- You can specify a simulator for the target machine with the
+  `TEST_SUITE_RUN_UNDER` setting. The lit runner will prefix all benchmark
+  invocations with it.
+
+
+Running the test-suite via LNT
+------------------------------
+
+The LNT tool can run the test-suite. Use this when submitting test results to
+an LNT instance.  See
+[http://llvm.org/docs/lnt/tests.html#llvm-cmake-test-suite](http://llvm.org/docs/lnt/tests.html#llvm-cmake-test-suite)
+for details.
+
+Running the test-suite via Makefiles (deprecated)
+-------------------------------------------------
+
+**Note**: The test-suite comes with a set of Makefiles that are considered
+deprecated.  They do not support newer testing modes like `Bitcode` or
+`Microbenchmarks` and are harder to use.
+
+Old documentation is available in the
+[test-suite Makefile Guide](TestSuiteMakefileGuide).

docs/TestSuiteMakefileGuide.rst

-=====================
-LLVM test-suite Guide
-=====================
+======================================
+test-suite Makefile Guide (deprecated)
+======================================
 
 .. contents::
     :local:
 
 Overview
 ========
 
-This document describes the features of the Makefile-based LLVM
-test-suite as well as the cmake based replacement. This way of interacting
-with the test-suite is deprecated in favor of running the test-suite using LNT,
-but may continue to prove useful for some users. See the Testing
-Guide's :ref:`test-suite Quickstart <test-suite-quickstart>` section for more
-information.
-
-Test suite Structure
-====================
-
-The ``test-suite`` module contains a number of programs that can be
-compiled with LLVM and executed. These programs are compiled using the
-native compiler and various LLVM backends. The output from the program
-compiled with the native compiler is assumed correct; the results from
-the other programs are compared to the native program output and pass if
-they match.
-
-When executing tests, it is usually a good idea to start out with a
-subset of the available tests or programs. This makes test run times
-smaller at first and later on this is useful to investigate individual
-test failures. To run some test only on a subset of programs, simply
-change directory to the programs you want tested and run ``gmake``
-there. Alternatively, you can run a different test using the ``TEST``
-variable to change what tests or run on the selected programs (see below
-for more info).
-
-In addition for testing correctness, the ``test-suite`` directory also
-performs timing tests of various LLVM optimizations. It also records
-compilation times for the compilers and the JIT. This information can be
-used to compare the effectiveness of LLVM's optimizations and code
-generation.
-
-``test-suite`` tests are divided into three types of tests: MultiSource,
-SingleSource, and External.
-
--  ``test-suite/SingleSource``
-
-   The SingleSource directory contains test programs that are only a
-   single source file in size. These are usually small benchmark
-   programs or small programs that calculate a particular value. Several
-   such programs are grouped together in each directory.
-
--  ``test-suite/MultiSource``
-
-   The MultiSource directory contains subdirectories which contain
-   entire programs with multiple source files. Large benchmarks and
-   whole applications go here.
-
--  ``test-suite/External``
-
-   The External directory contains Makefiles for building code that is
-   external to (i.e., not distributed with) LLVM. The most prominent
-   members of this directory are the SPEC 95 and SPEC 2000 benchmark
-   suites. The ``External`` directory does not contain these actual
-   tests, but only the Makefiles that know how to properly compile these
-   programs from somewhere else. The presence and location of these
-   external programs is configured by the test-suite ``configure``
-   script.
-
-Each tree is then subdivided into several categories, including
-applications, benchmarks, regression tests, code that is strange
-grammatically, etc. These organizations should be relatively self
-explanatory.
-
-Some tests are known to fail. Some are bugs that we have not fixed yet;
-others are features that we haven't added yet (or may never add). In the
-regression tests, the result for such tests will be XFAIL (eXpected
-FAILure). In this way, you can tell the difference between an expected
-and unexpected failure.
-
-The tests in the test suite have no such feature at this time. If the
-test passes, only warnings and other miscellaneous output will be
-generated. If a test fails, a large <program> FAILED message will be
-displayed. This will help you separate benign warnings from actual test
-failures.
-
-Running the test suite via CMake
-================================
-
-To run the test suite, you need to use the following steps:
-
-#. The test suite uses the lit test runner to run the test-suite,
-   you need to have lit installed first.  Check out LLVM and install lit:
-   
-   .. code-block:: bash
-
-       % svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
-       % cd llvm/utils/lit
-       % sudo python setup.py install # Or without sudo, install in virtual-env.
-       running install
-       running bdist_egg
-       running egg_info
-       writing lit.egg-info/PKG-INFO
-       ...
-       % lit --version
-       lit 0.5.0dev
-
-#. Check out the ``test-suite`` module with:
-
-   .. code-block:: bash
-
-       % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
-
-#. Use CMake to configure the test suite in a new directory. You cannot build
-   the test suite in the source tree.
-
-   .. code-block:: bash
-   
-       % mkdir test-suite-build
-       % cd test-suite-build
-       % cmake ../test-suite
-
-#. Build the benchmarks, using the makefiles CMake generated.
-
-.. code-block:: bash
-
-    % 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
-    [  0%] Built target timeit-target
-    Scanning dependencies of target fpcmp-host
-    [  0%] [TEST_SUITE_HOST_CC] Building host executable fpcmp
-    [  0%] Built target fpcmp-host
-    Scanning dependencies of target timeit-host
-    [  0%] [TEST_SUITE_HOST_CC] Building host executable timeit
-    [  0%] Built target timeit-host
-
-    
-#. Run the tests with lit:
-
-.. code-block:: bash
-
-    % 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)
-
-
-Running the test suite via Makefiles (deprecated)
-=================================================
-
 First, all tests are executed within the LLVM object directory tree.
 They *are not* executed inside of the LLVM source tree. This is because
 the test suite creates temporary files during execution.
 
 To run the test suite, you need to use the following steps:
 
 #. ``cd`` into the ``llvm/projects`` directory in your source tree.
 #. Check out the ``test-suite`` module with:
.. code-block:: bash
        % cd $LLVM_OBJ_ROOT/projects/test-suite
        % make
 
 Note that the second and third steps only need to be done once. After
 you have the suite checked out and configured, you don't need to do it
 again (unless the test code or configure script changes).
 
 Configuring External Tests
---------------------------
+==========================
 
 In order to run the External tests in the ``test-suite`` module, you
 must specify *--with-externals*. This must be done during the
 *re-configuration* step (see above), and the ``llvm`` re-configuration
 must recognize the previously-built ``llvm-gcc``. If any of these is
 missing or neglected, the External tests won't work.
 
 * *--with-externals*

 * speccpu2000
 
 * speccpu2006
 
 * povray31
 
 Others are added from time to time, and can be determined from
 ``configure``.
 
-Running different tests
------------------------
+Running Different Tests
+=======================
 
 In addition to the regular "whole program" tests, the ``test-suite``
 module also provides a mechanism for compiling the programs in different
 ways. If the variable TEST is defined on the ``gmake`` command line, the
 test system will include a Makefile named
 ``TEST.<value of TEST variable>.Makefile``. This Makefile can modify
 build rules to yield different results.
 
 For example, the LLVM nightly tester uses ``TEST.nightly.Makefile`` to
 create the nightly test reports. To run the nightly tests, run
 ``gmake TEST=nightly``.
 
 There are several TEST Makefiles available in the tree. Some of them are
 designed for internal LLVM research and will not work outside of the
 LLVM research group. They may still be valuable, however, as a guide to
 writing your own TEST Makefile for any optimization or analysis passes
 that you develop with LLVM.
 
-Generating test output
-----------------------
+Generating Test Output
+======================
 
 There are a number of ways to run the tests and generate output. The
 most simple one is simply running ``gmake`` with no arguments. This will
 compile and run all programs in the tree using a number of different
 methods and compare results. Any failures are reported in the output,
 but are likely drowned in the other output. Passes are not reported
 explicitly.
 
 Somewhat better is running ``gmake TEST=sometest test``, which runs the
 specified test and usually adds per-program summaries to the output
 (depending on which sometest you use). For example, the ``nightly`` test
 explicitly outputs TEST-PASS or TEST-FAIL for every test after each
 program. Though these lines are still drowned in the output, it's easy
 to grep the output logs in the Output directories.
 
 Even better are the ``report`` and ``report.format`` targets (where
 ``format`` is one of ``html``, ``csv``, ``text`` or ``graphs``). The
 exact contents of the report are dependent on which ``TEST`` you are
 running, but the text results are always shown at the end of the run and
 the results are always stored in the ``report.<type>.format`` file (when
 running with ``TEST=<type>``). The ``report`` also generate a file
 called ``report.<type>.raw.out`` containing the output of the entire
 test run.
 
-Writing custom tests for the test suite
----------------------------------------
+Writing Custom Tests for the test-suite
+=======================================
 
 Assuming you can run the test suite, (e.g.
 "``gmake TEST=nightly report``" should work), it is really easy to run
 optimizations or code generator components against every program in the
 tree, collecting statistics or running custom checks for correctness. At
 base, this is how the nightly tester works, it's just one example of a
 general framework.
 

docs/TestingGuide.rst

 =================================
 LLVM Testing Infrastructure Guide
 =================================
 
 .. contents::
    :local:
 
 .. toctree::
    :hidden:
 
+   TestSuiteGuide
    TestSuiteMakefileGuide
 
 Overview
 ========
 
 This document is the reference manual for the LLVM testing
 infrastructure. It documents the structure of the LLVM testing
 infrastructure, the tools needed to use it, and how to add and run
 tests.
 
 Requirements
 ============
 
 In order to use the LLVM testing infrastructure, you will need all of the
 software required to build LLVM, as well as `Python <http://python.org>`_ 2.7 or
 later.
 
-If you intend to run the :ref:`test-suite <test-suite-overview>`, you will also
-need a development version of zlib (zlib1g-dev is known to work on several Linux
-distributions).
-
-LLVM testing infrastructure organization
+LLVM Testing Infrastructure Organization
 ========================================
 
 The LLVM testing infrastructure contains two major categories of tests:
 regression tests and whole programs. The regression tests are contained
 inside the LLVM repository itself under ``llvm/test`` and are expected
 to always pass -- they should be run before every commit.
 
 The whole programs tests are referred to as the "LLVM test suite" (or

 
 In addition to compiling and executing programs, whole program tests
 serve as a way of benchmarking LLVM performance, both in terms of the
 efficiency of the programs generated as well as the speed with which
 LLVM compiles, optimizes, and generates code.
 
 The test-suite is located in the ``test-suite`` Subversion module.
 
+See the :doc:`TestSuiteGuide` for details.
+
 Debugging Information tests
 ---------------------------
 
 The test suite contains tests to check quality of debugging information.
 The test are written in C based languages or in LLVM assembly language.
 
 These tests are compiled and run under a debugger. The debugger output
 is checked to validate of debugging information. See README.txt in the
 test suite for more information . This test suite is located in the
 ``debuginfo-tests`` Subversion module.
 
 Quick start
 ===========
 
 The tests are located in two separate Subversion modules. The
 regressions tests are in the main "llvm" module under the directory
 ``llvm/test`` (so you get these tests for free with the main LLVM tree).
 Use ``make check-all`` to run the regression tests after building LLVM.
 
-The more comprehensive test suite that includes whole programs in C and C++
-is in the ``test-suite`` module. See :ref:`test-suite Quickstart
-<test-suite-quickstart>` for more information on running these tests.
+The ``test-suite`` module contains more comprehensive tests including whole C
+and C++ programs. See the :doc:`TestSuiteGuide` for details.
 
 Regression tests
 ----------------
 
 To run all of the LLVM regression tests use the check-llvm target:
 
 .. code-block:: bash
 
     % make check-llvm

 interpretation of lines to terminate. This is generally done right after
 the last RUN: line. This has two side effects:
 
 (a) it prevents special interpretation of lines that are part of the test
     program, not the instructions to the test case, and
 
 (b) it speeds things up for really big test cases by avoiding
     interpretation of the remainder of the file.
-
-.. _test-suite-overview:
-
-``test-suite`` Overview
-=======================
-
-The ``test-suite`` module contains a number of programs that can be
-compiled and executed. The ``test-suite`` includes reference outputs for
-all of the programs, so that the output of the executed program can be
-checked for correctness.
-
-``test-suite`` tests are divided into three types of tests: MultiSource,
-SingleSource, and External.
-
--  ``test-suite/SingleSource``
-
-   The SingleSource directory contains test programs that are only a
-   single source file in size. These are usually small benchmark
-   programs or small programs that calculate a particular value. Several
-   such programs are grouped together in each directory.
-
--  ``test-suite/MultiSource``
-
-   The MultiSource directory contains subdirectories which contain
-   entire programs with multiple source files. Large benchmarks and
-   whole applications go here.
-
--  ``test-suite/External``
-
-   The External directory contains Makefiles for building code that is
-   external to (i.e., not distributed with) LLVM. The most prominent
-   members of this directory are the SPEC 95 and SPEC 2000 benchmark
-   suites. The ``External`` directory does not contain these actual
-   tests, but only the Makefiles that know how to properly compile these
-   programs from somewhere else. When using ``LNT``, use the
-   ``--test-externals`` option to include these tests in the results.
-
-.. _test-suite-quickstart:
-
-``test-suite`` Quickstart
--------------------------
-
-The modern way of running the ``test-suite`` is focused on testing and
-benchmarking complete compilers using the
-`LNT <http://llvm.org/docs/lnt>`_ testing infrastructure.
-
-For more information on using LNT to execute the ``test-suite``, please
-see the `LNT Quickstart <http://llvm.org/docs/lnt/quickstart.html>`_
-documentation.
-
-``test-suite`` Makefiles
-------------------------
-
-Historically, the ``test-suite`` was executed using a complicated setup
-of Makefiles. The LNT based approach above is recommended for most
-users, but there are some testing scenarios which are not supported by
-the LNT approach. In addition, LNT currently uses the Makefile setup
-under the covers and so developers who are interested in how LNT works
-under the hood may want to understand the Makefile based setup.
-
-For more information on the ``test-suite`` Makefile setup, please see
-the :doc:`Test Suite Makefile Guide <TestSuiteMakefileGuide>`.

docs/index.rst

 
 :doc:`SphinxQuickstartTemplate`
   A template + tutorial for writing new Sphinx documentation. It is meant
   to be read in source form.
 
 :doc:`LLVM Testing Infrastructure Guide <TestingGuide>`
    A reference manual for using the LLVM testing infrastructure.
 
+:doc:`TestSuiteGuide`
+  Describes how to compile and run the test-suite benchmarks.
+
 `How to build the C, C++, ObjC, and ObjC++ front end`__
    Instructions for building the clang front-end from source.
 
    .. __: http://clang.llvm.org/get_started.html
 
 :doc:`Lexicon`
    Definition of acronyms, terms and concepts used in LLVM.