Skip to content

[SYCL][DOC] Add build instructions for Windows to GetStartedWithSYCLC… #494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 22, 2019
Merged

[SYCL][DOC] Add build instructions for Windows to GetStartedWithSYCLC… #494

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 143 additions & 30 deletions sycl/doc/GetStartedWithSYCLCompiler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Overview

The SYCL* Compiler compiles C++\-based SYCL source files with code for both CPU
and a wide range of compute accelerators. The compiler uses Khronos*
OpenCL™ API to offload computations to accelerators.


# Before You Begin

OpenCL runtime for CPU and/or GPU:
### Get `OpenCL runtime` for CPU and/or GPU:

a. OpenCL runtime for GPU: follow instructions on
[github.com/intel/compute-runtime/releases](https://github.com/intel/compute-runtime/releases)
Expand All @@ -16,55 +16,156 @@ to install.
SYCL support: follow the instructions under
[SYCL* Compiler and Runtimes](https://github.com/intel/llvm/releases/tag/2019-07)

# Build the SYCL compiler and runtime
### Get the required tools:

a. `git` - for downloading the sources (Get it at https://git-scm.com/downloads)

b. `cmake` - for building the compiler and tools, version 3.2 or later (Get it at: http://www.cmake.org/download)

c. `python` - for building the compiler and running tests (Get it at: https://www.python.org/downloads/release/python-2716/ )

d. `Visual Studio 2017 or later` (Windows only. Get it at: https://visualstudio.microsoft.com/downloads/)


# Configure environment:
For simplicity it is assumed below that the environment variable SYCL_HOME contains path to a folder where the SYCL compiler and runtime will be stored.
### Linux:
```bash
export SYCL_HOME=/export/home/workspaces/sycl_workspace
mkdir $SYCL_HOME
```
### Windows:
Open a developer command prompt using one of tho methods:
- Click start menu and search for the command prompt. So, for MSVC-2017 it is '`x64 Native Tools Command Prompt for VS 2017`'
- run 'cmd' and then '`"C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" x64`'

```bash
set SYCL_HOME=%USERPROFILE%\workspaces\sycl_workspace
mkdir %SYCL_HOME%
```
# Get `OpenCL-Headers` and `OpenCL-ICD-Loader`

**These 2 steps are optional.** The Compiler build process is going to look for available OpenCL SDK on the local machine.
If it finds suitable OpenCL, it will reuse it. Otherwise, it will automatically download `OpenCL-Headers` and `OpenCL-ICD-Loader` from GitHub and build it.
You may want to run these steps if have some unexpected problems caused by `OpenCL-Headers` or `OpenCL-ICD-Loader` at the compiler build phase.

## Get `OpenCL-Headers`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please, clarify that this is an optional step.
CMake will automatically configure OpenCL headers and ICD loader if OpenCL_INCLUDE_DIR and OpenCL_LIBRARY variables are not set.

BTW, these part of the instructions are not related to Windows enabling, so it would be better to have it committed separately. It should be okay to have a separate commit in this PR as long as it documentation only.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not know that OpenCL-Headers and ICD-Loader parts were optional. Probably because I started SYCL build on some older machine with DLLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN=1, etc.

Thank you. I am removing these 2 big blocks now.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now I am not so sure that removing those two optional blocks (download OpenCL_Headers and download/build OpenCL-ICD-Loader) was good idea.
I am going to put them to this guide again.

The reason: even with this patch (that is in code-review now): #528 nmake and make work perfectly without those optional steps/blocks, while 'ninja' does not. Ninja (or our build scripts) have some problems with dependencies. Ninja does not build ICD-Loader before building sycl.lib. SYCL CMakeLists.txt look good to me.

### Linux:
```bash
cd $SYCL_HOME
git clone https://github.com/KhronosGroup/OpenCL-Headers
export OPENCL_HEADERS=$SYCL_HOME/OpenCL-Headers
```

### Windows:
```bash
cd %SYCL_HOME%
git clone https://github.com/KhronosGroup/OpenCL-Headers
set OPENCL_HEADERS=%SYCL_HOME%\OpenCL-Headers
```

Download the LLVM* repository with SYCL support to your local machine folder
e.g. `$HOME/sycl` (assuming environment var `$SYCL_HOME`) folder using
following command:
## Get `OpenCL-ICD-Loader`
You can also find the most recent instructions for this component at https://github.com/KhronosGroup/OpenCL-ICD-Loader

### Linux:
```bash
cd $SYCL_HOME
git clone https://github.com/KhronosGroup/OpenCL-ICD-Loader
cd OpenCL-ICD-Loader
mkdir build
cd build
cmake -DOPENCL_ICD_LOADER_HEADERS_DIR=$OPENCL_HEADERS ..
make
export ICD_LIB=$SYCL_HOME/OpenCL-ICD-Loader/build/libOpenCL.so
```

### Windows:
```bash
git clone https://github.com/intel/llvm -b sycl $HOME/sycl
cd %SYCL_HOME%
git clone https://github.com/KhronosGroup/OpenCL-ICD-Loader
cd OpenCL-ICD-Loader
mkdir build
cd build
cmake -G "Ninja" -DOPENCL_ICD_LOADER_HEADERS_DIR=%OPENCL_HEADERS% -DOPENCL_ICD_LOADER_REQUIRE_WDK=OFF ..
ninja
set ICD_LIB=%SYCL_HOME%\OpenCL-ICD-Loader\build\OpenCL.lib
```

Build the SYCL compiler and runtime following instruction below:
# Checkout and Build the SYCL compiler and runtime

Defining paths to `OpenCL-Headers` and `OpenCL-ICD-Loader` is optional ( `-DOpenCL_INCLUDE_DIR=` and `-DOpenCL_LIBRARY=` ).
If you do not specify the paths explicitly, then:
- If `OpenCL-Headers` and `OpenCL-ICD-Loader` are availalbe in the system, they will be used;
- If they are not available, then OpenCL files are automatically downloaded/built from GitHub during compiler build.

### Linux:
```bash
cd $SYCL_HOME
git clone https://github.com/intel/llvm -b sycl
mkdir $SYCL_HOME/build
cd $SYCL_HOME/build
cmake -DCMAKE_BUILD_TYPE=Release \

cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86" \
-DLLVM_EXTERNAL_PROJECTS="llvm-spirv;sycl" \
-DLLVM_EXTERNAL_SYCL_SOURCE_DIR=$SYCL_HOME/sycl \
-DLLVM_EXTERNAL_LLVM_SPIRV_SOURCE_DIR=$SYCL_HOME/llvm-spirv \
-DLLVM_ENABLE_PROJECTS="clang;llvm-spirv;sycl" \
$SYCL_HOME/llvm
-DLLVM_EXTERNAL_SYCL_SOURCE_DIR=$SYCL_HOME/llvm/sycl \
-DLLVM_EXTERNAL_LLVM_SPIRV_SOURCE_DIR=$SYCL_HOME/llvm/llvm-spirv \
-DOpenCL_INCLUDE_DIR="$OPENCL_HEADERS" -DOpenCL_LIBRARY="$ICD_LIB" \
$SYCL_HOME/llvm/llvm

make -j`nproc` sycl-toolchain
```
### Windows:
```bash
mkdir %SYCL_HOME%
cd %SYCL_HOME%
git clone https://github.com/intel/llvm -b sycl
mkdir %SYCL_HOME%\build
cd %SYCL_HOME%\build

cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_EXTERNAL_PROJECTS="llvm-spirv;sycl" -DLLVM_ENABLE_PROJECTS="clang;llvm-spirv;sycl" -DLLVM_EXTERNAL_SYCL_SOURCE_DIR="%SYCL_HOME%\llvm\sycl" -DLLVM_EXTERNAL_LLVM_SPIRV_SOURCE_DIR="%SYCL_HOME%\llvm\llvm-spirv" -DCMAKE_C_COMPILER=cl -DCMAKE_CXX_COMPILER=cl -DCMAKE_C_FLAGS="/GS" -DCMAKE_CXX_FLAGS="/GS" -DCMAKE_EXE_LINKER_FLAGS="/NXCompat /DynamicBase" -DCMAKE_SHARED_LINKER_FLAGS="/NXCompat /DynamicBase" -DOpenCL_INCLUDE_DIR="%OPENCL_HEADERS%" -DOpenCL_LIBRARY="%ICD_LIB%" "%SYCL_HOME%\llvm\llvm"

ninja sycl-toolchain
```

After the build completed, the SYCL compiler/include/libraries can be found
under `$SYCL_HOME/build` directory.
in `$SYCL_HOME/build` directory.

---

## Build the SYCL runtime with libc++ library.

There is experimental support for building and linking SYCL runtime with
libc++ library instead of libstdc++. To enable it the following cmake options
should be used:

should be used.
### Linux:
```
-DSYCL_USE_LIBCXX=ON \
-DSYCL_LIBCXX_INCLUDE_PATH=<path to libc++ headers> \
-DSYCL_LIBCXX_LIBRARY_PATH=<path to libc++ and libc++abi libraries>
```

# Test the SYCL compiler and runtime

Run LIT testing using the command below after building SYCL compiler and runtime.

After building the SYCL compiler and runtime, choose the amount of LIT testing you need and run one of the LIT tests suites shown below:
### Linux:
```bash
make -j`nproc` check-all
make -j`nproc` check-all # to run all test suites including those smaller ones shown below
make -j`nproc` check-llvm # run llvm tests only
make -j`nproc` check-llvm-spirv # run llvm-spirv tests only
make -j`nproc` check-clang # run clang tests only
make -j`nproc` check-sycl # run sycl tests only
```
### Windows:
```bash
ninja check-all
ninja check-llvm
ninja check-llvm-spirv
ninja check-clang
ninja check-sycl
```
If no OpenCL GPU/CPU runtimes are available, the corresponding LIT tests are skipped

# Creating a simple SYCL program
# Create a simple SYCL program

A simple SYCL program consists of following parts:
1. Header section
Expand All @@ -78,7 +179,6 @@ A simple SYCL program consists of following parts:
Creating a file `simple-sycl-app.cpp` with the following C++ SYCL code in it:

```c++

#include <CL/sycl.hpp>

int main() {
Expand Down Expand Up @@ -129,21 +229,34 @@ int main() {

# Build and Test a simple SYCL program

To build simple-sycl-app run following command:
To build simple-sycl-app put `bin` and `lib` to PATHs and run following command:
### Linux:
```bash
export PATH=$SYCL_HOME/build/bin:$PATH
export LD_LIBRARY_PATH=$SYCL_HOME/build/lib:$LD_LIBRARY_PATH
```
### Windows:
```bash
set PATH=%SYCL_HOME%\build\bin;%PATH%
set LIB=%SYCL_HOME%\build\lib;%LIB%
```

```console
clang++ -std=c++11 -fsycl simple-sycl-app.cpp -o simple-sycl-app -lOpenCL
### Linux & Windows:
```bash
clang++ -fsycl simple-sycl-app.cpp -o simple-sycl-app.exe -lOpenCL
```

This `simple-sycl-app` application doesn't specify SYCL device for execution,
This `simple-sycl-app.exe` application doesn't specify SYCL device for execution,
so SYCL runtime will first try to execute on OpenCL GPU device first, if OpenCL
GPU device is not found, it will try to run OpenCL CPU device; and if OpenCL
CPU device is also not available, SYCL runtime will run on SYCL host device.

To run the `simple-sycl-app`:
### Linux & Windows:
```bash
./simple-sycl-app.exe
The results are correct!
```

LD_LIBRARY_PATH=$SYCL_HOME/build/lib ./simple-sycl-app
The results are correct!

NOTE: SYCL developer can specify SYCL device for execution using device
selectors (e.g. `cl::sycl::cpu_selector`, `cl::sycl::gpu_selector`) as
Expand Down Expand Up @@ -194,6 +307,8 @@ int main() {

```

# C++ standard
- Minimally support C++ standard is c++11 on Linux and c++14 on Windows.

# Known Issues or Limitations

Expand All @@ -202,8 +317,6 @@ int main() {
- SYCL host device is not fully supported.
- SYCL works only with OpenCL implementations supporting out-of-order queues.


# Find More

SYCL 1.2.1 specification: [www.khronos.org/registry/SYCL/specs/sycl-1.2.1.pdf](https://www.khronos.org/registry/SYCL/specs/sycl-1.2.1.pdf)