We provide a collection of utilities for developing Canisters for the Internet Computer (IC) blockchain, all without using dfx.
WARNING: Very experimental at the moment, try at your own risk!
Except the testing and deployment part, canister development is largely the same as ordinary software development. To better cope with the growing complexity, we should:
- Allow projects to use familiar build tools, most notably, the Makefile.
- Prefer the composition of a variety of tools instead of one monolithic binary.
- Tools for interacting with system canisters on the IC including the ledger.
- Makefile based command line workflow including
- Create, top-up, install, and call canisters (without using cycles wallets).
- Uninstall canisters after collecting remaining cycles.
- Interacting with IC.
- Running a local replica for testing.
- Project setup for Motoko backend.
- Project setup for JS frontend.
- Project setup for C and Rust backends.
- Linux support.
- Darwin (OS X) support.
- WSL (Windows) support.
Download a binary release package and unpack it somewhere on the system.
It includes a few other IC tools and binaries: quill, keysmith, moc from Motoko, icx from agent-rs.
Please feel free to include the unpacked bin sub-directory in your PATH environment, but this is not required.
One of the command in the unpacked bin sub-directory is ic-init-project.
As an example, you can setup a Makefile in a new or existing directory like this:
ic-init-project .
It will first check the existence of a few system tools (make from GNU Make, protoc from protobuf, jq and xxd) in PATH.
Most likely you can have all of them installed via the preferred package installation of your distro.
To use the Makefile once it is setup, you also need to set the PEM_FILE environment variable.
It has to point to a file holding the private key of the principal you want to use for development.
If you have used dfx, it usually is ~/.config/dfx/identity/default/identity.pem.
Or create a new one using keysmith.
This is required for creating and installing canisters on the IC, and you will need some ICPs on this account to pay for cycles too.
You can try it out by playing with a sample "hello" project:
make init-hello
To learn about what else can be done, there is make help:
$ make help
The following are examples of using this Makefile, assuming you have a
project called 'hello' written in 'src/hello.mo'.
Install to IC, and initialize it with cycles converted from 0.02 ICPs:
make install/hello ICP=0.02 MODE=install
Call its method 'greet' with an argument:
make call/hello METHOD=greet ARG='("world")'
Commonly used make targets are in the form of '<action>/<canister>'.
The <action> is one of: 'install', 'topup', 'status', 'update_settings',
'call' and 'query'.
Commonly used variable settings:
METHOD method name to call on the canister
ARG argument list encoded in Candid text format.
MODE one of 'install', 'reinstall' and 'upgrade' (default)
IC network URI, e.g. 'http://localhost:8000' for a local setup.
All canisters installed in IC will have their canister ids created in
file 'canister_ids.json'. Make sure you don't lose this file, otherwise
you may lose access to your canisters if you don't have their ids.
What is nice of using Makefile is that a command like make call/... will perform all prerequisite steps before calling the canister.
This may include compiling Wasm, creating, installing or updating canisters, and so on.
It is a big time saver when it comes to source code editing and testing loops.
Start build now by editing the Makefile!
Built products like Wasm and Candid files are put in dist sub-directory, and network installation status are put in the run sub-directory.
But permanent canister IDs on IC are recorded in canister_ids.json file.
You are advised to make backups of this file or track it in your git repository.
If you want to contribute to this project, the fastest way to develop is to install nix and run nix-shell, which will launch you in a shell with all required dependencies ready to use.