FYP
2022-09-01 20:00:00

Project Setup

The following conditions need to be fulfilled before setting up a Rust-CDK IC project:

  • Internet connection and access to a shell
  • Rust tool chain version at 1.46.0 or later installed
  • dfx installed
  • Node.js installed (optional)
  • ic-cdk-optimizer utility installed
  • cmake installed.
  • Stopped any local execution environment.

Create Project Using DFX

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

Important Files Overview

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.

References

Some information in this note come from the following external links: