From 0885f82c2ab4aeff5e46f8a3fbc336a4097bfd71 Mon Sep 17 00:00:00 2001 From: Ji-Xinyou Date: Mon, 5 Jun 2023 23:57:54 +0800 Subject: [PATCH 1/2] 1st example --- bindings/c/Makefile | 20 +++++++++++- bindings/c/examples/basicrw.c | 57 +++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 bindings/c/examples/basicrw.c diff --git a/bindings/c/Makefile b/bindings/c/Makefile index 36b1547adba9..0d62b6e947af 100644 --- a/bindings/c/Makefile +++ b/bindings/c/Makefile @@ -19,17 +19,19 @@ RPATH=$(PWD)/../../target/debug OBJ_DIR=./build DOC_DIR=./docs +CCFLAGS=-I./include CXXFLAGS=-I./include -std=c++14 LDFLAGS=-L$(RPATH) -Wl,-rpath,$(RPATH) LIBS=-lopendal_c -lgtest -lpthread .PHONY: all -all: build test +all: build test examples .PHONY: format format: find . -name '*.cpp' -exec clang-format -i --style=WebKit --verbose {} \; + find . -name '*.c' -exec clang-format -i --style=WebKit --verbose {} \; .PHONY: build build: @@ -46,9 +48,25 @@ doc: mkdir -p $(DOC_DIR) doxygen Doxyfile +# build examples begin +EXAMPLES=$(wildcard ./examples/*.c) +EXAMPLE_OBJECTS=$(EXAMPLES:.c=.o) +EXAMPLE_TARGETS=$(EXAMPLES:.c=) +.PHONY: examples +examples: $(EXAMPLE_TARGETS) + +$(EXAMPLE_TARGETS): % : %.o + $(CC) $(CCFLAGS) -o $@ $< $(LDFLAGS) $(LIBS) + +%.o: %.c + $(CC) $(CCFLAGS) -c $< -o $@ +# build examples end + .PHONY: clean clean: cargo clean + rm -rf $(EXAMPLE_OBJECTS) + rm -rf $(EXAMPLE_TARGETS) rm -rf $(OBJ_DIR) rm -rf $(DOC_DIR) diff --git a/bindings/c/examples/basicrw.c b/bindings/c/examples/basicrw.c new file mode 100644 index 000000000000..2f8ca6ae8ec7 --- /dev/null +++ b/bindings/c/examples/basicrw.c @@ -0,0 +1,57 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +#include "assert.h" +#include "opendal.h" +#include "stdio.h" + +int main() +{ + /* Initialize a operator for "memory" backend, with no options */ + opendal_operator_ptr op = opendal_operator_new("memory", 0); + assert(op.ptr != NULL); + + /* 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_code code = opendal_operator_blocking_write(op, "/testpath", data); + assert(code == OPENDAL_OK); + + /* We can read it out, make sure the data is the same */ + opendal_result_read r = opendal_operator_blocking_read(op, "/testpath"); + opendal_bytes* read_bytes = r.data; + assert(r.code == OPENDAL_OK); + 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); +} From 28b010d330d9b9f235d9b2fae7a96299ec1938e7 Mon Sep 17 00:00:00 2001 From: Ji-Xinyou Date: Tue, 6 Jun 2023 00:05:54 +0800 Subject: [PATCH 2/2] simple example to readme --- bindings/c/README.md | 90 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 73 insertions(+), 17 deletions(-) diff --git a/bindings/c/README.md b/bindings/c/README.md index ec340336cde5..d46f40b6e7ba 100644 --- a/bindings/c/README.md +++ b/bindings/c/README.md @@ -1,6 +1,50 @@ # OpenDAL C Binding (WIP) -# Build C bindings +## Example +A simple read and write example +```C +#include "assert.h" +#include "opendal.h" +#include "stdio.h" + +int main() +{ + /* Initialize a operator for "memory" backend, with no options */ + opendal_operator_ptr op = opendal_operator_new("memory", 0); + assert(op.ptr != NULL); + + /* 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_code code = opendal_operator_blocking_write(op, "/testpath", data); + assert(code == OPENDAL_OK); + + /* We can read it out, make sure the data is the same */ + opendal_result_read r = opendal_operator_blocking_read(op, "/testpath"); + opendal_bytes* read_bytes = r.data; + assert(r.code == OPENDAL_OK); + 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 C++ compiler** that supports **c++14**, *e.g.* clang++ and g++ @@ -30,25 +74,37 @@ sudo ln -s /usr/lib/libgtest.a /usr/local/lib/libgtest.a sudo ln -s /usr/lib/libgtest_main.a /usr/local/lib/libgtest_main.a ``` -## Build -To build the library and header file. -```shell -make build -``` +## Makefile +- To **build the library and header file**. -- The header file `opendal.h` is under `./include` -- The library is under `../../target/debug` after building. + ```sh + make build + ``` -To clean the build results. -```shell -make clean -``` + - The header file `opendal.h` is under `./include` -## Test -To build and run the tests. (Note that you need to install GTest) -```shell -make test -``` + - The library is under `../../target/debug` after building. + + +- To **clean** the build results. + + ```sh + make clean + ``` + +- To build and run the **tests**. (Note that you need to install GTest) + + ```sh + make test + ``` + +- To build the **examples** + + ```sh + make examples + ``` + + ## Documentation The documentation index page source is under `./docs/doxygen/html/index.html`.