libclc/README.md

   1 # libclc
   2
   3 libclc is an open source implementation of the library
   4 requirements of the OpenCL C programming language, as specified by the
   5 OpenCL 1.1 Specification. The following sections of the specification
   6 impose library requirements:
   7
   8   * 6.1: Supported Data Types
   9   * 6.2.3: Explicit Conversions
  10   * 6.2.4.2: Reinterpreting Types Using as_type() and as_typen()
  11   * 6.9: Preprocessor Directives and Macros
  12   * 6.11: Built-in Functions
  13   * 9.3: Double Precision Floating-Point
  14   * 9.4: 64-bit Atomics
  15   * 9.5: Writing to 3D image memory objects
  16   * 9.6: Half Precision Floating-Point
  17
  18 libclc is intended to be used with the Clang compiler's OpenCL frontend.
  19
  20 libclc is designed to be portable and extensible. To this end, it provides
  21 generic implementations of most library requirements, allowing the target
  22 to override the generic implementation at the granularity of individual
  23 functions.
  24
  25 libclc currently supports PTX, AMDGPU, SPIRV and CLSPV targets, but support for
  26 more targets is welcome.
  27
  28 ## Compiling and installing
  29
  30 (in the following instructions you can use `make` or `ninja`)
  31
  32 For an in-tree build, Clang must also be built at the same time:
  33 ```
  34 $ cmake <path-to>/llvm-project/llvm/CMakeLists.txt -DLLVM_ENABLE_PROJECTS="libclc;clang" \
  35     -DCMAKE_BUILD_TYPE=Release -G Ninja
  36 $ ninja
  37 ```
  38 Then install:
  39 ```
  40 $ ninja install
  41 ```
  42 Note you can use the `DESTDIR` Makefile variable to do staged installs.
  43 ```
  44 $ DESTDIR=/path/for/staged/install ninja install
  45 ```
  46 To build out of tree, or in other words, against an existing LLVM build or install:
  47 ```
  48 $ cmake <path-to>/llvm-project/libclc/CMakeLists.txt -DCMAKE_BUILD_TYPE=Release \
  49   -G Ninja -DLLVM_DIR=$(<path-to>/llvm-config --cmakedir)
  50 $ ninja
  51 ```
  52 Then install as before.
  53
  54 In both cases this will include all supported targets. You can choose which
  55 targets are enabled by passing `-DLIBCLC_TARGETS_TO_BUILD` to CMake. The default
  56 is `all`.
  57
  58 In both cases, the LLVM used must include the targets you want libclc support for
  59 (`AMDGPU` and `NVPTX` are enabled in LLVM by default). Apart from `SPIRV` where you do
  60 not need an LLVM target but you do need the
  61 [llvm-spirv tool](https://github.com/KhronosGroup/SPIRV-LLVM-Translator) available.
  62 Either build this in-tree, or place it in the directory pointed to by
  63 `LLVM_TOOLS_BINARY_DIR`.
  64
  65 ## Website
  66
  67 https://libclc.llvm.org/