docs(book): complete missing docs for the MVP (#65)

* docs(benchmarks): introduce fibonacci recursion example * docs(tutorial): overall instructions for creating zink project * docs(cli): guide for zinkc * docs(styles): current status and future plans * docs(compiler): details of the layout of calls * docs(compiler): introduce description for local variables * docs(examples): copy-paste examples lol * docs(stability): note for v0.1.0 * docs(benchmarks): add summary for the benchmark chapter * docs(contributing): introduce section contributing * docs(appendix): introduce appendix and pack READMEs * docs(README): add code snippet for fibonacci * chore(README): short guide for installation * docs(README): highlight for the example
zink-lang · Aug 4, 2023 · e0ddc20 · e0ddc20
1 parent 1622dfd
commit e0ddc20
Show file tree

Hide file tree

Showing 42 changed files with 715 additions and 138 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
+.log
 **/*target
 docs/book
diff --git a/README.md b/README.md
@@ -1,14 +1,14 @@
-# Zink 
+# Zink
 
 > This project is still under development, plz DO NOT use it in production.
 
 [![zink][version-badge]][version-link]
 [![ci][ci-badge]][ci-link]
-[![telegram][telegram-badge]][telegram-group] 
+[![telegram][telegram-badge]][telegram-group]
 
-The Zink project mainly provides an optimizing compiler `zinkc` which can compile WASM 
-to the EVM bytecode with optimizations, the source code of your smart contract could be 
-any language you like! 
+[The Zink project][book] mainly provides a singlepass compiler `zinkc` which compiles
+WASM to EVM bytecode, the source code of your smart contract could be any language you
+like!
 
 ```mermaid
 flowchart LR
@@ -18,33 +18,61 @@ flowchart LR
     Z --> V[(EVM)]
 ```
 
+Run `cargo install zinkup` to install the toolchain!
+
+## Fibonacci Example
+
+| fib(n) | Zink | Solidity@0.8.21 |
+| ------ | ---- | --------------- |
+| 0      | 110  | 605             |
+| 1      | 110  | 605             |
+| 2      | 262  | 3636            |
+| 3      | 414  | 6667            |
+| 4      | 718  | 12729           |
+| 5      | 1174 | 21822           |
+
+```rust
+/// Calculates the nth fibonacci number using recursion.
+#[no_mangle]
+pub extern "C" fn recursion(n: usize) -> usize {
+    if n < 2 {
+        n
+    } else {
+        recursion(n - 1) + recursion(n - 2)
+    }
+}
+```
+
+As an example for the benchmark, calculating fibonacci sequence with recursion, missed
+vyper because it doesn't support recursion...
+
 ## Features
 
-Here we highly recommand you to choose `rust` as the language of your smart contracts 
+Here we highly recommand you to choose `rust` as the language of your smart contracts
 which will unlock all of the following features:
 
-- **Safe**: `rustc` is wathcing you! Furthermore, after compiling your rust code into WASM, 
-`zinkc` will precompute all of the stack and memory usages in your contracts to ensure they
-are safe in EVM bytecode as well!
-
-- **High Performance**: The optimizations are provided by the three of `rustc`, `wasm-opt` 
-and `zinkc`, your contracts will have the smallest size with **strong performance** in EVM 
-bytecode at the end! More details plz check [Optimizations](./docs/optimizations.md).
+- **Safe**: `rustc` is wathcing you! Furthermore, after compiling your rust code into WASM,
+  `zinkc` will precompute all of the stack and memory usages in your contracts to ensure they
+  are safe in EVM bytecode as well!
 
-- **Compatible**: All of the `no_std` libraries in rust are your libraries, futhermore, you 
-can use your solidity contracts as part of your zink contracts and your zink contracts as 
-part of your solidty contracts :)
+- **High Performance**: The optimizations are provided by the three of `rustc`, `wasm-opt`
+  and `zinkc`, your contracts will have the smallest size with **strong performance** in EVM
+  bytecode at the end!
 
-- **Easy Debugging**: Developing your smart contracts with only one programming language! 
-zink will provide everything you need for developing your contracts officially based on the 
-stable projects in rust like the `foundry` tools.
+- **Compatible**: All of the `no_std` libraries in rust are your libraries, futhermore, you
+  can use your solidity contracts as part of your zink contracts and your zink contracts as
+  part of your solidty contracts :)
 
+- **Easy Debugging**: Developing your smart contracts with only one programming language!
+  zink will provide everything you need for developing your contracts officially based on the
+  stable projects in rust like the `foundry` tools.
 
 ## LICENSE
 
 GPL-3.0-only
 
-[telegram-badge]: https://img.shields.io/badge/telegram-blue?logo=telegram 
+[book]: https://docs.zink-lang.org/
+[telegram-badge]: https://img.shields.io/badge/telegram-blue?logo=telegram
 [telegram-group]: https://t.me/+6oZpbwxlVD81OGQ1
 [version-badge]: https://img.shields.io/crates/v/zink
 [version-link]: https://docs.rs/zink/latest/zink/

diff --git a/cli/README.md b/cli/README.md
@@ -1,42 +1,25 @@
 # `zinkup`
 
-```
+The zink components are gathered here, you can install all of the
+components directly with:
+
+```bash
 cargo install zinkup
 ```
 
-## Binary `elko`
-
-``` shell
-elko
-Zink's package manager
-
-Usage: elko [OPTIONS] <COMMAND>
-
-Commands:
-  new    Create a new zink project
-  build  Build zink project to EVM bytecode
-  help   Print this message or the help of the given subcommand(s)
+For installing only specified binaries:
 
-Options:
-  -v, --verbose...  Verbose mode (-v, -vv, -vvv, etc.)
-  -h, --help        Print help
-  -V, --version     Print version
+```bash
+cargo install zinkup --features elko,zinkc
 ```
 
+Available binaries:
 
-## Binary `zinkc`
+| Name    | Description             |
+| ------- | ----------------------- |
+| `elko`  | Zink\'s package manager |
+| `zinkc` | The zink compiler       |
 
-```
-Zink Compiler
-
-Usage: zinkc [OPTIONS] <INPUT>
+## LICENSE
 
-Arguments:
-  <INPUT>  The path of the wasm file
-
-Options:
-  -o, --output <OUTPUT>  Write output to <filename>
-  -v, --verbose...       Verbose mode (-v, -vv, -vvv, etc.)
-  -h, --help             Print help
-  -V, --version          Print version
-```
+GPL-3.0
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -1,21 +1,30 @@
 # Summary
 
 - [Introduction](./introduction.md)
-- [Tutorial](./tutorial.md)
+- [Tutorial](./tutorial/README.md)
   - [Creating Zink Project](./tutorial/create-zink-project.md)
   - [Compiling Zink Project](./tutorial/compile-zink-project.md)
-- [Examples](./examples.md)
-- [Command Line Tool](./cli.md)
+- [Examples](./examples/README.md)
+  - [AddTwo](./examples/add-two.md)
+  - [Fibonacci](./examples/fibonacci.md)
+- [Command Line Tool](./cli/README.md)
   - [elko](./cli/elko.md)
+  - [zinkc](./cli/zinkc.md)
+- [Styles](./styles/README.md)
 - [Compiler](./compiler/README.md)
   - [Arithmetic](./compiler/arithmetic.md)
   - [Calls](./compiler/calls.md)
   - [Control Flow](./compiler/control-flow.md)
   - [Locals](./compiler/locals.md)
   - [Recursion](./compiler/recursion.md)
-- [Stability](./stability.md)
+- [Stability](./stability/README.md)
+  - [v0.1.0](./stability/v0.1.0.md)
 - [Security](./security.md)
-- [Benchmarks](./benchmarks.md)
-- [Contributing](./contributing.md)
+- [Benchmarks](./benchmarks/README.md)
+  - [Fibonacci](./benchmarks/fibonacci.md)
+- [Contributing](./contributing/README.md)
+  - [Architecture](./contributing/architecture.md)
+  - [Building](./contributing/building.md)
+  - [Testing](./contributing/testing.md)
 - [Appendix](./appendix/README.md)
-  - [A - Operators](./appendix/operators.md)
+  - [A - Optimizations](./appendix/optimizations.md)
diff --git a/docs/appendix/README.md b/docs/appendix/README.md
@@ -1 +1,4 @@
 # Appendix
+
+The following sections contain reference material you may find useful
+in your Zink journey.
diff --git a/docs/appendix/operators.md b/docs/appendix/operators.md
diff --git a/docs/appendix/optimizations.md b/docs/appendix/optimizations.md
@@ -0,0 +1,7 @@
+# A - Optimizations
+
+The optimizations of Zink projects now are mainly benifited from
+the optimizer of wasm -- `wasm-opt`, for the details of it please
+check [Binary Optimizations][binaryen-optimizations].
+
+[binaryen-optimizations]: https://github.com/WebAssembly/binaryen#binaryen-optimizations
diff --git a/docs/benchmarks.md b/docs/benchmarks.md
diff --git a/docs/benchmarks/README.md b/docs/benchmarks/README.md
@@ -0,0 +1,10 @@
+# Benchmarks
+
+This chapter terms to record the benchmarks of zink projects comparing
+with `solidity` and `vyper`.
+
+We are not going to compare with `yul` or `huff` since we are on different
+level, however, if zink is even faster than `yul` or `huff` in some cases,
+don't be suprised, we are born with high performance.
+
+- [Fibonacci](/benchmarks/fibonacci.md)
diff --git a/docs/benchmarks/fibonacci.md b/docs/benchmarks/fibonacci.md
@@ -0,0 +1,47 @@
+# Fibonacci
+
+Benchmarks for fibonacci.
+
+## Recursion
+
+| fib(n) | Zink | Solidity@0.8.21 |
+| ------ | ---- | --------------- |
+| 0      | 110  | 605             |
+| 1      | 110  | 605             |
+| 2      | 262  | 3636            |
+| 3      | 414  | 6667            |
+| 4      | 718  | 12729           |
+| 5      | 1174 | 21822           |
+
+`zink` implementation in rust:
+
+```rust
+//! Zink fibonacci recursion
+
+#[no_mangle]
+pub extern "C" fn fib(n: usize) -> usize {
+    if n < 2 {
+        n
+    } else {
+        recursion(n - 1) + recursion(n - 2)
+    }
+}
+```
+
+`solidity` implementation:
+
+```sol
+/**
+ * Solidity fibonacci recursion
+ **/
+
+function fib(uint n) public view returns (uint) {
+  if (n <= 1) {
+    return n;
+  } else {
+    return this.fib(n - 1) + this.fib(n - 2);
+  }
+}
+```
+
+Vyper is not included since it doesn't support cyclic function call :(
diff --git a/docs/cli.md b/docs/cli.md
diff --git a/docs/cli/README.md b/docs/cli/README.md
@@ -0,0 +1,24 @@
+# Command Line Tool
+
+The zink toolchain are gathered in [zinkup][zinkup]
+
+You can install all of the components directly with:
+
+```bash
+cargo install zinkup
+```
+
+For installing only specified binaries:
+
+```bash
+cargo install zinkup --features elko,zinkc
+```
+
+Available binaries:
+
+| Name    | Description             |
+| ------- | ----------------------- |
+| `elko`  | Zink\'s package manager |
+| `zinkc` | The zink compiler       |
+
+[zinkup]: https://crates.io/crates/zinkup
diff --git a/docs/cli/elko.md b/docs/cli/elko.md
@@ -1,10 +1,9 @@
 # `elko` - Zink's package manager
 
-
 ## Installation
 
 ```bash
-cargo install zinkup
+cargo install zinkup --features elko
 ```
 
 ## Usages

diff --git a/docs/cli/zinkc.md b/docs/cli/zinkc.md
@@ -0,0 +1,24 @@
+# The zink compiler
+
+## Installation
+
+```
+cargo install zinkup --features zinkc
+```
+
+## Usage
+
+```bash
+The Zink Compiler
+
+Usage: zinkc [OPTIONS] <INPUT>
+
+Arguments:
+  <INPUT>  The path of the wasm file
+
+Options:
+  -o, --output <OUTPUT>  Write output to <filename>
+  -v, --verbose...       Verbose mode (-v, -vv, -vvv, etc.)
+  -h, --help             Print help
+  -V, --version          Print version
+```
diff --git a/docs/compiler/README.md b/docs/compiler/README.md
@@ -1 +1,10 @@
 # Compiler
+
+The chapter illustrates the design of the zink compiler, so mostly,
+we are talking about `wat` and EVM bytecode `Mnemonic` here:
+
+- [Arithmetic](./arithmetic.md)
+- [Calls](./calls.md)
+- [Control Flow](./control-flow.md)
+- [Locals](./locals.md)
+- [Recursion](./recursion.md)