Introduction

Here we collect the information helping Rust developers deal with the Gear protocol internals.

Disclaimer

The information provided here is not a part of the official documentation and is not guaranteed to be up-to-date. It is provided as-is and is not covered by any support. Use it at your own risk.

Architechture overview

flowchart TB
    gear-cli-->vara-runtime
    vara-runtime-->pallets
    subgraph pallets
        pallet-gear
        pallet-gear-bank
        pallet-gear-gas
        pallet-gear-messenger
        pallet-gear-program
        pallet-gear-payment
        pallet-gear-scheduler
        pallet-gear-staking-rewards
        pallet-gear-voucher
    end

🚧 To be added soon.

Block production

🚧 To be added soon.

Wasm code instrumentation

🚧 To be added soon.

Wasm executors

🚧 To be added soon.

Gas tree

🚧 To be added soon.

Lazy pages

🚧 To be added soon.

Benchmarking

🚧 To be added soon.

Async-await in programs

🚧 To be added soon.

Accelerate the Gear node building

Using `sccache`

Using sccache configured with AWS S3 allows decreasing build time.

Install `sccache`

macOS:

brew install sccache

Add S3 config

We consider we have already configured AWS S3 storage with the following settings:

Region: us-west-1
Bucket: gear-sccache
Access key ID: <AWS_KEY_ID>
Secret access key: <AWS_SECRET_KEY>

We will use environment variables added to the profile file. For example, if using zsh, we need to add the following to the ~/.zshrc:

export SCCACHE_BUCKET=gear-sccache
export SCCACHE_REGION=us-west-1
export SCCACHE_S3_KEY_PREFIX=gear
export AWS_ACCESS_KEY_ID=<AWS_KEY_ID>
export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_KEY>"

Run to apply these settings immediately:

source ~/.zshrc

Build Gear node using `sccache`

We need to set the RUSTC_WRAPPER environment variable to sccache. Also, we need to set CARGO_INCREMENTAL to 0 as sccache doesn't work well when using incremental building. We can set these environment variables by prepending the cargo command in the shell:

cd gear

# Debug build:
RUSTC_WRAPPER=sccache CARGO_INCREMENTAL=0 cargo b

# Release build:
RUSTC_WRAPPER=sccache CARGO_INCREMENTAL=0 cargo b -r

Using `mold/sold`

mold is the linker that uses multiple CPU cores when linking.

Install `mold/sold`

macOS

As mold doesn't support macOS we need to build sold manually.

git clone https://github.com/bluewhalesystems/sold.git
mkdir sold/build
cd sold/build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=c++ ..
cmake --build . -j $(sysctl -n hw.ncpu)
sudo cmake --build . --target install

Configure `cargo` to use `mold/sold`

To use mold/sold with Rust, create (or update) .cargo/config.toml at your home directory with the following:

# macOS on M-series:
[target.aarch64-apple-darwin]
rustflags = ["-C", "link-arg=--ld-path=/usr/local/bin/ld64.sold"]

Then just run cargo b [-r] as usually.

Using prebuilt `librocksdb.a`

You can use prebuilt static library for the librocksdb-sys crate to avoid rebuilding it everytime from C++ sources.

The example below is for macOS:

Build the librocksdb-sys crate in the release profile:
```
cargo b -rp librocksdb-sys
```

Find the librocksdb.a file in the target directory:

find target -name librocksdb.a
# -> target/release/build/librocksdb-sys-a0a228694895e8fd/out/librocksdb.a

Copy librocksdb.a to some permanent directory:

mkdir -p ~/lib
cp -fv path/to/librocksdb.a ~/lib/

Install bzip2:
```
brew install bzip2
```

Set environment variables:

export ROCKSDB_STATIC=1
export ROCKSDB_LIB_DIR=~/lib
export CARGO_TARGET_AARCH64_APPLE_DARWIN_RUSTFLAGS="-Clink-arg=-L/opt/homebrew/opt/bzip2/lib -Clink-arg=-lbz2"

Now the librocksdb-sys crate building will be mush faster.

Avoid rebuilding examples before pallet tests

Set the __GEAR_WASM_BUILDER_NO_FEATURES_TRACKING environment variable to 1:

export __GEAR_WASM_BUILDER_NO_FEATURES_TRACKING=1
cargo t -p pallet-gear

Referendum starting

🚧 To be added soon.

Gear for Rustaceans