Portable Computing Language (pocl)
----------------------------------
pocl is being developed towards an efficient implementation of OpenCL standard
which can be easily adapted for new targets.

Please refer to the file INSTALL in this directory for building and installing
pocl.

More documentation available at http://portablecl.org/docs/html/
The main web page is at http://portablecl.org

pocl builds (as of Aug 2017) on ODROID XU3 and ODROID C2
but some tests fail.

How to build:

* get a clang / llvm. DO NOT use the ones downloaded from llvm.org, they only work
  on the distro where they were compiled. Ubuntu LTS these days ships multiple llvm
  versions even quite recent ones; get the clang+llvm from your distro's packages.

* read the pocl install/build instructions in docs

* LLVM will likely not recognize your cpu, and running cmake will give you a warning.
  run cmake with -DLLC_HOST_CPU=<yourcpu>. "yourcpu" must be something LLVM recognizes,
  usually it's simply "cortex-aXX" like cortex-a15 etc. You can get the full list by
  running `llc -mcpu=help`.

# WARNING: this document is seriously outdated
#
# considering we haven't had anyone maintaining
# the Windows build since about 2016, getting the
# current PoCL code to build on Windows will likely
# require much more effort than this howto describes.

# Compiling pocl on Windows

## Dependencies:

- Visual Studio 2013
- Git and Git bash http://git-scm.com/downloads
- CMake 2.8 or newer http://www.cmake.org/download/
- Python 2.7 for LLVM
- Pthreads-win32 binary distribution https://www.sourceware.org/pthreads-win32/
- Hwloc for Windows x64 binary distribution http://www.open-mpi.org/software/hwloc/v1.10/
- LLVM + Clang latest release sources

## Support:

- Only 64bit compiling for now
- No ICD compiling
- No VML (no stdcxxlib finding done for windows)
- Static compilation

## Building

There is shell script in `pocl/windows/setup_and_build_win64.sh`

Shell script may be ran in `Git Bash` and it downloads and installs pocl and all the
library dependencies and builds them to `/c/pocl-playground`.

To download and build everything without first fetching pocl repository one can do simply:

    curl https://github.com/pocl/pocl/raw/master/windows/setup_and_build_win64.sh | sh

Script requires following software installed on Windows 7 or later (64bit only):

- Visual Studio 2013 (e.g. community edition)
- Cmake 2.8 or later (must be added to PATH)
- Git + Git Bash
- Python 2.7 for compiling LLVM

This file contains notes for making distribution packages of pocl.

ICD
---
Pocl should probably be built with ICD enabled (``-DENABLE_ICD=ON`` CMake
option) for desktop distributions. Pocl does not have an ICD loader,
so a dependancy on one would be beneficial.

CMake options for a distribution build
--------------------------------------
- ``-DKERNELLIB_HOST_CPU_VARIANTS=distro``
  Note: this note only works for x86(-64) platform currently,
  on other platforms, it has zero effect.
  Enables runtime detection of CPU and builds separate
  kernel libraries for most common x86 CPUs.

- ``-DPOCL_ICD_ABSOLUTE_PATH=OFF``
  The pocl.icd file (which the ICD loader uses to load the pocl lib)
  by default has a full path to the installed libpocl.so file.
  Set this option to OFF and pocl will only put the dynamic library
  name into pocl.icd.

- ``-DENABLE_POCL_BUILDING=OFF``
  When OFF, POCL_BUILDING option (which causes pocl to look for required
  files in build / source directories) will be ignored
  and pocl will always look in installed paths only.

Mesa (OpenGL) interoperability
------------------------------
On some current (Jan 2014) Linux distibutions, mesa is built with LLVMpipe.
If pocl is built against a shared LLVM library, the mesa calls to its LLVM
will be re-routed to the LLVM linked in pocl, causing a segfault. Consider
linking LLVM statically to pocl. At least 'nouveau' and 'swrast_dri' are
known to suffer from this. See https://github.com/pocl/pocl/issues/46