From b54a72ed500760cf2edae0e344b2a255414b5ae3 Mon Sep 17 00:00:00 2001 From: Ji-Xinyou Date: Wed, 17 May 2023 18:31:54 +0800 Subject: [PATCH 1/7] toc of doc Signed-off-by: Ji-Xinyou --- bindings/c/CONTRIBUTING.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 bindings/c/CONTRIBUTING.md diff --git a/bindings/c/CONTRIBUTING.md b/bindings/c/CONTRIBUTING.md new file mode 100644 index 000000000000..2e45e7864a0e --- /dev/null +++ b/bindings/c/CONTRIBUTING.md @@ -0,0 +1,15 @@ +# Contributing + +## Setup + +### Using a dev container environment + +### Bring your own toolbox + +## Prepare + +## Build + +## Test + +## Docs From e220bfe89968c78e5a76bac22240aa49df6233c3 Mon Sep 17 00:00:00 2001 From: Ji-Xinyou Date: Wed, 17 May 2023 18:46:05 +0800 Subject: [PATCH 2/7] step Signed-off-by: Ji-Xinyou --- bindings/c/CONTRIBUTING.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/bindings/c/CONTRIBUTING.md b/bindings/c/CONTRIBUTING.md index 2e45e7864a0e..b11cf295cc1b 100644 --- a/bindings/c/CONTRIBUTING.md +++ b/bindings/c/CONTRIBUTING.md @@ -1,15 +1,53 @@ # Contributing +1. [Contributing](#contributing) + 1. [Setup](#setup) + 1. [Using a dev container environment](#using-a-dev-container-environment) + 2. [Bring your own toolbox](#bring-your-own-toolbox) + 2. [Prepare](#prepare) + 3. [Build](#build) + 4. [Test](#test) + 5. [Docs](#docs) ## Setup ### Using a dev container environment ### Bring your own toolbox +To build OpenDAL C binding, the tools you need it very simple. +All you need is +- A C++ compiler that supports c++14 +- A Rust toolchain that satifies the MSRV +- (optional) if you want 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 + - 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. ## Prepare ## Build +To build the library and header file. +```shell +make build +``` +The header file `opendal.h` is under `./include` and the library is under `../../target/debug` after +building. + +To clean the build results. +```shell +make clean +``` ## Test +To build and run the tests. +```shell +make test +``` ## Docs +The OpenDAL C binding currently do not have a documentation online(Open to contribution). +If you want to know more about the C binding, you may: +- Have a look at the comments inline with Rust codes under the `./src` or the comments in `opendal.h` +- Have a look at the comments of the Rust core +- Have a look at the test files, they contain compact and simple usage of OpenDAL C binding + From d0cecf8156a73fd7e653541826e6df874b4e1c73 Mon Sep 17 00:00:00 2001 From: Ji-Xinyou Date: Wed, 17 May 2023 21:04:57 +0800 Subject: [PATCH 3/7] done Signed-off-by: Ji-Xinyou --- bindings/c/CONTRIBUTING.md | 70 +++++++++++++++++++++++++++----------- 1 file changed, 50 insertions(+), 20 deletions(-) diff --git a/bindings/c/CONTRIBUTING.md b/bindings/c/CONTRIBUTING.md index b11cf295cc1b..47883b6d43e9 100644 --- a/bindings/c/CONTRIBUTING.md +++ b/bindings/c/CONTRIBUTING.md @@ -3,35 +3,40 @@ 1. [Setup](#setup) 1. [Using a dev container environment](#using-a-dev-container-environment) 2. [Bring your own toolbox](#bring-your-own-toolbox) - 2. [Prepare](#prepare) - 3. [Build](#build) - 4. [Test](#test) - 5. [Docs](#docs) + 2. [Build](#build) + 3. [Test](#test) + 4. [Docs](#docs) + 5. [Misc](#misc) ## Setup ### Using a dev container environment +OpenDAL provides a pre-configured [dev container](https://containers.dev/) that could be used in [Github Codespaces](https://github.com/features/codespaces), [VSCode](https://code.visualstudio.com/), [JetBrains](https://www.jetbrains.com/remote-development/gateway/), [JuptyerLab](https://jupyterlab.readthedocs.io/en/stable/). Please pick up your favourite runtime environment. + +The fastest way is: + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/apache/incubator-opendal?quickstart=1&machine=standardLinux32gb) ### Bring your own toolbox -To build OpenDAL C binding, the tools you need it very simple. -All you need is -- A C++ compiler that supports c++14 -- A Rust toolchain that satifies the MSRV -- (optional) if you want 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 - - 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. - -## Prepare +To build OpenDAL C binding, the tools you need are very simple. + +The following is all you need +- **A C++ compiler** that supports **c++14**, *e.g.* clang++ and g++ +- **A Rust toolchain** that satifies the MSRV +- **(optional)** if you want 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)** **GTest(Google Test)** need to be installed if you want to build the BDD (Behavior + Driven Development) tests. To see how to build, check [here](https://github.com/google/googletest). ## Build To build the library and header file. ```shell make build ``` -The header file `opendal.h` is under `./include` and the library is under `../../target/debug` after -building. + +- The header file `opendal.h` is under `./include` +- The library is under `../../target/debug` after building. To clean the build results. ```shell @@ -39,15 +44,40 @@ make clean ``` ## Test -To build and run the tests. +To build and run the tests. (Note that you need to install GTest) ```shell make test ``` +```text +[==========] Running 5 tests from 1 test suite. +[----------] Global test environment set-up. +[----------] 5 tests from OpendalBddTest +[ RUN ] OpendalBddTest.Write +[ OK ] OpendalBddTest.Write (4 ms) +[ RUN ] OpendalBddTest.Exist +[ OK ] OpendalBddTest.Exist (0 ms) +[ RUN ] OpendalBddTest.EntryMode +[ OK ] OpendalBddTest.EntryMode (0 ms) +[ RUN ] OpendalBddTest.ContentLength +[ OK ] OpendalBddTest.ContentLength (0 ms) +[ RUN ] OpendalBddTest.Read +[ OK ] OpendalBddTest.Read (0 ms) +[----------] 5 tests from OpendalBddTest (4 ms total) + +[----------] Global test environment tear-down +[==========] 5 tests from 1 test suite ran. (4 ms total) +[ PASSED ] 5 tests. +``` + ## Docs -The OpenDAL C binding currently do not have a documentation online(Open to contribution). -If you want to know more about the C binding, you may: +The OpenDAL C binding currently do not have an official documentation online(Open to contribution). + +If you want to know more about the OpenDAL C binding, you may: - Have a look at the comments inline with Rust codes under the `./src` or the comments in `opendal.h` - Have a look at the comments of the Rust core - Have a look at the test files, they contain compact and simple usage of OpenDAL C binding +## Misc +- We use `cbindgen` to generate the header file and library. If you want to contribute to the C binding core code, you may see the official [documentation](https://github.com/mozilla/cbindgen/blob/master/docs.md) of `cbindgen`. +- We have github action that shows how to setup the building and testing environment, if you are still not clear how to setup your environment, you may see [this github action](../../.github/workflows/bindings_c.yml). From d2d25519d384cd9a24b952f10a31cac6975be9c2 Mon Sep 17 00:00:00 2001 From: Ji-Xinyou Date: Wed, 17 May 2023 21:08:56 +0800 Subject: [PATCH 4/7] typo Signed-off-by: Ji-Xinyou --- bindings/c/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bindings/c/CONTRIBUTING.md b/bindings/c/CONTRIBUTING.md index 47883b6d43e9..7fd22afff658 100644 --- a/bindings/c/CONTRIBUTING.md +++ b/bindings/c/CONTRIBUTING.md @@ -22,7 +22,7 @@ To build OpenDAL C binding, the tools you need are very simple. The following is all you need - **A C++ compiler** that supports **c++14**, *e.g.* clang++ and g++ -- **A Rust toolchain** that satifies the MSRV +- **A Rust toolchain** that satisfies the MSRV - **(optional)** if you want 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. From 3cdce591caa65f3fd0333a0412fa3bbdc2923b7f Mon Sep 17 00:00:00 2001 From: Ji-Xinyou Date: Sun, 21 May 2023 15:20:46 +0800 Subject: [PATCH 5/7] fix --- .devcontainer/post_create.sh | 9 ++++++++ bindings/c/CONTRIBUTING.md | 41 ++++++++++++++++++++---------------- 2 files changed, 32 insertions(+), 18 deletions(-) diff --git a/.devcontainer/post_create.sh b/.devcontainer/post_create.sh index b645975955a3..01963e0accdc 100644 --- a/.devcontainer/post_create.sh +++ b/.devcontainer/post_create.sh @@ -36,3 +36,12 @@ corepack prepare yarn@stable --activate sudo apt install -y default-jdk echo "export JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:/bin/java::")" | sudo tee /etc/profile.d/java_home.sh sudo ln -s /usr/lib/jvm/default-java /usr/lib/jvm/default + +# Setup for C binding +sudo apt-get install libgtest-dev +cd /usr/src/gtest +sudo cmake CMakeLists.txt +sudo make +sudo cp lib/*.a /usr/lib +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 diff --git a/bindings/c/CONTRIBUTING.md b/bindings/c/CONTRIBUTING.md index 7fd22afff658..41d6beb00e95 100644 --- a/bindings/c/CONTRIBUTING.md +++ b/bindings/c/CONTRIBUTING.md @@ -18,16 +18,32 @@ The fastest way is: [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/apache/incubator-opendal?quickstart=1&machine=standardLinux32gb) ### Bring your own toolbox -To build OpenDAL C binding, the tools you need are very simple. - -The following is all you need +To build OpenDAL C binding, the following is all you need: - **A C++ compiler** that supports **c++14**, *e.g.* clang++ and g++ -- **A Rust toolchain** that satisfies the MSRV -- **(optional)** if you want to format the code, you need to install **clang-format** + +- 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)** **GTest(Google Test)** need to be installed if you want to build the BDD (Behavior - Driven Development) tests. To see how to build, check [here](https://github.com/google/googletest). + +- **GTest(Google Test)** need to be installed to build the BDD (Behavior Driven Development) tests. To see how to build, check [here](https://github.com/google/googletest). + +For Ubuntu and Debian: +```shell +# 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 +cd /usr/src/gtest +sudo cmake CMakeLists.txt +sudo make +sudo cp lib/*.a /usr/lib +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. @@ -70,14 +86,3 @@ make test [ PASSED ] 5 tests. ``` -## Docs -The OpenDAL C binding currently do not have an official documentation online(Open to contribution). - -If you want to know more about the OpenDAL C binding, you may: -- Have a look at the comments inline with Rust codes under the `./src` or the comments in `opendal.h` -- Have a look at the comments of the Rust core -- Have a look at the test files, they contain compact and simple usage of OpenDAL C binding - -## Misc -- We use `cbindgen` to generate the header file and library. If you want to contribute to the C binding core code, you may see the official [documentation](https://github.com/mozilla/cbindgen/blob/master/docs.md) of `cbindgen`. -- We have github action that shows how to setup the building and testing environment, if you are still not clear how to setup your environment, you may see [this github action](../../.github/workflows/bindings_c.yml). From c29c2ed4bcfa3a845d283426fbfb089220d979d9 Mon Sep 17 00:00:00 2001 From: Ji-Xinyou Date: Sun, 21 May 2023 15:30:01 +0800 Subject: [PATCH 6/7] fix Signed-off-by: Ji-Xinyou --- bindings/c/CONTRIBUTING.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/bindings/c/CONTRIBUTING.md b/bindings/c/CONTRIBUTING.md index 41d6beb00e95..549d78a8d8f0 100644 --- a/bindings/c/CONTRIBUTING.md +++ b/bindings/c/CONTRIBUTING.md @@ -1,12 +1,12 @@ # Contributing -1. [Contributing](#contributing) - 1. [Setup](#setup) - 1. [Using a dev container environment](#using-a-dev-container-environment) - 2. [Bring your own toolbox](#bring-your-own-toolbox) - 2. [Build](#build) - 3. [Test](#test) - 4. [Docs](#docs) - 5. [Misc](#misc) +- [Contributing](#contributing) + - [Setup](#setup) + - [Using a dev container environment](#using-a-dev-container-environment) + - [Bring your own toolbox](#bring-your-own-toolbox) + - [Build](#build) + - [Test](#test) + - [Docs](#docs) + - [Misc](#misc) ## Setup From 1a46355a18b8329488819ddf9a9503844f8308e1 Mon Sep 17 00:00:00 2001 From: Ji-Xinyou Date: Sun, 21 May 2023 17:31:19 +0800 Subject: [PATCH 7/7] fix --- .devcontainer/post_create.sh | 2 +- bindings/c/Makefile | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.devcontainer/post_create.sh b/.devcontainer/post_create.sh index 01963e0accdc..c9cbdff1735a 100644 --- a/.devcontainer/post_create.sh +++ b/.devcontainer/post_create.sh @@ -38,7 +38,7 @@ echo "export JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:/bin/java::")" | sud sudo ln -s /usr/lib/jvm/default-java /usr/lib/jvm/default # Setup for C binding -sudo apt-get install libgtest-dev +sudo apt install -y libgtest-dev cmake cd /usr/src/gtest sudo cmake CMakeLists.txt sudo make diff --git a/bindings/c/Makefile b/bindings/c/Makefile index a98899cbbe9f..7455cd7b9660 100644 --- a/bindings/c/Makefile +++ b/bindings/c/Makefile @@ -18,7 +18,7 @@ RPATH=$(PWD)/../../target/debug CXXFLAGS=-I./include -std=c++14 LDFLAGS=-L$(RPATH) -Wl,-rpath,$(RPATH) -LIBS=-lopendal_c -lgtest +LIBS=-lopendal_c -lgtest -lpthread OBJ_DIR=./build .PHONY: all