From ca627abe9251ab9068b780f3ef97f478b9097db7 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Mon, 29 Jan 2024 16:23:58 -0600 Subject: [PATCH 1/4] Hello world quickstart guide --- docs/developer-docs/setup/first-canister.mdx | 6 +- docs/developer-docs/setup/hello-world.mdx | 253 +++++++++++++++++++ sidebars.js | 5 + 3 files changed, 261 insertions(+), 3 deletions(-) create mode 100644 docs/developer-docs/setup/hello-world.mdx diff --git a/docs/developer-docs/setup/first-canister.mdx b/docs/developer-docs/setup/first-canister.mdx index 93b18b9668..42dbc9115f 100644 --- a/docs/developer-docs/setup/first-canister.mdx +++ b/docs/developer-docs/setup/first-canister.mdx @@ -223,13 +223,13 @@ By default, the `dfx.json` file will contain automatically generated configurati ## Reviewing the default program code -The backend canister's code will be located in the `src/hello_world_backend` subdirectory. +The backend canister's code will be located in the `src/hello_backend` subdirectory. ```motoko -///src/hello_world_backend/main.mo +///src/hello_backend/main.mo actor { public query func greet(name : Text) : async Text { return "Hello, " # name # "!"; @@ -241,7 +241,7 @@ public query func greet(name : Text) : async Text { ```rust -///src/hello_world_backend/src/lib.rs +///src/hello_backend/src/lib.rs #[ic_cdk::query] fn greet(name: String) -> String { format!("Hello, {}!", name) diff --git a/docs/developer-docs/setup/hello-world.mdx b/docs/developer-docs/setup/hello-world.mdx new file mode 100644 index 0000000000..6ec90f6e6a --- /dev/null +++ b/docs/developer-docs/setup/hello-world.mdx @@ -0,0 +1,253 @@ +# Hello, world! + +This guide shows how to get started developing on ICP quickly by deploying your first 'Hello, world!' smart contract. + +## Install dependencies + +### Install the IC SDK (v0.15.2 and newer) + +```bash +sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)" +``` + +### Install Node.js + +```bash +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash +nvm install 18 +``` + +## Start the local replica + +```bash +dfx start +``` + +## Create a new project + + + + +```bash +dfx new hello +cd hello +npm install +``` + + + + +```bash +dfx new hello --type=rust +cd hello +npm install +``` + + + + + +```bash +npx azle new azle_hello +cd hello +npm install +``` + + + + + +Create the project directory and file structure: + +```bash +mkdir kybra_hello +cd kybra_hello + +mkdir src + +touch src/main.py +touch dfx.json +``` + +Create a virtual environment: + +```bash +~/.pyenv/versions/3.10.7/bin/python -m venv venv +source venv/bin/activate +``` + +Install Kybra: + +```bash +pip install kybra +``` + + + + +For information about project structure and default configuration, [learn more about deploying your first canister](first-canister.mdx). + +## Smart contract code + + + + +```motoko +// src/hello_backend/main.mo +actor { +public query func greet(name : Text) : async Text { + return "Hello, " # name # "!"; +}; +}; +``` + + + + +```rust +// src/hello_world_backend/src/lib.rs +#[ic_cdk::query] +fn greet(name: String) -> String { + format!("Hello, {}!", name) +} +``` + + + +```typescript +// azle_hello/src/index.ts +import { Canister, query, text, update, Void } from 'azle'; + +// This is a global variable that is stored on the heap +let message = ''; + +export default Canister({ + // Query calls complete quickly because they do not go through consensus + getMessage: query([], text, () => { + return message; + }), + // Update calls take a few seconds to complete + // This is because they persist state changes and go through consensus + setMessage: update([text], Void, (newMessage) => { + message = newMessage; // This change will be persisted + }) +}); +``` + + + + + +Create the project directory and file structure: + +```python +# kybra_hello/src/main.py + +from kybra import query, update, void + +# This is a global variable that is stored on the heap +message: str = '' + +# Query calls complete quickly because they do not go through consensus +@query +def get_message() -> str: + return message + +# Update calls take a few seconds to complete +# This is because they persist state changes and go through consensus +@update +def set_message(new_message: str) -> void: + global message + message = new_message # This change will be persisted + +``` + + + + + +## Deploy locally + +Deploy the project's canisters locally: + +``` +dfx deploy +``` + +## Call the canister + + + + +```bash +dfx canister call hello_backend greet world +``` + +Output: + +``` +("Hello, world!") +``` + + + + +```bash +dfx canister call hello_backend greet world +``` + +Output: + +``` +("Hello, world!") +``` + + + + + +```bash +dfx canister call azle_hello setMessage '("Hello, world!")' +``` + +Then, call the `getMessage` function: + +``` +dfx canister call azle_hello getMessage +``` + +Output: + +``` +("Hello, world!") +``` + + + + + +```bash +dfx canister call kybra_hello set_message '("Hello, world!")' +``` + +Then, call the `getMessage` function: + +``` +dfx canister call kybra_hello getMessage +``` + +Output: + +``` +("Hello, world!") +``` + + + + + +## Next steps + +- [Acquire cycles](cycles/cycles-faucet.md). + +- [Deploy to the mainnet](deploy-mainnet.md). \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 16835106e7..e927da06f5 100644 --- a/sidebars.js +++ b/sidebars.js @@ -15,6 +15,11 @@ const sidebars = { label: "What is the Internet Computer?", id: "concepts/what-is-ic", }, + { + type: "doc", + label: "Hello, world!", + id: "developer-docs/setup/hello-world", + }, { type: "doc", label: "Installing the IC SDK", From d3191d0eb12325b63ca5d491a4bd9bc78ea3eb75 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Mon, 29 Jan 2024 16:36:00 -0600 Subject: [PATCH 2/4] Hello world quickstart guide --- docs/developer-docs/setup/hello-world.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/developer-docs/setup/hello-world.mdx b/docs/developer-docs/setup/hello-world.mdx index 6ec90f6e6a..33ba2faccb 100644 --- a/docs/developer-docs/setup/hello-world.mdx +++ b/docs/developer-docs/setup/hello-world.mdx @@ -159,7 +159,6 @@ def get_message() -> str: def set_message(new_message: str) -> void: global message message = new_message # This change will be persisted - ``` From e015e442980c06953f8b0e603a52396a2ae18b3f Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Mon, 29 Jan 2024 16:36:34 -0600 Subject: [PATCH 3/4] Hello world quickstart guide --- docs/developer-docs/setup/hello-world.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/developer-docs/setup/hello-world.mdx b/docs/developer-docs/setup/hello-world.mdx index 33ba2faccb..525a9059a7 100644 --- a/docs/developer-docs/setup/hello-world.mdx +++ b/docs/developer-docs/setup/hello-world.mdx @@ -112,6 +112,8 @@ fn greet(name: String) -> String { } ``` + + ```typescript From 45a5feb9d4a26cebb4e01e4ff42a75c91db994ea Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Tue, 30 Jan 2024 11:53:27 -0600 Subject: [PATCH 4/4] add examples submodule --- .gitmodules | 3 +++ submodules/examples | 1 + 2 files changed, 4 insertions(+) create mode 160000 submodules/examples diff --git a/.gitmodules b/.gitmodules index 78c3dc10c8..9a14ffe2d2 100644 --- a/.gitmodules +++ b/.gitmodules @@ -15,3 +15,6 @@ path = submodules/interface-spec url = https://github.com/dfinity/interface-spec.git branch = public +[submodule "submodules/examples"] + path = submodules/examples + url = https://github.com/dfinity/examples.git diff --git a/submodules/examples b/submodules/examples new file mode 160000 index 0000000000..d6234de89b --- /dev/null +++ b/submodules/examples @@ -0,0 +1 @@ +Subproject commit d6234de89b1a01fa71b5cbe3962f252a7ac66ce6