-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: expand user guide for basic setup
- Loading branch information
Showing
6 changed files
with
143 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,28 @@ | ||
# Creating schemas | ||
|
||
<!-- toc --> | ||
|
||
Basic types | ||
|
||
- Signed integers: `i8`, `i16`, `i32`, `i64` and `i128`. | ||
- Unsigned integers: `u8`, `u16`, `u32`, `u64` and `u128`. | ||
- Floating point numbers: `f32` and `f64`. | ||
- Strings: `string`. | ||
- Bytes: `bytes`. | ||
|
||
Colletions | ||
|
||
- Vectors: `vec<T>`. | ||
- Hash maps: `hash_map<K, V>`. | ||
- Hash sets: `hash_set<T>`. | ||
|
||
Special types | ||
|
||
- Optionals: `option<T>`. | ||
- Non-zero: `non_zero<T>`. | ||
- Boxed strings: `box<string`. | ||
- Boxed bytes: `box<bytes>`. | ||
|
||
```rust,ignore | ||
{{#include creating/basic.stef}} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
/// Basic user information. | ||
struct User { | ||
/// Full name of the user. | ||
name: string @1, | ||
/// Current age in years. | ||
age: u16 @2, | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,72 @@ | ||
# Generating code | ||
|
||
<!-- toc --> | ||
|
||
## Rust | ||
|
||
First, make sure you followed the [installation](./installation.md#rust) instructions, to setup the dependencies in your _Cargo.toml_ properly. | ||
|
||
The main entry point is the `stef-build` crate, which you use as build script in your `build.rs` file. A basic setup looks like this, assuming you have a single schema under `src/sample.stef`: | ||
|
||
```rust | ||
fn main() { | ||
stef_build::compile(&["src/sample.stef"], &["src/"]).unwrap(); | ||
} | ||
``` | ||
|
||
This will take care of reading and parsing the schema files, then generate the Rust code from them. The code is stored in your `target` folder in a folder specifically for build script output. | ||
|
||
In your code you then include the generated files with Rust's `include!` macro. The correct folder can be accessed through the `OUT_DIR` environment variable and combined with the right file name to get the correct path. | ||
|
||
Continuing on the previous example, the generated could could be included like this: | ||
|
||
```rust | ||
// in src/main.rs | ||
|
||
mod sample { | ||
include!(concat!(env!("OUT_DIR"), "/sample.rs")); | ||
} | ||
|
||
fn main() { | ||
println!("Hello, World!"); | ||
} | ||
``` | ||
|
||
The file name is the same as the input schema file name, but with `.rs` as file extension instead of `.stef`. The schema file `sample.stef` becomes `sample.rs`. | ||
|
||
### Using the code | ||
|
||
From that point on, the generated code can be used like regular Rust code. Extending the example a bit, let's say the schema file contained the following: | ||
|
||
```rust,ignore | ||
struct Sample { | ||
value: u32 @1, | ||
} | ||
``` | ||
|
||
Then we could use the generated struct as follows: | ||
|
||
```rust,ignore | ||
// Include stef's `Encode` trait to get access to the `encode()` method. | ||
use stef::Encode; | ||
mod sample { | ||
include!(concat!(env!("OUT_DIR"), "/sample.rs")); | ||
} | ||
fn main() { | ||
// Let's create an instance of your `Sample` struct. | ||
let value = sample::Sample { | ||
value: 5 | ||
}; | ||
// We can print it out like an Rust value that implements `Debug`: | ||
println!("{value:?}"); | ||
// Here we encode it into the wire format. | ||
// - byte 1 for the field identifier. | ||
// - byte 5 for the actual value. | ||
// - byte 0 to mark the end of the struct. | ||
assert_eq!(&[1, 5, 0], value.encode()); | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,38 @@ | ||
# Installation | ||
|
||
<!-- toc --> | ||
|
||
## Command Line Interface | ||
|
||
The CLI tool is not strictly needed to compile and use STEF schemas, but it contains several helpful elements like a validator for schema correctness, a formatter and helper for setting up STEF in your project. | ||
|
||
### From source | ||
|
||
Currently it can only be installed from source, using Cargo: | ||
|
||
```sh | ||
cargo install --git https://github.com/dnaka91/stef.git stef-cli | ||
``` | ||
|
||
## Rust | ||
|
||
For Rust projects, two crates are needed to work with STEF schemas and data. One is the `stef` crate for runtime support, which contains all components that are used by the generated code. | ||
|
||
The other one is the `stef-build` crate which generates the Rust code from schema files. It is used as [Build Script](https://doc.rust-lang.org/cargo/reference/build-scripts.html) usually in the _build.rs_ file of your project. | ||
|
||
You can use Cargo's [add](https://doc.rust-lang.org/cargo/commands/cargo-add.html) command to add those dependencies: | ||
|
||
```sh | ||
cargo add --git https://github.com/dnaka91/stef.git stef | ||
cargo add --git https://github.com/dnaka91/stef.git --build stef-build | ||
``` | ||
|
||
Or specify them in your _Cargo.toml_ manually: | ||
|
||
```toml | ||
[dependencies] | ||
stef = { git = "https://github.com/dnaka91/stef.git" } | ||
|
||
[build-dependencies] | ||
stef-build = { git = "https://github.com/dnaka91/stef.git" } | ||
``` |