diff --git a/docs/languages/motoko/index.md b/docs/languages/motoko/index.md index f50bb27a..cfc74bfb 100644 --- a/docs/languages/motoko/index.md +++ b/docs/languages/motoko/index.md @@ -6,18 +6,111 @@ sidebar: icskills: [] --- -TODO: Write content for this page. This is the landing page for the Motoko section. Actual Motoko documentation pages are synced from the caffeinelabs/motoko repository. +Motoko is a high-level programming language designed specifically for building canisters on the Internet Computer. It combines a familiar syntax (drawing from JavaScript, Rust, Swift, and Java) with features that map directly to how ICP works: an actor-based programming model, orthogonal persistence, async/await for inter-canister messaging, and compilation to WebAssembly. - -Landing page for Motoko documentation. Brief overview of Motoko as a language designed specifically for ICP: actor model, orthogonal persistence, async/await for inter-canister calls, and strong typing. Link to synced sections (Fundamentals, ICP Features, Reference) and external resources. Always recommend the `core` library (supersedes `base`). Include a note about the base→core migration guide (synced from Motoko repo). +If you want a language where ICP concepts are first-class citizens rather than library abstractions, Motoko is a strong choice. - -- Synced from caffeinelabs/motoko (52+ pages in fundamentals/, icp-features/, reference/) -- Motoko core library (standard): https://mops.one/core/docs -- Motoko base library (legacy, superseded by core): https://mops.one/base/docs -- Base→core migration guide: synced from caffeinelabs/motoko (doc/md/12-base-core-migration.md) +## Key features - -- getting-started/quickstart -- Motoko quickstart path -- guides/backends/data-persistence -- Motoko persistence patterns -- languages/rust/index -- alternative language +**Actor model.** Every Motoko canister is an actor — an isolated unit of state and behavior that communicates with other actors through asynchronous messages. This maps directly to how canisters work on ICP: each canister has private state and a public interface. + +**Orthogonal persistence.** Variables declared in a `persistent actor` survive canister upgrades automatically. There is no database layer, no serialization code, and no pre/post-upgrade hooks needed for most use cases. See [Orthogonal persistence](../../concepts/orthogonal-persistence.md) for how this works at the platform level. + +**Async/await messaging.** Inter-canister calls use `async`/`await`, making sequential message flows read like synchronous code. The compiler and runtime handle the underlying callback mechanics. + +**Strong typing.** Motoko has a sound type system with generics, variant types, pattern matching, and option types (`?T`) that prevent null-pointer errors at compile time. + +**WebAssembly compilation.** Motoko compiles to Wasm, the execution format for all ICP canisters. The compiler handles ICP-specific concerns (Candid serialization, system API bindings, memory management) so you don't have to. + +## Quick example + +A minimal Motoko canister with a query method and an update method: + +```motoko +persistent actor Counter { + var count : Nat = 0; + + public query func get() : async Nat { + return count; + }; + + public func increment() : async () { + count += 1; + }; +}; +``` + +The `persistent actor` declaration means `count` survives canister upgrades. The `query` keyword marks `get` as a fast, read-only call. The `increment` function is an update call that modifies state and goes through consensus. + +## Getting started + +Create a new Motoko project with icp-cli: + +```bash +icp new my-project --subfolder motoko +``` + +This generates a Motoko canister project with an `icp.yaml` build configuration and a source file. The build configuration uses the Motoko recipe: + +```yaml +canisters: + - name: backend + recipe: + type: "@dfinity/motoko@" + configuration: + main: src/main.mo + shrink: true +``` + +Start a local network and deploy: + +```bash +icp network start -d +icp deploy +``` + +For a guided walkthrough, see the [Quickstart](../../getting-started/quickstart.md). + +## Standard library: `core` + +The **`core`** package ([mops.one/core](https://mops.one/core)) is the standard library for Motoko. It supersedes the older `base` library with a cleaner API, consistent naming conventions, and data structures that work directly with stable memory. + +Add it to your project's `mops.toml`: + +```toml +[dependencies] +core = "2.2.0" # Check the latest version at https://mops.one/core + +[toolchain] +moc = "1.3.0" # Check the latest version at https://github.com/caffeinelabs/motoko/releases +``` + +Then import modules: + +```motoko +import Map "mo:core/Map"; +import Text "mo:core/Text"; +import List "mo:core/List"; +``` + +Key improvements in `core` over `base`: + +- All data structures can be stored in stable memory without pre/post-upgrade hooks +- Clear separation between mutable (`Map`, `Set`, `List`) and immutable (`pure/Map`, `pure/Set`, `pure/List`) data structures +- Hash-based collections removed in favor of ordered maps and sets (better security against collision attacks) +- Consistent naming: `values()` instead of `vals()`, `Cycles` instead of `ExperimentalCycles` + +If you have an existing project using `base`, you can migrate incrementally — both libraries can coexist in the same project. See the [base to core migration guide](base-core-migration.md) for detailed instructions. + +`core` and all other Motoko packages are managed with [Mops](https://mops.one), which handles dependency resolution, compiler toolchain management, and publishing. Browse community packages at [mops.one](https://mops.one). + +## Further reading + +- [Quickstart](../../getting-started/quickstart.md) — Create and deploy your first canister +- [Motoko documentation](https://docs.motoko.org) — Full language reference (fundamentals, ICP features, error codes) +- [core library API docs](https://mops.one/core/docs) — Standard library reference +- [Data persistence](../../guides/backends/data-persistence.md) — Persistence patterns for Motoko and Rust canisters +- [Rust](../rust/index.md) — Alternative language for ICP development using the Rust CDK +- [Motoko GitHub](https://github.com/caffeinelabs/motoko) — Compiler source and issue tracker + +