diff --git a/Cargo.toml b/Cargo.toml index 2addfb3d646..7f84c21526d 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 6e188420a00..62af4b0aada 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ Major components of the project include: ## Documentation -The documentation is available at . +The documentation is available at . 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 00000000000..eb68687a14c --- /dev/null +++ b/examples/rust/section01-introduction/.gitignore @@ -0,0 +1,2 @@ +/target +/tmp \ No newline at end of file diff --git a/examples/rust/section01-introduction/Cargo.toml b/examples/rust/section01-introduction/Cargo.toml new file mode 100644 index 00000000000..7f09d4ceca5 --- /dev/null +++ b/examples/rust/section01-introduction/Cargo.toml @@ -0,0 +1,29 @@ +# 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. + +[package] +name = "section01-introduction" +version = "0.1.0" +edition = "2021" + +# 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 00000000000..33146096ad3 --- /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 "] +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 00000000000..9fb0534fc20 --- /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