Skip to content

Commit 7eab110

Browse files
author
Pavel Chupin
authored
[SYCL][DOC] Update README and docs with project details (#5689)
* Restructure contribution guidelines, keeping CONTRIBUTING.md the shared one between OpenMP outlining and DPC++ and moving DPC++ specific details into separate doc * Add more details on DPC++ project * Add more details on how to use DPC++ vs. how to contribute * Made minor style fixes
1 parent 7f37250 commit 7eab110

File tree

4 files changed

+227
-129
lines changed

4 files changed

+227
-129
lines changed

‎CONTRIBUTING.md

Lines changed: 41 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -15,25 +15,18 @@ these terms.
1515

1616
### Development
1717

18-
**NB**: For any changes not related to DPC++, but rather to LLVM in general, it
19-
is strongly encouraged that you submit the patch to https://llvm.org/ directly.
20-
See [LLVM contribution guidelines](https://llvm.org/docs/Contributing.html)
21-
for more information.
22-
23-
**NB**: A change in compiler and runtime should be accompanied with
24-
corresponding test changes.
25-
See [Test DPC++ toolchain](sycl/doc/GetStartedGuide.md#test-dpc-toolchain)
26-
section of Get Started guide for more information.
27-
28-
**Note (October, 2020)**: DPC++ runtime and compiler ABI is currently in frozen
29-
state. This means that no ABI-breaking changes will be accepted by default.
30-
Project maintainers may still approve breaking changes in some cases. Please,
31-
see [ABI Policy Guide](sycl/doc/developer/ABIPolicyGuide.md) for more
32-
information.
18+
For any changes not related to Intel Project for LLVM\* technology, but rather
19+
to LLVM in general, it is strongly encouraged that you submit the patch to
20+
https://llvm.org/ directly. See
21+
[LLVM contribution guidelines](https://llvm.org/docs/Contributing.html) for
22+
more information.
23+
24+
Every change should be accompanied with corresponding test modification (adding
25+
new test(s), extending, removing or modifying existing test(s)).
26+
27+
To contribute:
3328

3429
- Create a personal fork of the project on GitHub
35-
- For the DPC++ Compiler project, use **sycl** branch as baseline for your
36-
changes. See [Get Started Guide](sycl/doc/GetStartedGuide.md).
3730
- Prepare your patch
3831
- follow [LLVM coding standards](https://llvm.org/docs/CodingStandards.html)
3932
- [clang-format](https://clang.llvm.org/docs/ClangFormat.html) and
@@ -48,110 +41,41 @@ information.
4841
./clang/tools/clang-format/git-clang-format `git merge-base origin/sycl HEAD`
4942
```
5043

51-
to check the format of your current changes against the `origin/sycl`
52-
branch.
44+
to check the format of your current changes. `origin/sycl` branch is an
45+
example here
5346
- `-f` to also correct unstaged changes
5447
- `--diff` to only print the diff without applying
55-
- Build the project following
56-
[Get Started Guide instructions](sycl/doc/GetStartedGuide.md#build-dpc-toolchain).
57-
- Run regression tests -
58-
[instructions](sycl/doc/GetStartedGuide.md#test-dpc-toolchain).
59-
60-
### Tests development
61-
62-
Every product change should be accompanied with corresponding test modification
63-
(adding new test(s), extending, removing or modifying existing test(s)).
64-
65-
There are 3 types of tests which are used for DPC++ toolchain validation:
66-
* DPC++ in-tree tests including [check-llvm](llvm/test),
67-
[check-clang](clang/test), [check-llvm-spirv](llvm-spirv/test) and
68-
[check-sycl](sycl/test) targets stored in this repository. These tests
69-
should not have hardware (e.g. GPU, FPGA, etc.) or external software
70-
dependencies (e.g. OpenCL, Level Zero, CUDA runtimes). All tests not following
71-
this approach should be moved to DPC++ end-to-end or SYCL-CTS tests.
72-
Generally, any functional change to any of the DPC++ toolchain components
73-
should be accompanied by one or more tests of this type when possible. They
74-
allow verifying individual components and tend to be more lightweight than
75-
end-to-end or SYCL-CTS tests.
76-
77-
**General guidelines for adding DPC++ in-tree tests**:
7848

79-
- Use `sycl::` namespace instead of `cl::sycl::`
49+
#### Project-specific contribution guidelines
8050

81-
- Add a helpful comment describing what the test does at the beginning and
82-
other comments throughout the test as necessary.
51+
- [Contribute to DPC++](/../sycl/sycl/doc/developer/ContributeToDPCPP.md)
8352

84-
- Try to follow descriptive naming convention for variables, functions as
85-
much as possible.
86-
Please refer to
87-
[LLVM naming convention](https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly)
88-
89-
**DPC++ clang FE tests**:
90-
91-
- Include sycl mock headers as system headers.
92-
Example: `-internal-isystem %S/Inputs`
93-
`#include "sycl.hpp"`
94-
95-
- Use SYCL functions for invoking kernels from the mock header
96-
`(single_task, parallel_for, parallel_for_work_group)`
97-
Example:
98-
```bash
99-
`#include "Inputs/sycl.hpp"`
100-
sycl::queue q;
101-
q.submit([&](cl::sycl::handler &h) {
102-
h.single_task( { //code });
103-
});
104-
```
53+
### Pull request
10554

106-
**DPC++ headers and runtime tests**:
107-
108-
- [check-sycl](sycl/test) target contains 2 types of tests: LIT tests and
109-
unit tests. LIT tests make compile-time checks of DPC++ headers, e.g. device
110-
code IR verification, static_assert tests. Unit tests check DPC++ runtime
111-
behavior and do not perform any device code compilation, instead relying on
112-
redefining plugin API with [PiMock](sycl/unittests/helpers/PiMock.hpp) when
113-
necessary.
114-
115-
* DPC++ end-to-end (E2E) tests which are extension to
116-
[LLVM\* test suite](https://github.com/intel/llvm-test-suite/tree/intel/SYCL).
117-
A test which requires full stack including backend runtimes (e.g. OpenCL,
118-
Level Zero or CUDA) should be put to DPC++ E2E test suite following
119-
[CONTRIBUTING](https://github.com/intel/llvm-test-suite/blob/intel/CONTRIBUTING.md).
120-
121-
* SYCL-CTS are official
122-
[Khronos\* SYCL\* conformance tests](https://github.com/KhronosGroup/SYCL-CTS).
123-
They verify SYCL specification compatibility. All implementation details or
124-
extensions are out of scope for the tests. If SYCL specification has changed
125-
(SYCL CTS tests conflict with recent version of SYCL specification) or change
126-
is required in the way the tests are built with DPC++ compiler (defined in
127-
[FindIntel_SYCL](https://github.com/KhronosGroup/SYCL-CTS/blob/SYCL-1.2.1/master/cmake/FindIntel_SYCL.cmake))
128-
pull request should be created under
129-
[KhronosGroup/SYCL-CTS](https://github.com/KhronosGroup/SYCL-CTS) with required
130-
patch.
131-
132-
### Commit message
133-
134-
- When writing your commit message, please make sure to follow
55+
- When creating your commit messages, please make sure to follow
13556
[LLVM developer policies](
13657
https://llvm.org/docs/DeveloperPolicy.html#commit-messages) on the subject.
137-
- For any DPC++-related commit, the `[SYCL]` tag should be present in the
138-
commit message title. To a reasonable extent, additional tags can be used
139-
to signify the component changed, e.g.: `[PI]`, `[CUDA]`, `[Doc]`.
140-
- For product changes which require modification in tests outside of the current repository
141-
(see [Test DPC++ toolchain](sycl/doc/GetStartedGuide.md#test-dpc-toolchain)),
142-
the commit message should contain the link to corresponding test PR, e.g.: E2E
143-
test changes are available under intel/llvm-test-suite#88 or SYCL
144-
conformance test changes are available under KhronosGroup/SYCL-CTS#65 (see
145-
[Autolinked references and URLs](https://docs.github.com/en/free-pro-team/github/writing-on-github/autolinked-references-and-urls)
58+
- [The seven rules of a great Git commit message](https://cbea.ms/git-commit)
59+
are recommended read and follow.
60+
- To a reasonable extent, title tags can be used to signify the component
61+
changed, e.g.: `[PI]`, `[CUDA]`, `[Doc]`.
62+
- Create a pull request (PR) for your changes following
63+
[Creating a pull request instructions](https://help.github.com/articles/creating-a-pull-request/).
64+
- Make sure PR has a good description explaining all of the changes made,
65+
represented by commits in the PR.
66+
- When PR is merged all commits are squashed and PR description is used as
67+
the merged commit message.
68+
- Consider splitting the large set of changes on small independent PRs that
69+
can be reviewed, tested and merged independently.
70+
- For changes which require modification in tests outside of the current repository
71+
the commit message should contain the link to corresponding test PR.
72+
For example: intel/llvm-test-suite#88 or KhronosGroup/SYCL-CTS#65. (see
73+
[Autolinked references and URLs](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls)
14674
for more details). The same message should be present both in commit
14775
message and in PR description.
14876

14977
### Review and acceptance testing
15078

151-
- Create a pull request for your changes following [Creating a pull request
152-
instructions](https://help.github.com/articles/creating-a-pull-request/).
153-
- CI will run a signed-off check as soon as your PR is created - see the
154-
**check_pr** CI action results.
15579
- CI will run several build and functional testing checks as soon as the PR is
15680
approved by an Intel representative.
15781
- A new approval is needed if the PR was updated (e.g. during code review).
@@ -160,12 +84,14 @@ ready for merge.
16084

16185
### Merge
16286

163-
Project maintainers merge pull requests using one of the following options:
87+
Project gatekeepers (@intel/llvm-gatekeepers) merge pull requests using [Squash
88+
and merge] and using PR description as the commit message, replacing all
89+
individual comments made per commit. Authors of the change must ensure PR
90+
description is up to date at the merge stage, as sometimes comments addressed
91+
during code reviews can invalidate original PR description. Feel free to ping
92+
@intel/llvm-gatekeepers if your PR is green and can be merged.
16493

165-
- [Rebase and merge] The preferable choice for PRs containing a single commit
166-
- [Squash and merge] Used when there are multiple commits in the PR
167-
- Squashing is done to make sure that the project is buildable on any commit
168-
- [Create a merge commit] Used for LLVM pull-down PRs to preserve hashes of the
169-
commits pulled from the LLVM community repository
94+
Pulldown from LLVM upstream is done through merge commits to preserve hashes of
95+
the original commits pulled from the LLVM community repository.
17096

171-
*Other names and brands may be claimed as the property of others.
97+
<sub>\*Other names and brands may be claimed as the property of others.</sub>

‎README.md

Lines changed: 70 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,86 @@
11
# Intel Project for LLVM\* technology
22

3-
Intel staging area for llvm.org contribution. Home for Intel LLVM-based projects:
3+
This is the Intel staging area for llvm.org contributions and the home for
4+
Intel LLVM-based projects:
5+
6+
- [oneAPI Data Parallel C++ compiler](#oneapi-data-parallel-c-compiler)
7+
- [Late-outline OpenMP and OpenMP Offload](#late-outline-openmp-and-openmp-offload)
48

59
## oneAPI Data Parallel C++ compiler
610

711
[![](https://spec.oneapi.io/oneapi-logo-white-scaled.jpg)](https://www.oneapi.io/)
812

9-
See [sycl](https://github.com/intel/llvm/tree/sycl) branch and
10-
[DPC++ Documentation](https://intel.github.io/llvm-docs/).
11-
1213
[![Linux Post Commit Checks](https://github.com/intel/llvm/workflows/Linux%20Post%20Commit%20Checks/badge.svg)](https://github.com/intel/llvm/actions?query=workflow%3A%22Linux+Post+Commit+Checks%22)
1314
[![Generate Doxygen documentation](https://github.com/intel/llvm/workflows/Generate%20Doxygen%20documentation/badge.svg)](https://github.com/intel/llvm/actions?query=workflow%3A%22Generate+Doxygen+documentation%22)
1415

15-
DPC++ is an open, cross-architecture language built upon the ISO C++ and Khronos
16-
SYCL\* standards. DPC++ extends these standards with a number of extensions,
17-
which can be found in [sycl/doc/extensions](sycl/doc/extensions) directory.
16+
The Data Parallel C++ or DPC++ is a LLVM-based compiler project that implements
17+
compiler and runtime support for the SYCL\* language. The project is hosted in
18+
the [sycl](/../../tree/sycl) branch and is synced with the tip of the LLVM
19+
upstream main branch on a regular basis (revisions delay is usually not more
20+
than 1-2 weeks). DPC++ compiler takes everything from LLVM upstream as is,
21+
however some modules of LLVM might be not included in the default project build
22+
configuration. Additional modules can be enabled by modifying build framework
23+
settings.
1824

19-
## Late-outline OpenMP\* and OpenMP\* Offload
20-
See [openmp](https://github.com/intel/llvm/tree/openmp) branch.
25+
The DPC++ goal is to support the latest SYCL\* standard and work on that is in
26+
progress. DPC++ also implements a number of extensions to the SYCL\* standard,
27+
which can be found in the [sycl/doc/extensions](/../sycl/sycl/doc/extensions)
28+
directory.
2129

22-
# License
30+
The main purpose of this project is open source collaboration on the DPC++
31+
compiler implementation in LLVM across a variety of architectures, prototyping
32+
compiler and runtime library solutions, designing future extensions, and
33+
conducting experiments. As the implementation becomes more mature, we try to
34+
upstream as much DPC++ support to LLVM main branch as possible. See
35+
[SYCL upstreaming working group notes](/../../wiki/SYCL-upstreaming-working-group-meeting-notes)
36+
for more details.
37+
38+
Note that this project can be used as a technical foundation for some
39+
proprietary compiler products, which may leverage implementations from this open
40+
source project. One of the examples is
41+
[Intel(R) oneAPI DPC++ Compiler](https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-compiler.html)
42+
Features parity between this project and downstream projects is not guaranteed.
43+
44+
Project documentation is available at:
45+
[DPC++ Documentation](https://intel.github.io/llvm-docs/).
46+
47+
### How to use DPC++
48+
49+
#### Docker containers
50+
51+
See available containers with pre-built/pre-installed DPC++ compiler at:
52+
[Containers](/../sycl/sycl/doc/developer/DockerBKMs.md#sycl-containers-overview)
2353

24-
See [LICENSE.txt](sycl/LICENSE.TXT) for details.
54+
#### Releases
2555

26-
# Contributing
56+
Daily builds of the sycl branch on Linux are available at
57+
[releases](/../../releases).
58+
A few times a year, we publish [Release Notes](/../sycl/sycl/ReleaseNotes.md) to
59+
highlight all important changes made in the project: features implemented and
60+
issues addressed. The corresponding builds can be found using
61+
[search](https://github.com/intel/llvm/releases?q=oneAPI+DPC%2B%2B+Compiler&expanded=true)
62+
in daily releases. None of the branches in the project are stable or rigorously
63+
tested for production quality control, so the quality of these releases is
64+
expected to be similar to the daily releases.
65+
66+
#### Build from sources
67+
68+
See [Get Started Guide](/../sycl/sycl/doc/GetStartedGuide.md).
69+
70+
### Report a problem
71+
72+
Submit an [issue](/../../issues) or initiate a [discussion](/../../discussions).
73+
74+
### How to contribute to DPC++
75+
76+
See [ContributeToDPCPP](/../sycl/sycl/doc/developer/ContributeToDPCPP.md).
77+
78+
## Late-outline OpenMP\* and OpenMP\* Offload
79+
80+
See [openmp](/../../tree/openmp) branch.
81+
82+
# License
2783

28-
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
84+
See [LICENSE](/../sycl/sycl/LICENSE.TXT) for details.
2985

30-
*\*Other names and brands may be claimed as the property of others.*
86+
<sub>\*Other names and brands may be claimed as the property of others.</sub>

0 commit comments

Comments
 (0)