Skip to main content

Gear Examples

Gear provides a set of examples that can be used for your familiarization with writing programs on Gear or become the basis for your own dApp: https://github.com/gear-foundation.

You can write your own program or try to build from examples.

Stable environment​

All program examples and JS applications have been tested on a stable environment that consists of specific development tool versions necessary for implementing, building and running programs and JS applications.

You may configure a local development environment according to the information provided below or use a pre-configured Docker image as described in the Using Docker section.

Current stable release: v1.1.1

Compiler Tools                                    Version How to install / access

Linux users should generally install GCC and Clang, according to their distribution’s documentation.

Latest

For example, on Ubuntu use:

sudo apt install -y build-essential clang cmake

On macOS, you can get a compiler toolset by running:

xcode-select --install
Rust 2023-09-18
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Add Wasm target to your toolchain:

rustup toolchain add nightly
rustup target add wasm32-unknown-unknown --toolchain nightly

Gear Rust libraries: gstd, gtest, gmeta, gclient, gear-wasm-builder

v1.1.1

Make sure the correct version is tagged in the Cargo.toml file of the program you're working on. For example: https://github.com/gear-foundation/dapps/blob/master/contracts/Cargo.toml

Vara Network Testnet

1020

Make sure you are connected to the Vara Network Testnet. You may switch the network by clicking on the network name in the https://idea.gear-tech.io

Gear JS ToolsVersionHow to install / access
Gear JS API0.36.3Make sure this version is specified in the package.json file of your program repository
Gear JS React Hooks0.10.3Make sure this version is specified in the package.json file of your program repository
Gear JS UI Kit0.5.22Make sure this version is specified in the package.json file of your program repository
Note

Windows users may encounter some problems related to the installation of Rust components and dependencies. It is highly recommended to use Linux or macOS for compiling Gear node and programs.

Previous environment versions​

Gear node versionRuntime versionGear libraries versionRust toolchain version
v1.0.51050tag = "v1.0.5"nightly-2023-09-18
v1.0.21020tag = "v1.0.2"nightly-2023-10-14
v1.0.11010tag = "v1.0.1"nightly-2023-10-14
v1.0.01000tag = "v1.0.0"nightly-2023-04-25
v0.3.3330tag = "v0.3.3"nightly-2023-04-25
v0.2.2220rev = "946ac47"nightly-2023-04-25
v0.1.6160rev = "78dfa07"nightly-2023-04-25
v0.1.4140rev = "5c685d0"nightly-2023-03-14

First steps​

To create our app project use the command cargo:

cargo new gear-app --lib

The project structure is following:

  └── gear-app // Your programt dir
│
├── src // Source files of your program
│ ├── maybe_some_file.rs // Additional module if needed
│ └── lib.rs // Main file of your program
│
└── Cargo.toml // Manifest of your program

Create file build.rs with the following code:

fn main() {
gear_wasm_builder::build();
}

Cargo.toml is a project manifest in Rust, it contains all metadata necessary for compiling the project. Configure the Cargo.toml similarly to how it is configured dapp-template/Cargo.toml. You can refer to Getting Started for additional details.

Building Rust Program​

We should compile our program in the app folder:

cargo build --release

Our application should compile successfully and the final file target/wasm32-unknown-unknown/release/gear-app.wasm should appear.

Using Docker​

You can use a pre-configured Docker image to build and test your program. The image contains all the necessary tools and dependencies for building and running programs and JS applications.

The source code of the image is available on GitHub.

To use the image, you need to install Docker on your machine. You can find the installation instructions for your OS on the Docker website.

After installing Docker, you can pull the image from the Docker Hub:

docker pull ghcr.io/gear-foundation/gear-env:stable

To run the image, use the following command:

docker run --rm --name gear-env -itd ghcr.io/gear-foundation/gear-env:stable bash

The command will run the image in the background and give you access to the container's shell. You can use the following command to access the container's shell:

docker exec -it gear-env bash

Copy a program to be built to the container (Use the gear-app created above):

docker cp ./gear-app gear-env:/root

After that, you can build the program:

docker exec -itw /root/gear-app gear-env cargo build --release

The compiled program will be available in the target/wasm32-unknown-unknown/release folder inside the container. Copy it to your local machine:

docker cp gear-env:/root/gear-app/target/wasm32-unknown-unknown/release/. ./

Stop the Docker container after using:

docker stop gear-env