Skip to content
This repository was archived by the owner on Mar 28, 2023. It is now read-only.

Commit 4a204bd

Browse files
author
Pavel Chupin
authored
[DOC] Major documentation update (#200)
* Simplified instructions for the first local run * Clarified variables, parameters meaning * Fixed inconsistencies with implementation * Outlined special test categories External and ExtraTests * Other minor fixes TODO: * Update LIT parameters, some are not used now, some are not documented Signed-off-by: Pavel V Chupin <[email protected]>
1 parent 5b4f67d commit 4a204bd

File tree

4 files changed

+243
-219
lines changed

4 files changed

+243
-219
lines changed

‎CONTRIBUTING.md

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,10 @@ for more information.
3939
branch.
4040
- `-f` to also correct unstaged changes
4141
- `--diff` to only print the diff without applying
42-
- Instructions about running DPC++ tests
43-
- see [README.md](SYCL/README.md).
42+
43+
### Testing
44+
45+
- See [SYCL/README.md](SYCL/README.md) for instructions.
4446

4547
### Commit message
4648

@@ -55,6 +57,10 @@ for more information.
5557

5658
- Create a pull request for your changes following [Creating a pull request
5759
instructions](https://help.github.com/articles/creating-a-pull-request/).
60+
- PR description should follow same rules as commit message. It is used as
61+
commit message on the final merge.
62+
- Changes addressing comments made during code review should be added as a
63+
separate commits to the same PR.
5864
- CI will run checks which are prerequisites for submitting PR:
5965
- clang-format-check/build checks that the patch matches coding style
6066
(see [clang-format](https://clang.llvm.org/docs/ClangFormat.html));
@@ -76,12 +82,7 @@ ready for merge.
7682

7783
### Merge
7884

79-
Project maintainers merge pull requests using one of the following options:
80-
81-
- [Rebase and merge] The preferable choice for PRs containing a single commit
82-
- [Squash and merge] Used when there are multiple commits in the PR
83-
- Squashing is done to make sure that the project is buildable on any commit
84-
- [Create a merge commit] Used for LLVM pull-down PRs to preserve hashes of the
85-
commits pulled from the LLVM community repository
85+
Project maintainers merge pull requests by "Squash and merge". PR description
86+
is used as final commit message.
8687

87-
*Other names and brands may be claimed as the property of others.
88+
\*Other names and brands may be claimed as the property of others.

‎SYCL/External/README.md

Lines changed: 63 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,80 @@
1-
# Table of contents
2-
* [Overview](#overview)
3-
* [Execution](#execution)
4-
* [Directory structure](#directory-structure)
5-
* [CMake parameters](#cmake-parameters)
6-
* [LIT parameters accepted by LIT executor](#lit-parameters-accepted-by-lit-executor)
7-
* [LIT features which can be used to configure test execution](#lit-features-which-can-be-used-to-configure-test-execution)
1+
> **NOTE**
2+
> This is experimental extension of test suite. Could be dropped or extended
3+
> further at some later point.
84
95
# Overview
10-
This directory contains SYCL-related infrastructure for running tests which
11-
sources are stored outside of this repository. Tests are distributed in
12-
sub-directories. One directory per application/test repository.
136

14-
# Execution
15-
```
16-
git clone <GIT_REPO> # e.g. https://github.com/intel/llvm-test-suite
17-
cd llvm-test-suite
18-
mkdir build
19-
cd build
20-
# configuring test execution (selecting compiler, target BE and target device,
21-
#downloading and building RSBench sources from default location)
22-
cmake -G Ninja \
23-
-DTEST_SUITE_SUBDIRS=SYCL \
24-
-DTEST_SUITE_LIT=<PATH_TO_llvm-lit> \
25-
-DCHECK_SYCL_ALL="opencl:cpu,acc,gpu,host;level_zero:gpu,host" \
26-
-DCMAKE_CXX_COMPILER=<PATH_TO_sycl_compiler> \
27-
-DSYCL_EXTERNAL_TESTS="RSBench" \
28-
..
29-
# Build and run full list of SYCL tests
30-
ninja check
31-
# Build all tests dependencies
32-
ninja
33-
# Run all SYCL tests
34-
llvm-lit .
35-
# Get list of available tests
36-
llvm-lit . --show-tests
37-
# Run specific test (e.g. RSBench only)
38-
llvm-lit SYCL/External/RSBench
39-
# Run tests with parameters
40-
llvm-lit --param target_devices=host,gpu --param sycl_be=level_zero \
41-
--param dpcpp_compiler=path/to/clang++ --param dump_ir=True SYCL/External/RSBench
42-
```
7+
"External" tests directory has necessary infrastructure for running tests where
8+
sources of tests are expected to be located outside of llvm-test-suite
9+
repository. Each subdirectory represents external repository for corresponding
10+
application/test.
4311

44-
Notes:
45-
- it is assumed that LIT framework, FileCheck and other LIT dependencies are
46-
available in the same directory with llvm-lit.
12+
# Adding external test
4713

48-
# Directory structure
49-
Every sub-directory (e.g. RSBench) contains the following content:
14+
See [RSBench](RSBench) as example, it contains the following:
5015
* **CMakeLists.txt** - CMake configuration file which is used to obtain
51-
application binary and data files. There are several variables which are
52-
used by it (see [Main parameters](#main-parameters) section for details)
53-
* **\*.test** - test configuration files, containing command lines, test
54-
status lines and verification patterns following [LLVM test infrastructure](https://llvm.org/docs/TestingGuide.html).
16+
application binary and data files.
5517
* **lit.local.cfg** - application specific LIT infrastructure configuration
56-
file. In case of RSBench benchmarks it sets LIT test file suffixes to `.test`
18+
file. In case of RSBench benchmark it sets LIT test file suffixes to `.test`
5719
and mark all tests in directory unsupported if corresponding directory is
58-
not added to `SYCL_EXTERNAL_TESTS` list (benchmark is not included in
59-
testing).
20+
not added to `SYCL_EXTERNAL_TESTS` list. See more at:
21+
[LLVM Testing Guide](https://llvm.org/docs/TestingGuide.html#platform-specific-tests)
22+
* **\*.test** - test configuration files, containing command lines, test
23+
status lines and verification patterns per each platform.
6024

6125
# CMake parameters
62-
All parameters described in [Readme.md](../README.md#cmake-parameters) are
63-
applicable. Also extra CMake parameters are introduced to configure specific
26+
27+
All parameters described in [README.md](../README.md#cmake-parameters) are
28+
applicable.
29+
30+
***SYCL_EXTERNAL_TESTS*** semicolon-separated names of external SYCL
31+
applications which are built and run as part of the testing. Name is
32+
subdirectory name in "External" directory. Example:
33+
```
34+
-DSYCL_EXTERNAL_TESTS=RSBench
35+
```
36+
Source code of external application can be downloaded from external repository
37+
as part of the build or provided in CMake variable <APPNAME>_SRC
38+
(e.g. RSBench_SRC).
39+
40+
Also extra CMake parameters are introduced to configure specific
6441
application:
65-
* **APPName_BIN** (e.g. `RSBench_BIN`) - point to the directory containing
66-
prebuilt binaries of the application.
67-
* **APPName_SRC** (e.g. `RSBench_SRC`) - point to the directory containing
68-
sources of the application.
42+
* **APPName_BIN** (e.g. `RSBench_BIN`) - directory containing prebuilt
43+
binaries of the application.
44+
* **APPName_SRC** (e.g. `RSBench_SRC`) - directory containing sources of the
45+
application.
6946
* **APPName_URL** (e.g. `RSBench_URL`) - URL to the GIT repository containing
70-
sources of the application (default value for RSBench benchmark is
71-
`https://github.com/ANL-CESAR/RSBench.git`).
47+
sources of the application.
7248
* **APPName_TAG** (e.g. `RSBench_TAG`) - GIT tag or hash or branch name used
73-
to download source from GIT repository (default value for RSBench
74-
benchmark is `origin/master`).
49+
to download source from GIT repository.
50+
7551
Configuration parameters are priorities from top to down. If **APPName_BIN**
7652
is specified binaries will be used directly ignoring other parameters.
7753

78-
# LIT parameters accepted by LIT executor:
79-
All parameters described in [Readme.md](../README.md#lit-parameters-accepted-by-lit-executor) are applicable.
54+
# Build and run tests
55+
56+
Get sources
57+
58+
```
59+
git clone https://github.com/intel/llvm-test-suite
60+
cd llvm-test-suite
61+
mkdir build
62+
cd build
63+
```
64+
65+
With compiler tools available in the PATH:
66+
67+
```
68+
# Configure
69+
cmake \
70+
-DCMAKE_CXX_COMPILER=clang++ \
71+
-DTEST_SUITE_SUBDIRS=SYCL \
72+
-DCHECK_SYCL_ALL="level_zero:gpu" \
73+
-DSYCL_EXTERNAL_TESTS="RSBench" \
74+
..
75+
76+
# Build and Run
77+
make check-sycl-all
78+
79+
```
8080

81-
# LIT features which can be used to configure test execution:
82-
All features described in [Readme.md](../README.md#lit-features-which-can-be-used-to-configure-test-execution) are applicable.

‎SYCL/ExtraTests/README.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
> **NOTE**
2+
> This is experimental extension of test suite. Could be dropped or extended
3+
> further at some later point.
4+
5+
# Overview
6+
7+
"ExtraTests" directory contains infrastructure for picking up LIT style tests
8+
from another external directory passed in SYCL_EXTRA_TESTS_SRC.
9+
10+
# CMake parameters
11+
12+
All parameters described in [Readme.md](../README.md#cmake-parameters) are
13+
applicable. Additional parameters for this test category:
14+
15+
***SYCL_EXTRA_TESTS_SRC*** path to directory which contains additional LIT
16+
tests.
17+
18+
# Example
19+
20+
```
21+
# Configure
22+
cmake -G Ninja \
23+
-DTEST_SUITE_SUBDIRS=SYCL \
24+
-DTEST_SUITE_LIT=<path/to/llvm-lit> \
25+
-DCHECK_SYCL_ALL="opencl:cpu,acc,gpu,host;level_zero:gpu,host" \
26+
-DCMAKE_CXX_COMPILER=<path/to/clang++> \
27+
-DSYCL_EXTRA_TESTS_SRC=<path/to/more/lit/tests/sources>
28+
..
29+
30+
# Build and run full list of SYCL tests
31+
ninja ninja check-sycl-all
32+
```

0 commit comments

Comments
 (0)