-# Building the OpenCL ICD Loader and Tests
+# OpenCL ICD Loader
-The build system will build ICD Loader library (OpenCL.dll or libOpenCL.so), the
-ICD Loader Test binary (icd_loader_test), and some helper libraries for the test.
+This repo contains the source code and tests for the Khronos official OpenCL ICD Loader.
-## Linux
+## CI Build Status
-Run "make"
+TBD
-## Windows
+## Introduction
-Run "build_using_cmake.bat"
+OpenCL defines an *Installable Client Driver* (ICD) mechanism to allow developers to build applications against an *Installable Client Driver* loader (ICD loader) rather than linking their applications against a specific OpenCL implementation.
+The ICD Loader is responsible for:
-## Running ICD Test
+* Exporting OpenCL API entry points
+* Enumerating OpenCL implementations
+* Forwarding OpenCL API calls to the correct implementation
-The ICD Test can be run using ctest, which is a companion to cmake. It can also be
-run directly by executing icd_loader_test(.exe) executable from the bin folder.
+This repo contains the source code and tests for the Khronos official OpenCL ICD Loader.
-### Linux
+Note that this repo does not contain an OpenCL implementation (ICD).
+You will need to obtain and install an OpenCL implementation for your OpenCL device that supports the OpenCL ICD extension `cl_khr_icd` to run an application using the OpenCL ICD Loader.
-1. Add driver stub as an ICD
- echo full/path/to/libOpenCLDriverStub.so > /etc/OpenCL/vendors/test.icd
+The OpenCL *Installable Client Driver* extension (`cl_khr_icd`) is described in the OpenCL extensions specification, which may be found on the [Khronos OpenCL Registry](https://www.khronos.org/registry/OpenCL/).
+
+## Build Instructions
+
+### Dependencies
+
+The OpenCL ICD Loader requires OpenCL Headers.
+To use system OpenCL Headers, please specify the OpenCL Header location using the CMake variable `OPENCL_ICD_LOADER_HEADERS_DIR`.
+By default, the OpenCL ICD Loader will look for OpenCL Headers in the `inc` directory.
+
+The OpenCL ICD Loader uses CMake for its build system.
+If CMake is not provided by your build system or OS pcakage manager, please consult the [CMake website](https://cmake.org).
+
+### Build and Install Directories
+
+A common convention is to place the `build` directory in the top directory of the repository and to place the `install` directory as a child of the `build` directory.
+The remainder of these instructions follow this convention, although you may place these directores in any location.
+
+### Example Usage
+
+For most Windows and Linux usages, the following steps are sufficient to build the OpenCL ICD Loader:
+
+1. Clone this repo:
+
+ git clone https://github.com/KhronosGroup/OpenCL-ICD-Loader
+
+1. Obtain the OpenCL Headers, if you are not planning to use system OpenCL headers.
+Headers may be obtained from the [Khronos OpenCL Headers](https://github.com/KhronosGroup/OpenCL-Headers) repository.
+
+1. Create a `build` directory:
+
+ cd OpenCL-ICD-Loader
+ mkdir build
+ cd build
+
+1. Invoke `cmake` to generate solution files, Makefiles, or files for other build systems.
+
+ cmake ..
-2. Run test using ctest
- make test
+1. Build using the CMake-generated files.
-### Windows
+Notes:
-1. Add driver stub as an ICD by adding appropriate registry value
- Key for 32-bit apps: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Khronos\OpenCL\Vendors
- Key for 64-bit apps: HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors
+* For 64-bit Windows builds, you may need to specify a 64-bit generator manually, for example:
- Add a REG_DWORD value:
- Name: c:/full/path/to/OpenCLDriverStub.dll
- Data: 0
+ cmake.exe -G "Visual Studio 14 2015 Win64" ..
- Note: The build_using_cmake.bat builds ICD test as a 32-bit binary.
+* Some users may prefer to use a CMake GUI frontend, such as `cmake-gui` or `ccmake`, vs. the command-line CMake.
+
+## OpenCL ICD Loader Tests
+
+OpenCL ICD Loader Tests can be run using `ctest`, which is a companion to CMake.
+The OpenCL ICD Loader Tests can also be run directly by executing icd_loader_test(.exe) executable from the bin folder.
+
+### Test Setup
+
+The OpenCL ICD Loader Tests use a "stub" ICD, which must be set up manually.
+The OpenCL ICD Loader Tests will "fail" if the "stub" ICD is not set up correctly.
+The method to install the "stub" ICD is operating system dependent.
+
+On Linux, install the "stub" ICD by creating a file with the full path to the "stub" ICD in `/etc/OpenCL/vendors`:
+
+ echo full/path/to/libOpenCLDriverStub.so > /etc/OpenCL/vendors/test.icd
+
+On Windows, add the "stub" ICD by adding a `REG_DWORD` value to the registry keys:
+
+ // For 32-bit operating systems, or 64-bit tests on a 64-bit operating system:
+ HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors
-2. Run test using ctest.exe
- cd build
- ctest.exe
+ // For 32-bit tests on a 64-bit operating system:
+ HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Khronos\OpenCL\Vendors
+
+ // The name of the REG_DWORD value should be the full path to the "stub" ICD
+ // OpenCLDriverStub.dll, and the data for this value should be 0.
+
+### Running Tests
+
+To run the tests, invoke `ctest` from the `build` directory.
+The CMake-generated build files may be able to invoke the OpenCL ICD Loader tests as well.
+
+### Test Cleanup
+
+Manually remove the file or registry keys added during Test Setup.
+
+## Support
-### Cleanup
+Please create a GitHub issue to report an issue or ask questions.
-Manually remove the registry key or .icd files added for running the ICD test.
+## Contributing
-The "build" and "bin" folders are autogenerated by the build so those may be
-safely deleted without losing any source code (on Linux "make clobber" will
-delete them).
+Contributions to the OpenCL ICD Loader are welcomed and encouraged.
+You will be prompted with a one-time "click-through" CLA dialog as part of submitting your pull request or other contribution to GitHub.
\ No newline at end of file
projects / platform / upstream / OpenCL-ICD-Loader.git / commitdiff