This is an automated email from the ASF dual-hosted git repository.
xyji pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
The following commit(s) were added to refs/heads/main by this push:
new 820839229 chore(bindings/C): add one simple read/write example into
readme and code (#2421)
820839229 is described below
commit 820839229df2b658a7fd36a15224ae9941f049fa
Author: xyJi <[email protected]>
AuthorDate: Tue Jun 6 01:54:29 2023 +0800
chore(bindings/C): add one simple read/write example into readme and code
(#2421)
* 1st example
* simple example to readme
---
bindings/c/Makefile | 20 +++++++++-
bindings/c/README.md | 90 +++++++++++++++++++++++++++++++++++--------
bindings/c/examples/basicrw.c | 57 +++++++++++++++++++++++++++
3 files changed, 149 insertions(+), 18 deletions(-)
diff --git a/bindings/c/Makefile b/bindings/c/Makefile
index 36b1547ad..0d62b6e94 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/README.md b/bindings/c/README.md
index ec340336c..d46f40b6e 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`.
diff --git a/bindings/c/examples/basicrw.c b/bindings/c/examples/basicrw.c
new file mode 100644
index 000000000..2f8ca6ae8
--- /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);
+}
