CLCC - The OpenCL kernel Compiler

Version 0.3.0 (build: 25)

SourceForge.net project page: http://www.sourceforge.net/projects/clcc

Introduction
Benefits
Usage
License
Building
Compatibility
Changelog
Todo List
Credits

Introduction

CLCC is a compiler for OpenCL kernel source files. It is intended to be a tool for application developers who need to incorporate OpenCL source code into their programs and who want to verify their OpenCL code actually gets compiled by the driver before their program tries to compile it on-demand.

Benefits

The benefits of using CLCC are simple: when building an OpenCL application, you write "normal" code and OpenCL code. The normal code gets checked by your ordinary compiler, but the OpenCL code is not, leaving you with the task of handling compilation errors in your application code. Something which isn't always possible or easy.

By compiling your code with CLCC during the build phase, you can quickly spot errors and fix them in your favorite development environment.

Usage

CLCC can be invoked from the command-line using the following syntax:

• clcc [options] file(s)...

Options are:

• --help show the list of available options
• --version display the version number of the program
• --info display a list of OpenCL platforms and devices
• --cloptions options to pass to the OpenCL compiler
• --clpath <arg> specify which OpenCL dynamic library to load
• --platform_filter case-insensitive platform name filter
• --device_filter case-insensitive device name filter
• --device_type <arg> specify which device type to compile for, where <arg> can be one of:
  • CPU compile for CPU devices
  • GPU compile for GPU devices
  • ACCELERATOR compile for ACCELERATOR devices
  • ALL compile for all devices (default)
• --platform_index,-p zero-based index of platform to compile for
• --device_index,-d zero-based index of device to compiler for
• --add_headers add CLCC headers to output binaries

If you specify more than on OpenCL source file on the command line, the files are compiled into a single program. Note that this behavior differs from the behavior in version 0.1

License

This project is available under the Boost Software License, Version 1.0

Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following:

The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Building

To build CLCC you will need to have a copy of the Boost Libraries installed on your system. You will find these at http://www.boost.org This version was built against Boost version 1.47.0

To generate makefiles and/or project files for your favorite IDE on your favorite platform, you will need CMake version 2.8 or higher, which you can find at http://www.cmake.org

Parts of this code are Copyright (c) 2008-2009 The Khronos Group Inc. Find more information on OpenCL at http://www.khronos.org/opencl/

To build CLCC from source, follow these steps:

• Unpack the source code into a folder (i.e. clcc)
• Create a build directory (i.e. build)
• From within the build folder, execute CMake to configure the project. Don't forget to specify the Boost root folder on the command-line in case it cannot be found automatically by CMake:
  • cmake -DBOOST_ROOT=<path_to_your_boost> <path_to_clcc_source_dir>
• To build clcc itself run
  • cmake --build . --config Release --target clcc
• To build the documentation run
  • cmake --build . --config Release --target clcc_doc
• To build an installer package run
  • cmake --build . --config Release --target package

Compatibility

This code was built and tested on the following platforms:

• Windows XP (x64, SP2) using Visual Studio 2008 (SP1)
• Max OS X 10.6.2 using XCode 3.2.1

The code should compile on any decent C++ compiler, but your mileage may vary.

Running

To run CLCC on any platform you will need a properly installed OpenCL driver. CLCC will attempt to locate the OpenCL dynamic library automatically, but if it fails you can try to pass it to CLCC by using the --clpath command line argument

Run-time dependencies

• Windows Visual Studio 2008 version: on Windows you will need the Visual Studio 2008 (x86) run-time library redistributables which you can find at this location: http://www.microsoft.com/downloads/details.aspx?FamilyID=9b2da534-3e03-4391-8a4d-074b9f2bc1bf&displaylang=en

• Windows Visual Studio 2010 version: on Windows you will need the Visual Studio 2010 (x86) run-time library redistributables which you can find at this location: http://www.microsoft.com/download/en/details.aspx?id=5555

Changelog

v0.3 (2012-01-15)

• (CLCC) added --add_headers option to define the binary output format
• (CLCC) added --platform_index/-p and --device_index/-d option for selecting platform & device by index
• (CLCC) added --device_filter option to allow building for specific devices only

v0.2 (2011-11-07)

• (CLCC) added --output_path option to allow specification of output filename
• (CLCC) added --platform_filter option to allow building for specific platforms only
• (CLCC) multiple .cl files on the command-line are now compiled as a single program (breaking change)
• (CLCC) added support for passing options to the OpenCL Compiler
• (CLCC) added option to save binaries
• (CLCC) fixed error when calling clCreateContextFromType with NULL argument
• (CLEW) added error code for failing to import a function
• (CLEW) added checking to function importer
• (CLEW) added support for special error codes

v0.1 (2009-12-08)

• Initial setup of code tree, tested under Windows and Mac OS X using Visual Studio 2008 and XCode 3.1

Todo

• add support for vender-specific extensions to CLEW
• add support for OpenCL 1.2 specification to CLEW and CLCC

Credits

CLCC was written by George van Venrooij of Organic Vectory B.V.
Contact him by e-mailing to: at george at organicvectory dot com

Contributions were made by the following authors:

• Fredrik Orderud
• Ian Cullinan

(c) 2009-2012 Organic Vectory B.V. - http://www.organicvectory.com