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

Commit 48c6c01

Browse files
author
Pavel V Chupin
committed
[DOC] Major documenation rewrite
* 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 86b837d commit 48c6c01

File tree

4 files changed

+231
-216
lines changed

4 files changed

+231
-216
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: 55 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,75 @@
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)
8-
91
# 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.
13-
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-
```
432

44-
Notes:
45-
- it is assumed that LIT framework, FileCheck and other LIT dependencies are
46-
available in the same directory with llvm-lit.
3+
"External" tests directory has necessary infrastructure for running tests where
4+
sources of tests are expected to be located outside of llvm-test-suite
5+
repository. Each subdirectory represents external repository for corresponding
6+
application/test.
477

488
# Directory structure
499
Every sub-directory (e.g. RSBench) contains the following content:
5010
* **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)
11+
application binary and data files.
5312
* **\*.test** - test configuration files, containing command lines, test
54-
status lines and verification patterns following [LLVM test infrastructure](https://llvm.org/docs/TestingGuide.html).
13+
status lines and verification patterns following
14+
[LLVM tests infrastructure](https://llvm.org/docs/TestingGuide.html).
5515
* **lit.local.cfg** - application specific LIT infrastructure configuration
5616
file. In case of RSBench benchmarks it sets LIT test file suffixes to `.test`
5717
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).
18+
not added to `SYCL_EXTERNAL_TESTS` list.
6019

6120
# CMake parameters
21+
6222
All parameters described in [Readme.md](../README.md#cmake-parameters) are
63-
applicable. Also extra CMake parameters are introduced to configure specific
23+
applicable.
24+
25+
***SYCL_EXTERNAL_TESTS*** semicolon-separated names of external SYCL
26+
applications which are built and run as part of the testing. Name is
27+
subdirectory name in "External" directory. Example:
28+
```
29+
-DSYCL_EXTERNAL_TESTS=RSBench
30+
```
31+
Source code of external application can be downloaded from external repository
32+
as part of the build or provided in CMake variable <APPNAME>_SRC
33+
(e.g. RSBench_SRC).
34+
35+
Also extra CMake parameters are introduced to configure specific
6436
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.
37+
* **APPName_BIN** (e.g. `RSBench_BIN`) - directory containing prebuilt
38+
binaries of the application.
39+
* **APPName_SRC** (e.g. `RSBench_SRC`) - directory containing sources of the
40+
application.
6941
* **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`).
42+
sources of the application.
7243
* **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`).
44+
to download source from GIT repository.
45+
7546
Configuration parameters are priorities from top to down. If **APPName_BIN**
7647
is specified binaries will be used directly ignoring other parameters.
7748

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

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

0 commit comments

Comments
 (0)