ocl-include

Simple preprocessor that implements #include mechanism for OpenCL source files.

About

OpenCL API doesn’t provide mechanism for including header files into the main one, like in C and C++. This crate is a simple preprocessor that handles #include ... and #pragma once directives in source files, collects them over filesystem or memory, and gives a single string to the output that could be passed to OpenCL kernel builder. Also it provides mechanism to find the source file and location in it by line number in resulting string, that is helpful for OpenCL compiler messages handling.

Documentation

• crates.io version documentation
• master branch documentation

Examples

Let you have main.c and header.h files in ./examples/ folder:

main.c:

#include <header.h>

int main() {
    return RET_CODE;
}

header.h:

#pragma once

static const int RET_CODE = 0;

Filesystem only

The follwong code takes main.c from the filesystem and includes header.h into it.

use std::path::Path;
use ocl_include::*;

fn main() {
    let hook = FsHook::new()
    .include_dir(&Path::new("./examples")).unwrap();

    let node = build(&hook, Path::new("main.c")).unwrap();

    println!("{}", node.collect().0);
}

Filesystem and memory

The follwong code takes main.c source from the memory and includes header.h into it from the filesystem.

use std::path::Path;
use ocl_include::*;

fn main() {
    let main = r"
    #include <header.h>
    int main() {
        return ~RET_CODE;
    }
    ";

    let hook = ListHook::new()
    .add_hook(
        MemHook::new()
        .add_file(&Path::new("main.c"), main.to_string()).unwrap()
    )
    .add_hook(
        FsHook::new()
        .include_dir(&Path::new("./examples")).unwrap()
    );

    let node = build(&hook, Path::new("main.c")).unwrap();

    println!("{}", node.collect().0);
}

Indexing

Node.collect() also returns Index instance as seconds value. It could be used to find the source file and line number in it by line number in generated string.

Let’s imagine that our OpenCL compiler takes generated string and fails at some line. But line number isn’t helpful for us because we don’t know in which source file this line originate. Fortunately there is Index::search for this.

use std::path::Path;
use ocl_include::*;

fn main() {
    let hook = FsHook::new()
    .include_dir(&Path::new("./examples")).unwrap();

    let node = build(&hook, Path::new("main.c")).unwrap();
    let (generated, index) = node.collect();

    // Let's imagine that we complie the code here
    // and got a compiler message at specific line
    let line = 4;
    println!("line {}: '{}'", line, generated.lines().nth(line - 1).unwrap());

    // This will find the origin of this line
    let (path, local_line) = index.search(line - 1).unwrap();

    println!("origin: '{}' at line {}", path.to_string_lossy(), local_line + 1);
}

Hooks

Hook is a handler that retrieve files by their names.

The crate contains the following hooks now:

• FsHook: takes files from the filesystem.
• MemHook: retrieves the source from the memory.
• ListHook: contains a list of other hooks and tries to retrieve source from them subsequently.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

This site is open source. Improve this page.