The following conditions need to be fulfilled before setting up a Rust-CDK IC project:
dfx
installedNode.js
installed (optional)ic-cdk-optimizer
utility installedcmake
installed.To setup our project:
dfx new --type=rust fyp
This will generate a folder named fyp
in the current directory and create the project files. We sometimes met some network issues at the steps related to npm install
, If this happens, ctrl+C
to cancel the process and try these later:
cd fyp
npm install
When the setup complete, we can get the following output:
===============================================================================
Welcome to the internet computer developer community!
You're using dfx 0.11.1
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▄▄▀▀▀▀▀▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▀▀▀▀▀▀▄▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ ▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄ ▀▄▄▄▄▄▄▄▄▄▄▄▄▀ ▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄
▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▀
▀▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄
▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀
▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀ ▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀▀ ▀▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀
▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀▀
To learn more before you start coding, see the documentation available online:
- Quick Start: https://internetcomputer.org/docs/current/developer-docs/quickstart/hello10mins/
- SDK Developer Tools: https://internetcomputer.org/docs/current/developer-docs/build/install-upgrade-remove/
- Motoko Language Guide: https://internetcomputer.org/docs/current/developer-docs/build/languages/motoko/
- Motoko Quick Reference: https://internetcomputer.org/docs/current/developer-docs/build/languages/motoko/language-manual
If you want to work on programs right away, try the following commands to get started:
cd fyp
dfx help
dfx new --help
===============================================================================
To see the project structure:
cd fyp/
tree ./
As the project structure is shown below:
./
├── Cargo.lock
├── Cargo.toml
├── README.md
├── dfx.json
├── notes
│ └── 01 Environment Installations.md
├── package.json
├── src
│ ├── fyp_backend
│ │ ├── Cargo.toml
│ │ ├── fyp_backend.did
│ │ └── src
│ │ └── lib.rs
│ └── fyp_frontend
│ ├── assets
│ │ ├── favicon.ico
│ │ ├── logo2.svg
│ │ ├── main.css
│ │ └── sample-asset.txt
│ └── src
│ ├── index.html
│ └── index.js
└── webpack.config.js
7 directories, 16 files
The following are some important files in the project directory:
dfx.json
A default dfx.json
configuration file is generated at the project setup stage. This file contains settings required to build a project for the Internet Computer blockchain much like the Cargo.toml
file provides build and package management configuration details for Rust programs.
There are some default settings for the created canister:
{
"canisters": {
"fyp_backend": {
// Specifies the location of the Candid interface description file to use for the canister.
"candid": "src/fyp_backend/fyp_backend.did",
// Specifies the package name of the Rust crate. It should be the same as in the crate Cargo.toml file.
"package": "fyp_backend",
// Specifies that this is a rust type canister.
"type": "rust"
},
"fyp_frontend": {
"dependencies": [
"fyp_backend"
],
"frontend": {
"entrypoint": "src/fyp_frontend/src/index.html"
},
"source": [
"src/fyp_frontend/assets",
"dist/fyp_frontend/"
],
"type": "assets"
}
},
"defaults": {
"build": {
"args": "",
"packtool": ""
}
},
"dfx": "0.11.1",
"networks": {
"local": {
"bind": "127.0.0.1:8000",
"type": "ephemeral"
}
},
"version": 1
}
Cargo.toml
In the root directory, there is a Cargo.toml
file.
It defines a Rust workspace by specifying paths to each Rust crate. A Rust type canister is just a Rust crate compiled to WebAssembly
.
# Here we have one member at `src/fyp` which is the only Rust canister.
[workspace]
members = [
"src/fyp_backend",
]
src/fyp_backend/Cargo.toml
As any standard Rust crate, there is a Cargo.toml
file inside the crate folder, which configures the details to build the Rust crate.
[package]
name = "fyp_backend"
version = "0.1.0"
edition = "2021"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[lib]
crate-type = ["cdylib"]
[dependencies]
candid = "0.7.14"
ic-cdk = "0.5.2"
ic-cdk-macros = "0.5.2"
The crate-type = ["cdylib"]
line which is necessary to compile this rust program into WebAssembly
module.
src/fyp_backend/src/lib.rs
The default project has a simple greet
function that uses the DFINITY Rust CDK query
macro.
#[ic_cdk_macros::query]
fn greet(name: String) -> String {
format!("Hello, {}!", name)
}
src/fyp_backend/fyp_backend.did
Candid is an interface description language (IDL) for interacting with canisters running on the Internet Computer. Candid files provide a language-independent description of a canister’s interfaces including the names, parameters, and result formats and data types for each function a canister defines.
By adding Candid files to your project, you can ensure that data is properly converted from its definition in Rust to run safely on the Internet Computer blockchain.
Visit the links in the references to see details about the Candid interface description language syntax.
service : {
"greet": (text) -> (text) query;
}
This definition specifies that the greet
function is a query
method which takes text
data as input and returns text
data.
Some information in this note come from the following external links: