chore(bindings/C): add one simple read/write example into readme and …

…code (#2421)

* 1st example

* simple example to readme

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)
 

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`.

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);
+}