You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2023/06/13 08:29:24 UTC

[incubator-opendal] 01/01: docs: Polish rust examples

This is an automated email from the ASF dual-hosted git repository.

xuanwo pushed a commit to branch polish-example
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git

commit b5c048ba1a87b3a08cf85acdabd7d0b74a79e96f
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Tue Jun 13 16:29:03 2023 +0800

    docs: Polish rust examples
    
    Signed-off-by: Xuanwo <gi...@xuanwo.io>
---
 .../Cargo.toml => .github/workflows/examples.yml   | 35 +++++---
 README.md                                          | 10 ++-
 examples/README.md                                 |  9 ++
 examples/rust/00-setup/.gitignore                  |  2 +
 examples/rust/00-setup/Cargo.toml                  | 19 +++++
 examples/rust/00-setup/README.md                   | 98 ++++++++++++++++++++++
 examples/rust/00-setup/src/main.rs                 |  5 ++
 examples/rust/README.md                            | 15 ++++
 examples/rust/section01-introduction/.gitignore    |  2 -
 examples/rust/section01-introduction/README.md     | 49 -----------
 examples/rust/section01-introduction/src/main.rs   | 58 -------------
 licenserc.toml                                     |  3 +
 12 files changed, 182 insertions(+), 123 deletions(-)

diff --git a/examples/rust/section01-introduction/Cargo.toml b/.github/workflows/examples.yml
similarity index 59%
rename from examples/rust/section01-introduction/Cargo.toml
rename to .github/workflows/examples.yml
index 7f09d4cec..41ce62ff2 100644
--- a/examples/rust/section01-introduction/Cargo.toml
+++ b/.github/workflows/examples.yml
@@ -15,15 +15,30 @@
 # specific language governing permissions and limitations
 # under the License.
 
-[package]
-name = "section01-introduction"
-version = "0.1.0"
-edition = "2021"
+name: Examples
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "examples/**"
 
-[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
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+jobs:
+  rust-00-setup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Rust toolchain
+        uses: ./.github/actions/setup
+      - name: Test
+        shell: bash
+        working-directory: examples/rust/00-setup
+        run: cargo run
diff --git a/README.md b/README.md
index 62af4b0aa..8e6875795 100644
--- a/README.md
+++ b/README.md
@@ -96,11 +96,13 @@ Major components of the project include:
 
 > Welcome to add any services that are not currently supported [here](https://github.com/apache/incubator-opendal/issues/5).
 
-## Documentation
+## Examples
+
+The examples is available at [here](./examples/).
 
-The documentation is available at <https://opendal.apache.org>. Checkout [here](./examples/) for the usage examples(still working on).
+## Documentation
 
-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.
+The documentation is available at <https://opendal.apache.org>.
 
 ## Contribute
 
@@ -108,9 +110,9 @@ OpenDAL is an active open-source project. We are always open to people who want
 
 - Start with [Contributing Guide](CONTRIBUTING.md).
 - Submit [Issues](https://github.com/apache/incubator-opendal/issues/new) for bug report or feature requests.
+- Discuss at [dev mailing list](mailto:dev-subscribe@opendal.apache.org) ([subscribe](mailto:dev-subscribe@opendal.apache.org?subject=(send%20this%20email%20to%20subscribe)) / [unsubscribe](mailto:dev-unsubscribe@opendal.apache.org?subject=(send%20this%20email%20to%20unsubscribe)) / [archives](https://lists.apache.org/list.html?dev@opendal.apache.org))
 - Asking questions in the [Discussions](https://github.com/apache/incubator-opendal/discussions/new?category=q-a).
 - Talk to community directly at [Discord](https://discord.gg/XQy8yGR2dg).
-- [Subscribe our dev mailing list](mailto:dev-subscribe@opendal.apache.org), then you can use it to ask questions, discuss design and implementation, etc. View the archive at <ht...@opendal.apache.org>.
 
 ## Who is using OpenDAL?
 
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 000000000..f1c0b202f
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,9 @@
+# OpenDAL Examples
+
+Thank you for using OpenDAL!
+
+The goal of these documents is to provide you with everything you need to start using OpenDAL. We will provide examples in different languages, starting with the basics and moving on to more specifics. We hope you have a good time here! Please raise issues if there is anything you don't understand, it must be our fault!
+
+## Examples
+
+- [Rust](rust/README.md)
diff --git a/examples/rust/00-setup/.gitignore b/examples/rust/00-setup/.gitignore
new file mode 100644
index 000000000..2c96eb1b6
--- /dev/null
+++ b/examples/rust/00-setup/.gitignore
@@ -0,0 +1,2 @@
+target/
+Cargo.lock
diff --git a/examples/rust/00-setup/Cargo.toml b/examples/rust/00-setup/Cargo.toml
new file mode 100644
index 000000000..3aa6083ae
--- /dev/null
+++ b/examples/rust/00-setup/Cargo.toml
@@ -0,0 +1,19 @@
+[package]
+# name for this package
+name = "setup"
+# edition is the rust edition that used to complie this package.
+# We will not discuss about this a lot, use `2021` is a good choice.
+#
+# For more information: <https://doc.rust-lang.org/edition-guide/editions/>
+edition = "2021"
+# version is the semver for this pacakge.
+# We will not publish this package publicly, so the version is leave AS-IS.
+version = "0.1.0"
+
+# In this example, we are depending on two crates (packages): `futures` and `opendal`
+[dependencies]
+futures = "0.3"
+# The `0.37` is the semver version of opendal.
+#
+# We use `0.37` to indicate all versions that `>=0.37.0 && <0.38.0`.
+opendal = "0.37"
diff --git a/examples/rust/00-setup/README.md b/examples/rust/00-setup/README.md
new file mode 100644
index 000000000..4e928aba5
--- /dev/null
+++ b/examples/rust/00-setup/README.md
@@ -0,0 +1,98 @@
+# Chapter-00: Setup Your First Rust Project
+
+Welcome to our first chapter. In this example we will setup our first rust project with OpenDAL.
+
+## Install Rust
+
+First of all, we need to install Rust. Refer [here](../../../CONTRIBUTING.md#bring-your-own-toolbox) to figure it out.
+
+After rust has been installed, we will have the following components:
+
+- `rustup`: [rustup](https://rust-lang.github.io/rustup/) is a command-line toolchain manager for the Rust programming language. It allows you to easily install, manage, and update different versions of the Rust compiler and associated tools on your system.
+- `cargo`: [cargo](https://doc.rust-lang.org/cargo/index.html) is the package manager and build system for the Rust programming language. It is designed to make it easy to develop, build, and manage Rust projects.
+- `rustc`: [rustc](https://rustc-dev-guide.rust-lang.org/) is the official compiler for the Rust programming language. It takes Rust source code as input and translates it into machine-readable instructions that can be executed by the computer's hardware. Most of time, `rustc` will be called by `cargo` and we don't need to use it directly.
+
+We can use `cargo --version` to check if it works as expected:
+
+```shell
+> cargo --version
+cargo 1.70.0 (ec8a8a0ca 2023-04-25)
+```
+
+## Rust Project Structure
+
+A typical Rust project follows a specific directory structure. The most simple project structure will contain the following files:
+
+- `Cargo.toml`: The Cargo.toml file is the manifest file for the project. It specifies metadata about the project, including its name, version, dependencies, and build configuration. It is also where you declare the project's dependencies using the Cargo package manager.
+- `src/`: The `src` directory is where the main source code files of the project reside. It typically contains the Rust source files with the code implementation for the project's functionality.
+
+Let's go into more deep by our example code.
+
+### `Cargo.toml`
+
+Let's take a look over [`Cargo.toml`](Cargo.toml) first.
+
+The most simple `Cargo.toml` will contains two parts:
+
+- `package`: The metadata of this package like `name`, `version`
+- `dependencies`: The dependencies that this package will depend on. `cargo` will download them from <https://crates.io> and compile them.
+
+### `src/`
+
+Than, let's read [`main.rs`](./src/main.rs).
+
+The most simple `main.rs` will contain only one function: `fn main()`, this is the entry of an application.
+
+In our example, we did the following things:
+
+```rust
+use opendal::Scheme;
+```
+
+Import the `opendal::Scheme` into current namespace, so that we can use `Scheme` instead of the full naming `opendal::Scheme` everywhere.
+
+``` rust
+fn main() {
+    ...
+}
+```
+
+Declare our main function, this is the most simple function that not take any input and not return any output.
+
+```rust
+println!("Hello, {}", Scheme::S3)
+```
+
+- `println!()` is a built macro in rust to prints to the standard output, with a newline. macro will be expanded to real code during compilation.
+- `"Hello, {}", Scheme::S3` is the format string in rust. It will convert `Scheme::S3` to string, and construct a new string in this format.
+
+## Build our first rust project!
+
+Now, it's time to build our first rust project!
+
+Make sure we are under folder `examples/rust/00-setup`, running:
+
+```shell
+cargo run
+```
+
+We will see output like:
+
+```shell
+:) cargo run
+   Compiling setup v0.1.0 (/home/xuanwo/Code/apache/incubator-opendal/examples/rust/00-setup)
+    Finished dev [unoptimized + debuginfo] target(s) in 0.32s
+     Running `target/debug/setup`
+Hello, s3
+```
+
+Congrate! Our first rust project is built and running with success!
+
+After built, we will find that there are some new files created:
+
+- `Cargo.lock`: Cargo.lock is a file generated by the cargo package manager when you build or run a Rust project. It serves as a lock file and records the exact versions of dependencies that were used during the previous successful build or run of the project. It's always a good idea to commit `Cargo.lock` to your repo, so developers can reproduce the same build result with you.
+- `target`: `target` folder is a directory automatically generated by rustc  and managed cargo. It contains the compiled artifacts and build output for specific target platforms and architectures.
+
+## Conclusion
+
+In this chapter we have learnt the rust project structure and run our first rust example. We will use this knowledge to build our first rust application in the next chapter!
diff --git a/examples/rust/00-setup/src/main.rs b/examples/rust/00-setup/src/main.rs
new file mode 100644
index 000000000..626a518c3
--- /dev/null
+++ b/examples/rust/00-setup/src/main.rs
@@ -0,0 +1,5 @@
+use opendal::Scheme;
+
+fn main() {
+    println!("Hello, {}", Scheme::S3)
+}
diff --git a/examples/rust/README.md b/examples/rust/README.md
new file mode 100644
index 000000000..40a1ff2d5
--- /dev/null
+++ b/examples/rust/README.md
@@ -0,0 +1,15 @@
+# OpenDAL Rust Examples
+
+Thank you for using OpenDAL Rust Core!
+
+The goal of these documents is to give you everything you need to start using OpenDAL Rust Core. We will start with the Rust basics and move on to more OpenDAL features. After reading and using all these examples, we hope you will become a master of OpenDAL and empowered to build your bravo applications!
+
+## Layout
+
+Our examples are organised like a book with different chapters.
+
+It's a good idea to start reading from the first chapter. It's also ok to pick the topics that interest you the most. Each chapter will be a separate project that can be run and referenced.
+
+## Contents
+
+- [Chapter-00: Setup Your First Rust Project](./00-setup/README.md)
diff --git a/examples/rust/section01-introduction/.gitignore b/examples/rust/section01-introduction/.gitignore
deleted file mode 100644
index eb68687a1..000000000
--- a/examples/rust/section01-introduction/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-/target
-/tmp
\ No newline at end of file
diff --git a/examples/rust/section01-introduction/README.md b/examples/rust/section01-introduction/README.md
deleted file mode 100644
index 33146096a..000000000
--- a/examples/rust/section01-introduction/README.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# 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 <yo...@example.com>"]
-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
deleted file mode 100644
index 9fb0534fc..000000000
--- a/examples/rust/section01-introduction/src/main.rs
+++ /dev/null
@@ -1,58 +0,0 @@
-// 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
diff --git a/licenserc.toml b/licenserc.toml
index d1d1ed824..e3a939cba 100644
--- a/licenserc.toml
+++ b/licenserc.toml
@@ -18,6 +18,9 @@
 headerPath = "Apache-2.0-ASF.txt"
 
 excludes = [
+  # Examples are served as public domain content.
+  "examples",
+
   # Well known generated files
   "**/Cargo.lock",
   "**/yarn.lock",