This is an automated email from the ASF dual-hosted git repository.
xuanwo 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 cf8bb7527 docs: add rust usage example (#2447)
cf8bb7527 is described below
commit cf8bb7527113937a3ea3905970855fbd5548e210
Author: Flash <[email protected]>
AuthorDate: Mon Jun 12 18:45:23 2023 +0800
docs: add rust usage example (#2447)
* add rust usage example
* separate into different folders
* fix CI error
* make it to section01
* update
* update
---
Cargo.toml | 1 +
README.md | 2 +-
examples/rust/section01-introduction/.gitignore | 2 +
.../rust/section01-introduction/Cargo.toml | 38 ++++----------
examples/rust/section01-introduction/README.md | 49 ++++++++++++++++++
examples/rust/section01-introduction/src/main.rs | 58 ++++++++++++++++++++++
6 files changed, 121 insertions(+), 29 deletions(-)
diff --git a/Cargo.toml b/Cargo.toml
index 2addfb3d6..7f84c2152 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -20,6 +20,7 @@ debug = true
[workspace]
default-members = ["core"]
+exclude = ["examples"]
members = [
"core",
diff --git a/README.md b/README.md
index 6e188420a..62af4b0aa 100644
--- a/README.md
+++ b/README.md
@@ -98,7 +98,7 @@ Major components of the project include:
## Documentation
-The documentation is available at <https://opendal.apache.org>.
+The documentation is available at <https://opendal.apache.org>. Checkout
[here](./examples/) for the usage examples(still working on).
We are engaged in a practice we call "documentation as code". You can also
view the documentation directly in project's source code. And we welcome you to
contribute to the documentation.
diff --git a/examples/rust/section01-introduction/.gitignore
b/examples/rust/section01-introduction/.gitignore
new file mode 100644
index 000000000..eb68687a1
--- /dev/null
+++ b/examples/rust/section01-introduction/.gitignore
@@ -0,0 +1,2 @@
+/target
+/tmp
\ No newline at end of file
diff --git a/Cargo.toml b/examples/rust/section01-introduction/Cargo.toml
similarity index 59%
copy from Cargo.toml
copy to examples/rust/section01-introduction/Cargo.toml
index 2addfb3d6..7f09d4cec 100644
--- a/Cargo.toml
+++ b/examples/rust/section01-introduction/Cargo.toml
@@ -15,33 +15,15 @@
# specific language governing permissions and limitations
# under the License.
-[profile.bench]
-debug = true
-
-[workspace]
-default-members = ["core"]
-members = [
- "core",
-
- "bindings/c",
- "bindings/nodejs",
- "bindings/object_store",
- "bindings/python",
- "bindings/ruby",
- "bindings/java",
-
- "bin/oli",
- "bin/oay",
-]
-
-[workspace.package]
-authors = ["OpenDAL Contributors <[email protected]>"]
+[package]
+name = "section01-introduction"
+version = "0.1.0"
edition = "2021"
-homepage = "https://opendal.apache.org/";
-license = "Apache-2.0"
-repository = "https://github.com/apache/incubator-opendal";
-rust-version = "1.65"
-version = "0.37.0"
-[workspace.dependencies]
-opendal = { version = "0.37", path = "core" }
+# See more keys and their definitions at
https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+opendal = { version = "0.37.0" }
+tokio = { version = "1.27", features = ["full"] }
+anyhow = { version = "1.0.30", features = ["std"] }
+futures = { version = "0.3" }
\ No newline at end of file
diff --git a/examples/rust/section01-introduction/README.md
b/examples/rust/section01-introduction/README.md
new file mode 100644
index 000000000..33146096a
--- /dev/null
+++ b/examples/rust/section01-introduction/README.md
@@ -0,0 +1,49 @@
+# Introduction
+
+Rust is a systems programming language that is known for its performance,
memory safety, and concurrency features. OpenDAL(**Open D**ata **A**ccess
**L**ayer) is a Rust project to access data freely, painlessly and efficiently.
+
+This examples documentation is organized in a progressive manner, with each
section building upon the previous one. Each section is located in a different
folder and contains both documentation and a stand-alone project that can be
run independently.
+
+The following will briefly introduce dev environment set up, the Rust project
structure, some important files, and how to quickly create a project. This is
prepared for those who are not familiar with Rust. If you are familiar with
Rust, you can skip this section.
+
+
+# Environment set up
+
+There need rust toolchain in your local environment, if you haven't set it up,
you can refer
[here](https://github.com/apache/incubator-opendal/blob/main/CONTRIBUTING.md#bring-your-own-toolbox)
to figure it out.
+
+
+# Rust Project Structure
+
+A typical Rust project follows a specific directory structure. Here's an
overview of the main directories and files you'll encounter in a Rust project:
+
+- src/: This directory contains the source code for your Rust project. It
typically includes a main.rs file, which is the entry point for your
application.
+
+- Cargo.toml: This file contains metadata about your project, such as its
name, version, and dependencies. It also specifies the build configuration for
your project.
+
+## Cargo.toml
+
+Cargo is Rust's package manager and build tool. It uses the Cargo.toml file to
manage dependencies and build configurations for your project.
+
+Here's an example Cargo.toml file for a Rust project:
+
+```toml
+[package]
+name = "my_project"
+version = "0.1.0"
+authors = ["Your Name <[email protected]>"]
+edition = "2018"
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+```
+## main.rs
+The main.rs file is the entry point for your Rust application. It typically
contains the `main()` function, which is the starting point for your program.
+
+
+# Basic Usage
+
+In this section, we chose `Fs` service as example because it is simple and
don't need extra work to set up, all service available can be found
[here](https://docs.rs/opendal/latest/opendal/services/index.html).
+
+This is a independent project, the `src/main.rs` provide a example usage about
`Fs`. It `read` a file and print its content to console, overwrite some new
content to it and read & print content again to verify the `write` operator has
been taken effect and then delete the file.
+
+Use `cargo run` to run this project. Just take a try.
\ No newline at end of file
diff --git a/examples/rust/section01-introduction/src/main.rs
b/examples/rust/section01-introduction/src/main.rs
new file mode 100644
index 000000000..9fb0534fc
--- /dev/null
+++ b/examples/rust/section01-introduction/src/main.rs
@@ -0,0 +1,58 @@
+// 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.
+
+use opendal::Operator;
+use opendal::Result;
+use opendal::services::Fs;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+
+ // Create fs backend builder.
+ let mut builder = Fs::default();
+
+ // set the root to `section01-introduction/tmp`, all operations will
happen under this root.
+ // note that the root must be absolute path.
+ let mut path = std::env::current_dir().unwrap();
+ path.push("tmp");
+ builder.root(path.to_str().unwrap());
+
+ // create an `Operator` from `builder`, all file operations are initiated
from it.
+ let op: Operator = Operator::new(builder)?.finish();
+
+ // if the 'root' path haven't been set, then the `file_path` below should
be `section01-introduction/tmp/1.txt`.
+ let file_path = "1.txt";
+ op.write(file_path, "This is OpenDAL usage documentation
section01-introduction.").await?;
+
+ // read the file and print its content.
+ let read_file = op.read(file_path).await?;
+ let content = String::from_utf8(read_file).unwrap();
+ println!("{}", content);
+
+ // write the file.
+ op.write(file_path, "File content has been overwrite.").await?;
+
+ // verify the file content after the write operator.
+ let read_file = op.read(file_path).await?;
+ let content = String::from_utf8(read_file).unwrap();
+ println!("{}", content);
+
+ // delete the file.
+ op.delete(file_path).await?;
+
+ Ok(())
+}
\ No newline at end of file
