Skip to main content

4: Rust quickstart

Beginner
Rust
Tutorial

Overview​

Applications for the Internet Computer blockchain start as projects. You can create new projects for the Internet Computer blockchain using the IC SDK. Because you are building this project to be deployed on the Internet Computer blockchain, this guide focuses on how to create, build, and deploy a Rust program by using the dfx parent command and its subcommands.

Prerequisites​

Before getting started, assure you have set up your developer environment according to the instructions in the developer environment guide.

Creating a new Rust project​

To create a new Rust project using the IC SDK, open a terminal window and run the following command:

Use dfx new <project_name> to create a new project:

dfx new rust_hello

You will be prompted to select the language that your backend canister will use. Select 'Rust':

? Select a backend language: ›
  Motoko
❯ Rust
  TypeScript (Azle)
  Python (Kybra)

Then, select a frontend framework for your frontend canister, or select 'No frontend canister':

  ? Select a frontend framework: ›
❯ SvelteKit
  React
  Vue
  Vanilla JS
  No JS template
  No frontend canister

Lastly, you can include extra features to be added to your project:

  ? Add extra features (space to select, enter to confirm) ›
⬚ Internet Identity
⬚ Bitcoin (Regtest)
⬚ Frontend tests

Next, navigate into your project directory by running the following command:

cd rust_hello

Starting the local canister execution environment​

Next, before you can build your project, you need to connect to either the local replica running in your development environment or the decentralized Internet Computer mainnet. For this guide, you'll deploy locally in your developer environment. For more information on deploying on the mainnet, check out the next step deploying canisters.

To start the local canister execution environment, first check that you are still in the root directory for your project, if needed.

Then, start the local replica on your computer in the background by running the following command:

dfx start --clean --background

Depending on your platform and local security settings, you might see a warning displayed. If you are prompted to allow or deny incoming network connections, click Allow.

Register, build, and deploy your project​

After you connect to the local replica running in your development environment, you can register, build, and deploy your project locally.

Register, build, and deploy the canisters specified in the dfx.json file by running the following command:

dfx deploy

The dfx deploy command output displays information about each of the operations it performs similar to the following excerpt:

Creating a wallet canister on the local network.
The wallet canister on the "local" network for user "default" is "rwlgt-iiaaa-aaaaa-aaaaa-cai"
Deploying all canisters.
Creating canisters...
Creating canister rust_hello_backend...
rust_hello_backend canister created with canister id: rrkah-fqaaa-aaaaa-aaaaq-cai
Creating canister rust_hello_frontend...
rust_hello_frontend canister created with canister id: ryjl3-tyaaa-aaaaa-aaaba-cai
Building canisters...

...

Deployed canisters.
URLs:
Frontend canister via browser
    rust_hello_frontend: http://127.0.0.1:4943/?canisterId=ryjl3-tyaaa-aaaaa-aaaba-cai
Backend canister via Candid interface:
    rust_hello_backend: http://127.0.0.1:4943/?canisterId=r7inp-6aaaa-aaaaa-aaabq-cai&id=rrkah-fqaaa-aaaaa-aaaaq-cai

Testing the dapp​

There are several ways to interact with your canisters. Let's talk about access from the browser first.

To access the frontend canister (rust_hello_frontend) you can simply follow the link that was printed in the terminal in the previous step.

    Frontend canister via browser
        rust_hello_frontend: http://127.0.0.1:4943/?canisterId=ryjl3-tyaaa-aaaaa-aaaba-cai

Frontend canisters, also called asset canisters, allow access to web content directly from a smart contract. This enables you to deploy your entire dapp, not just the backend, on the Internet Computer.

To access the backend canister (rust_hello_backend) you can again open the URL printed to your terminal in the previous step.

Backend canister via Candid interface:
        rust_hello_backend: http://127.0.0.1:4943/?canisterId=r7inp-6aaaa-aaaaa-aaabq-cai&id=rrkah-fqaaa-aaaaa-aaaaq-cai

Using this method, open the so called Candid UI canister that is automatically deployed to your local replica when you first ran dfx deploy. The Candid UI canister fetches the interface from your backend canister and allows you to test and browse your canister's API with a visual web interface.

To test the deployed rust_hello_backend locally from your command line using dfx, you can run the greet function by running the following command:

dfx canister call rust_hello_backend greet world

Then, verify that the call to the rust_hello_backend canister greet function returns a text message ("Hello, world!").

Stopping the local canister execution environment​

After testing the application, you can stop the local replica so that it doesn’t continue running in the background.

To stop the local replica running on your computer, run the following command:

dfx stop

When dfx is started again in the future, it should be started with the dfx start --clean command to wipe the previous state.

Next steps​

Now, let's take a closer look into writing and deploying canisters