Apache OpenDAL™ C Binding (WIP)

Note: This binding has its own independent version number, which may differ from the Rust core version. When checking for updates or compatibility, always refer to this binding's version rather than the core version.

Example

A simple read and write example

#include "assert.h"
#include "opendal.h"
#include "stdio.h"

int main()
{
    /* Initialize a operator for "memory" backend, with no options */
    opendal_result_operator_new result = opendal_operator_new("memory", 0);
    assert(result.op != NULL);
    assert(result.error == NULL);

    opendal_operator* op = result.op;

    /* Prepare some data to be written */
    opendal_bytes data = {
        .data = (uint8_t*)"this_string_length_is_24",
        .len = 24,
    };

    /* Write this into path "/testpath" */
    opendal_error *error = opendal_operator_write(op, "/testpath", &data);
    assert(error == NULL);

    /* We can read it out, make sure the data is the same */
    opendal_result_read r = opendal_operator_read(op, "/testpath");
    opendal_bytes read_bytes = r.data;
    assert(r.error == NULL);
    assert(read_bytes.len == 24);

    /* Lets print it out */
    for (int i = 0; i < 24; ++i) {
        printf("%c", read_bytes.data[i]);
    }
    printf("\n");

    /* the opendal_bytes read is heap allocated, please free it */
    opendal_bytes_free(&read_bytes);

    /* the operator_ptr is also heap allocated */
    opendal_operator_free(&op);
}

For more examples, please refer to ./examples

Prerequisites

To build OpenDAL C binding, the following is all you need:

A compiler that supports C11 and C++14, e.g. clang and gcc
To format the code, you need to install clang-format
- The opendal.h is not formatted by hands when you contribute, please do not format the file. Use make format only.
- If your contribution is related to the files under ./tests, you may format it before submitting your pull request. But notice that different versions of clang-format may format the files differently.
(optional) Doxygen need to be installed to generate documentations.

For Ubuntu and Debian:

# install C/C++ toolchain
sudo apt install -y build-essential

# install clang-format
sudo apt install clang-format

# install and build GTest library under /usr/lib and softlink to /usr/local/lib
sudo apt-get install libgtest-dev

# install CMake
sudo apt-get install cmake

# install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Makefile

To build the library and header file.
```
mkdir -p build && cd build
cmake ..
make
```
- The header file opendal.h is under ./include
- The library is under ../../target/debug after building.
- use FEATURES to enable services, like cmake .. -DFEATURES="opendal/services-memory,opendal/services-fs"
To clean the build results.
```
cargo clean
cd build && make clean
```
To build and run the tests. (Note that you need to install Valgrind and GTest)
```
cd build
make tests && ./tests
```
To build the examples
```
cd build
make basic error_handle
```

Documentation

The documentation index page source is under ./docs/doxygen/html/index.html. If you want to build the documentations yourself, you could use

# this requires you to install doxygen
make doc

Used by

Check out the users list for more details on who is using OpenDAL.

License and Trademarks

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Apache OpenDAL, OpenDAL, and Apache are either registered trademarks or trademarks of the Apache Software Foundation.