From 725ce77a8c60525dd194b05c65a4c6d31fb87bd7 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 10 Jun 2024 09:29:58 -0500 Subject: [PATCH] Update docs (#4566) * add MOPS docs * Add default dfx instructions * add additional error codes * Sample projects * Sample projects * Update doc/md/getting-started/dev-env.md Co-authored-by: Luc Blaeser <112870813+luc-blaeser@users.noreply.github.com> * Update examples.md --------- Co-authored-by: Luc Blaeser <112870813+luc-blaeser@users.noreply.github.com> --- doc/md/getting-started/dev-env.md | 31 +++++ doc/md/getting-started/examples.md | 110 ++++++++++++++++++ doc/md/getting-started/motoko-introduction.md | 33 ------ doc/md/reference/error-codes.md | 13 +++ doc/md/stable-memory/stablememory.md | 10 ++ 5 files changed, 164 insertions(+), 33 deletions(-) create mode 100644 doc/md/getting-started/examples.md diff --git a/doc/md/getting-started/dev-env.md b/doc/md/getting-started/dev-env.md index de30e283d3a..7e23ba8f479 100644 --- a/doc/md/getting-started/dev-env.md +++ b/doc/md/getting-started/dev-env.md @@ -82,6 +82,8 @@ https://github.com/dfinity/sdk/blob//nix/sources.json#L144 Replace `` with the IC SDK release version, such as `0.14.2`. +## Custom developer environment + ### Specifying a custom version of the compiler To specify a custom version of the Motoko compiler to be used with `dfx`, you can use the package manager `mops` or `vessel`. @@ -111,3 +113,32 @@ For example, to use base library version `0.9.0`, use the command: ``` mops add base@0.9.0 && mops install ``` + +### Specifying a custom version of `dfx` + +To specify a custom version of `dfx`, you can use the [`dfxvm` tool](/docs/current/developer-docs/developer-tools/cli-tools/dfxvm/docs/cli-reference/dfxvm/dfxvm-default). To set a default `dfx` version to be used in your project, run the command: + +``` +$ dfxvm default 0.7.2 +... +info: installed dfx 0.7.2 +info: set default version to dfx 0.7.2 +``` + +### Pass flags to `moc` in `dfx.json` + +You can pass flags directly to `moc` by adding an `args` field in your Motoko canister's description in your project's `dfx.json` file: + +Here is an example `dfx.json` canister configuration that uses `args`: + +```json +... + "canisters": { + "hello": { + "type": "motoko", + "main": "src/hello/main.mo", + "args": "-v --incremental-gc" + }, + } +... +``` diff --git a/doc/md/getting-started/examples.md b/doc/md/getting-started/examples.md new file mode 100644 index 00000000000..11e8df8880d --- /dev/null +++ b/doc/md/getting-started/examples.md @@ -0,0 +1,110 @@ +--- +sidebar_position: 5 +--- + +# Sample projects and resources + +## Overview + +Want to get started building with Motoko? Check out some of these sample projects and Motoko resources to help you get started. + +## Sample apps + +### Canister management + +- [Canister app](https://github.com/canister-app): A series of tools for canister tools written in Motoko. + +- [Canister Geek](https://github.com/usergeek/canistergeek-ic-motoko): Canister cycle monitoring and management. + +- [Canister tip jar](https://github.com/ninegua/tipjar): Donate cycles to a canister on ICP. + +- [iCAN](https://github.com/PrimLabs/iCAN): A canister management platform for creating and managing canisters conveniently. + +- [ic-blackhole](https://github.com/ninegua/ic-blackhole): An example of a black hole canister. + +- [motoko_top_up_canister](https://github.com/ORIGYN-SA/motoko_top_up_canister): A Motoko canister that automatically tops up a user-defined list of canisters. + +### Games, social, and utility samples + +- [Bitshop](https://github.com/lukasvozda/bitshop): A Shopify alternative that accepts Bitcoin payments. + +- [Cleansheets](https://github.com/matthewhammer/cleansheets): A spreadsheet application. + +- [DocToken](https://github.com/ava-vs/doctoken): Document storage. + +- [EVM proof verifier](https://github.com/horizonx-tech/evm-proof-verifier-motoko): Verify EVM proofs using a Motoko canister. + +- [Flower power DAO](https://github.com/flowerpowerdao/power-equalizer-v3). + +- [Formyfi](https://github.com/Talentum-id/formify): Question and answer forms. + +- [HTTP server for Motoko](https://github.com/krpeacock/server): A simple HTTP server. + +- [IC Payroll](https://github.com/cosmasken/ic-payroll): A simple payroll dapp that allows users to be paid in ckBTC. + +- [Metabomb](https://github.com/av1ctor/metamob): A campaign dapp for fundraising or donations. + +- [NacDB](https://github.com/vporton/NacDB): A distributed database. + +- [Play to earn game sample](https://github.com/therealbryanho/IC-Code-Sample-Unity-Play-to-Earn-Game): A simple play to earn game template. + +- [Rakeoff statistics](https://github.com/rakeoff-labs/rakeoff_statistics): A Motoko canister that provides statistic analysis for the [Rakeoff application](https://app.rakeoff.io/). + +- [Reversi](https://github.com/ninegua/reversi): A multiplayer Reversi game. + +- [Revo](https://github.com/DepartureLabsIC/revo): A drawing game. + +- [SecureGuard Escrow](https://github.com/bix-tech/secure-guard-escrow): ICP-based escrow platform. + +### Tokens & DeFi + +- [Appic](https://github.com/Appic-Solutions/Auto_Investment): Automatically by and sell tokens at a specific interval or time. + +- [ICDex](https://github.com/iclighthouse/ICDex): An on-chain orderbook decentralized exchange written in Motoko. + +- [icrc7_motoko](https://github.com/noku-team/icrc7_motoko) and - [icrc7-mo](https://github.com/PanIndustrial-Org/icrc7.mo): Motoko implementations of the ICRC-7 NFT standard. + +- [icrc-nft-mo](https://github.com/PanIndustrial-Org/icrc_nft.mo): An example NFT that combines `icrc7-mo`, `icrc30-mo`, and `icrc3-mo`. + +- [ic-token](https://github.com/rocklabs-io/ic-token) and [motoko-token](https://github.com/enzoh/motoko-token): Motoko implementations of an ERC-20 token. + +- [Itoka music NFT](https://github.com/Itoka-DAO/itoka-music-nft-standard): A standard for music NFTs. + +- [Motoko Bitcoin](https://github.com/tgalal/motoko-bitcoin): A Motoko Bitcoin integration. + +- [Staking pool](https://github.com/ICTO-Labs/staking-pool): A staking pool project written in Motoko. + +- [Token faucet](https://github.com/rocklabs-io/token-faucet): A token faucet for [ic-token](https://github.com/rocklabs-io/ic-token). + +- [Token minter sample](https://github.com/icpipeline-framework/mbt): A sample app that mints tokens. + +### Writing Motoko + +- [Blocks](https://blocks-editor.github.io/blocks/): A Motoko smart contract editor. + +- [JSON for Motoko](https://github.com/aviate-labs/json.mo): Motoko JSON library. + +- [motoko-library-template](https://github.com/kritzcreek/motoko-library-template): Template for creating Motoko libraries. + +- [Motoko Pilot](https://d7dm6-sqaaa-aaaag-qcgma-cai.icp0.io/): An AI tool for writing Motoko. + +- [Motoko starter](https://github.com/motoko-bootcamp/motoko-starter): Basic starter template for Motoko projects. + +- [Vite + React + Motoko template](https://github.com/rvanasa/vite-react-motoko): Boilerplate template for Vite, React, and Motoko. + +- [Visual Studio Code Motoko extension](https://github.com/dfinity/vscode-motoko): A VS Code extension for Motoko. + + +## Education resources + +- [Awesome Motoko](https://github.com/ic123-xyz/awesome-motoko): A list of Motoko projects, tools, and resources. + +- [DFINITY Examples](https://github.com/dfinity/examples/tree/master/motoko): Simple Motoko sample projects and templates. + +- [ICP developer journey](https://internetcomputer.org/docs/current/tutorials/developer-journey/): A 36-part series focused on Motoko development for ICP canisters. + +- [Motoko Auction summer camp example](https://github.com/luc-blaeser/auction). + +- [Motoko book](https://github.com/Web3NL/motoko-book): An educational book on Motoko. + +- [Motoko Bootcamp](https://github.com/motoko-bootcamp/education): Lessons and lectures on Motoko development. diff --git a/doc/md/getting-started/motoko-introduction.md b/doc/md/getting-started/motoko-introduction.md index 800e08fb470..b221ed1b84a 100644 --- a/doc/md/getting-started/motoko-introduction.md +++ b/doc/md/getting-started/motoko-introduction.md @@ -94,36 +94,3 @@ For scenarios that can’t be solved using stable variables alone, Motoko provid ## Getting started Get started with Motoko by [setting up your developer environment](dev-env.md) and creating a simple [Hello, world!](quickstart.md) program. - -## Sample apps - - -For projects that use the Motoko programming language, see [Motoko sample projects](https://github.com/dfinity/examples/tree/master/motoko). - -- [Calculator: simple functions](https://github.com/dfinity/examples/tree/master/motoko/calc) - -- [Counter](https://github.com/dfinity/examples/tree/master/motoko/counter) - -- [Echo](https://github.com/dfinity/examples/tree/master/motoko/echo) - -- [Factorial](https://github.com/dfinity/examples/tree/master/motoko/factorial) - -- [Hello, cycles](https://github.com/dfinity/examples/tree/master/motoko/hello_cycles) - -- [Hello, world](https://github.com/dfinity/examples/tree/master/motoko/hello-world) - -- [Game of Life: upgrades](https://github.com/dfinity/examples/tree/master/motoko/life) - -- [Phone book](https://github.com/dfinity/examples/tree/master/motoko/phone-book) - -- [Publish and subscribe](https://github.com/dfinity/examples/tree/master/motoko/pub-sub) - -- [Quicksort](https://github.com/dfinity/examples/tree/master/motoko/quicksort) - -- [Random maze using cryptographic randomness](https://github.com/dfinity/examples/tree/master/motoko/random_maze) - -- [To-do checklist](https://github.com/dfinity/examples/tree/master/motoko/simple-to-do) - -- [Superheroes database](https://github.com/dfinity/examples/tree/master/motoko/superheroes) - -- [whoami](https://github.com/dfinity/examples/tree/master/motoko/whoami) diff --git a/doc/md/reference/error-codes.md b/doc/md/reference/error-codes.md index 7b4fb28820a..14d7a4b5ff3 100644 --- a/doc/md/reference/error-codes.md +++ b/doc/md/reference/error-codes.md @@ -7,6 +7,7 @@ sidebar_position: 6 | Error code | Error description | |------------|-------------------| | M0001 | Parsing errors | +| M0003 | Module tried to import itself | | M0009 | File not found for import | | M0010 | Imported package was not defined | | M0014 | Non-static expression in library or module | @@ -37,8 +38,20 @@ sidebar_position: 6 | M0112 | Tuple pattern cannot consume type | | M0116 | Variant pattern cannot consume type | | M0126 | Shared function cannot be private | +| M0137 | A type or class was declared that explicitly or implicitly references an outer type parameter. | | M0139 | Inner actor classes are not supported | | M0141 | Forbidden declaration in program | | M0145 | Pattern does not cover value | +| M0149 | An immutable record field (declared without `var`) was supplied where a mutable record field (specified with `var`), was expected. | +| M0150 | A mutable record field (declared with `var`) was supplied where an immutable record field (specified without `var`) was expected. | +| M0151 | A object literal is missing some fields. | +| M0153 | An imported Candid file (.did) mentions types that cannot be represented in Motoko. | | M0154 | Deprecation annotation | | M0155 | Inferred type Nat for subtraction | +| M0156 | A parameterized type definition, or set of type definitions, is too complicated for Motoko to accept. | +| M0157 | A type definition, or set of type definitions, is ill-defined. | +| M0158 | A public class was declared without providing it with a name. | +| M0194 | An identifier was defined without referencing it later. | +| M0195 | A function that demands elevated (system) capabilities was called without manifestly passing the capability. | +| M0197 | A function that requires (system) capabilities was called in a context that does not provide them. | +| M0198 | A field identifier was specified in an object pattern without referencing this identifier later. | \ No newline at end of file diff --git a/doc/md/stable-memory/stablememory.md b/doc/md/stable-memory/stablememory.md index f7a7cb6d259..251e3299f46 100644 --- a/doc/md/stable-memory/stablememory.md +++ b/doc/md/stable-memory/stablememory.md @@ -103,3 +103,13 @@ Because `StableLog` allocates and maintains its (potentially large) log data dir - [`memory-buffer`](https://mops.one/memory-buffer): Persistent buffer implementation. - [`memory-hashtable`](https://mops.one/memory-hashtable): A library for storing, updating, deleting, and retrieving a single blob-value per key. + +## Samples + +- [motoko-bucket](https://github.com/PrimLabs/Bucket): A key value database library that uses stable memory. + +- [motoko-cdn](https://github.com/gabrielnic/motoko-cdn): An auto-scaling storage solution. + +- [motoko-dht](https://github.com/enzoh/motoko-dht): A distributed hash table sample. + +- [motoko-document-db](https://github.com/DepartureLabsIC/motoko-document-db): A document database sample.