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/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..525a9059a7 --- /dev/null +++ b/docs/developer-docs/setup/hello-world.mdx @@ -0,0 +1,254 @@ +# 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", 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