docs/C_API.md

# Clspv - C API wrapper

There is a C API for shared lib version of Clspv.

This C API allows for compiling OpenCL C as well as linking IR generated by Clspv.

User will need to enable CMake option to enable building Clspv as a shared lib:
```Bash
$ cmake -DCLSPV_SHARED_LIB=ON ...
```

## clBuildProgram Example Flow

```C++
#include <cstdio>
#include <cstdint>

#include "clspv/Compiler.h"

int main() {
    // CL source example:
    const char* clSrc = "__kernel void sample_test(__global int *dst, int count) {  \n"
                        "                                                           \n"
                        "   int  tid = get_global_id(0);                            \n"
                        "   for( int i = 0; i < count; i++ )                        \n"
                        "       dst[i] = tid + i;                                   \n"
                        "}                                                          \n";

    // Compile
    size_t outputSpvSize = 0;
    char* outputSpv = nullptr;
    char* outputBuildLog = nullptr;
    ClspvError ret = clspvCompileFromSourcesString(1,
                                                   NULL,
                                                   (const char**)&clSrc,
                                                   "",
                                                   &outputSpv,
                                                   &outputSpvSize,
                                                   &outputBuildLog);
    printf("Build Log:\n%s\n", outputBuildLog);
    if (ret != CLSPV_SUCCESS) {
        // Handle error ...
    }

    // Cleanup
    clspvFreeOutputBuildObjs(outputSpv, outputBuildLog);
    /*
        // User can also cleanup like so:

        free(outputSpv);       outputSpv       = NULL;
        free(outputBuildLog);  outputBuildLog  = NULL;
    */

    return 0;
}
```

## clCompileProgram and clLinkProgram Example Flow

```C++
#include <cstdio>
#include <cstdint>

#include "clspv/Compiler.h"

int main() {
    // Test/Build CL source example:
    const char* clSrc = "__kernel void sample_test(__global int *dst, int count) {  \n"
                        "                                                           \n"
                        "   int  tid = get_global_id(0);                            \n"
                        "   for( int i = 0; i < count; i++ )                        \n"
                        "       dst[i] = tid + i;                                   \n"
                        "}                                                          \n";

    const char* clSrc2 = "__kernel void sample_test2(__global float *src, __global int *dst) {  \n"
                         "    int  tid = get_global_id(0);                                      \n"
                         "    dst[tid] = (int)src[tid];                                         \n"
                         "}                                                                     \n";

    // Compile first program to LLVM IR
    size_t outputBinSize = 0;
    char* outputBin = nullptr;
    char* outputBuildLog = nullptr;
    ClspvError ret = clspvCompileFromSourcesString(1,
                                                   NULL,
                                                   (const char**)&clSrc,
                                                   "--output-format=bc ",
                                                   &outputBin,
                                                   &outputBinSize,
                                                   &outputBuildLog);
    if (ret != CLSPV_SUCCESS) {
        // Handle error ...
    }

    // Compile second program to LLVM IR
    size_t outputBinSize2 = 0;
    char* outputBin2 = nullptr;
    char* outputBuildLog2 = nullptr;
    ret = clspvCompileFromSourcesString(1,
                                        NULL,
                                        (const char**)&clSrc2,
                                        "--output-format=bc ",
                                        &outputBin2,
                                        &outputBinSize2,
                                        &outputBuildLog2);
    if (ret != CLSPV_SUCCESS) {
        // Handle error ...
    }

    // Link programs
    size_t outputSpvSize = 0;
    char* outputSpv = nullptr;
    size_t outputBinSizes[2] = { outputBinSize, outputBinSize2 };
    const char* outputBinChars[2] = { outputBin, outputBin2 };
    char* outputBuildLog3 = nullptr;
    ret = clspvCompileFromSourcesString(2,
                                        outputBinSizes,
                                        outputBinChars,
                                        "-x ir ",
                                        &outputSpv,
                                        &outputSpvSize,
                                        &outputBuildLog3);
    if (ret != CLSPV_SUCCESS) {
        // Handle error ...
    }

    // Cleanup
    clspvFreeOutputBuildObjs(outputBin,  outputBuildLog);
    clspvFreeOutputBuildObjs(outputBin2, outputBuildLog2);
    clspvFreeOutputBuildObjs(outputSpv,  outputBuildLog3);
    /*
        // User can also cleanup like so:

        free(outputBin);       outputBin       = NULL;
        free(outputBuildLog);  outputBuildLog  = NULL;
        free(outputBin2);      outputBin2      = NULL;
        free(outputBuildLog2); outputBuildLog2 = NULL;
        free(outputSpv);       outputSpv       = NULL;
        free(outputBuildLog3); outputBuildLog3 = NULL;
    */

    return 0;
}
```