https://github.com/dfinity/motoko-base
The Motoko base library
https://github.com/dfinity/motoko-base
internet-computer library modules motoko
Last synced: 24 days ago
JSON representation
The Motoko base library
- Host: GitHub
- URL: https://github.com/dfinity/motoko-base
- Owner: dfinity
- License: apache-2.0
- Created: 2020-04-14T16:34:26.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2025-04-25T14:16:53.000Z (about 1 month ago)
- Last Synced: 2025-04-25T15:26:00.930Z (about 1 month ago)
- Topics: internet-computer, library, modules, motoko
- Language: Motoko
- Homepage:
- Size: 3.57 MB
- Stars: 488
- Watchers: 39
- Forks: 101
- Open Issues: 154
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-motoko - motoko-base - The Motoko base library, commonly used data structures and algorithms, maintained by the official. (Libraries / Data structures)
- best-of-crypto - GitHub - 74% open · ⏱️ 19.04.2024): (Metaverse, NFTs & Gaming)
README
The Motoko base library
=======================
This repository contains the Motoko base library. It is intended to be used with the [`moc` compiler](https://github.com/dfinity/motoko) (and tools that wrap it, like `dfx`).
Usage
-----
If you are installing Motoko through the DFINITY SDK releases, then this base
library is already included.
If you build your project using the [Mops package manager], run the following command to add the base package to your project:
```sh
mops add base
```
If you build your project using the [Vessel package manager] your package-set most likely already includes base, but if it doesn't or you want to override its version, add an entry like so to your `package-set.dhall`:
```
{
name = "base",
repo = "https://github.com/dfinity/motoko-base",
version = "master",
dependencies = [] : List Text
}
```
The package _name_ `"base"` appears when importing its modules in Motoko (e.g., `import "mo:base/Nat"`). The _repo_ may either be your local clone path, or this public repository url, as above. The _version_ can be any git branch or tag name (such as `version = "moc-0.8.4"`). There are no dependencies. See the [Vessel package manager] docs for more details.
[Mops package manager]: https://mops.one
[Vessel package manager]: https://github.com/dfinity/vessel
Building & Testing
------------------
Run the following commands to configure your local development branch:
```sh
# First-time setup
git clone https://github.com/dfinity/motoko-base
cd motoko-base
npm install
# Run tests
npm test
# Run all tests in wasi mode
npm test -- --mode wasi
# Run formatter
npm run prettier:format
```
**Note**:
- If you are using `npm test` to run the tests:
- You don't need to install any additional dependencies.
- The test runner will automatically download the `moc` and `wasmtime` versions specified in `mops.toml` in the `[toolchain]` section.
- If you are using `Makefile` to run the tests:
- The test runner will automatically detect the `moc` compiler from your system path or `dfx` installation.
- Running the tests locally also requires [Wasmtime](https://wasmtime.dev/) and [Vessel](https://github.com/dfinity/vessel) to be installed on your system.
Run only specific test files:
```sh
npm test
```
For example `npm test list` will run `List.test.mo` and `AssocList.test.mo` test files.
Run tests in watch mode:
```sh
npm test -- --watch
# useful to combine with filter when writing tests
npm test array -- --watch
```
Documentation
-------------
The documentation can be generated in `doc/` by running
```sh
./make_docs.sh
```
which creates `_out/html/index.html`.
The `next-moc` branch
---------------------
The `next-moc` branch contains changes that make base compatible with the
in-development version of `moc`. This repository's public CI does _not_ run
on that branch.
External contributions are best made against `master`.
- `master` branch is meant for the newest **released** version of `moc`
- The CI runs on this branch
- `next-moc` branch is meant for the **in-development** version of `moc`
- This branch is used by the [`motoko` repository](https://github.com/dfinity/motoko)'s CI
Both branches are kept in sync with each other by mutual, circular merges:
- `next-moc` is updated automatically on each push to `master` via the [sync.yml](.github/workflows/sync.yml) workflow
- `master` is updated **manually** on each release of `moc` as part of the `motoko` release process
Only *normal* merges are allowed between `master` and `next-moc`, because development is permitted on both branches.
This policy makes every PR (to either branch) visible in the history of both branches.
Contributing
------------
Please read the [Interface Design Guide for Motoko Base Library](doc/design.md) before making a pull request.