Skip to content

Latest commit

 

History

History
163 lines (111 loc) · 7.33 KB

README.md

File metadata and controls

163 lines (111 loc) · 7.33 KB
Raw

IC SDK

This repo contains the IC SDK: a Software Development Kit for creating and managing canister smart contracts on the Internet Computer (ICP blockchain).

For further reading:

What gets installed

The IC SDK installation script installs several components in default locations on your local computer. The following table describes the development environment components that the installation script installs:

Component Description Default location
dfx Command-line interface (CLI) /usr/local/bin/dfx
moc Motoko runtime compiler ~/.cache/dfinity/versions/<VERSION>/moc
replica Internet Computer local network binary ~/.cache/dfinity/versions/<VERSION>/replica
uninstall.sh Script to remove the SDK and all of its components ~/.cache/dfinity/uninstall.sh
versions Cache directory that contains a subdirectory for each version of the SDK you install. ~/.cache/dfinity/versions

SDK vs CDK vs dfx

There are a few components above worth expanding on:

  1. dfx - dfx is the command-line interface for the IC SDK. This is why many commands for the IC SDK start with the command "dfx .." such as dfx new or dfx stop.

  2. Canister Development Kit (CDK) - A CDK is an adapter used by the IC SDK so a programming language has the features needed to create and manage canisters. The IC SDK comes with a few CDKs already installed for you so you can use them in the language of yoru choice. That is why there is a Rust CDK, Python CDK, TypeScript CDK, etc... Since CDKs are components used the SDK, some developer choose to use the CDK directly (without the IC SDK), but typically are used as part of the whole IC SDK.

Getting Started

Installing

You can install the IC SDK a few different ways.

via curl (recommended)

sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"

This command will install a binary compatible with your operating system, and add it to /usr/local/bin.

via GitHub Releases

Find a release for your architecture here.

in GitHub Action, using dfinity/setup-dfx

    steps:
    - name: Install dfx
      uses: dfinity/setup-dfx@main

Getting Help

Once the IC SDK is installed, get acquainted with its capabilities by entering.

dfx help

Contributing to the DFINITY SDK

See our contributing guidelines here.

Building the IC SDK

Building the IC SDK is very simple:

cargo build

Release Process

IC SDK is released in two steps:

  1. Publishing a new IC SDK release.

  2. Publishing a new manifest.json and install.sh to instruct the installer to actually download and install the new IC SDK release.

Publishing the IC SDK

  1. The release manager makes sure the dfx stable branch points to the revision that should be released and that the revision is tagged with a version (like 0.5.6).

  2. The sdk-release jobset on Hydra tracks the stable branch and starts evaluating shortly after stable advances.

  3. As you can see it only has the single job publish.dfx which is defined here in terms of the dfx job. Note that the publish.dfx job only exists when the revision has a proper version tag. This prevents publishing of untagged revisions.

  4. Our CD system running at deployer.dfinity.systems is configured with the publish-sdk-dfx-release job. It will monitor the aforementioned publish.dfx job for new builds, whenever there's a new build it will download the output (the CD script) and execute it.

  5. As you can see the script also sends a message to the #build-notifications Slack channel so you can see when and if the SDK has been published.

Publishing manifest.json and install.sh

After the IC SDK has been released it's available for download but the install script at https://sdk.dfinity.org/install.sh won't immediately install it. To make sure the installer actually downloads and installs the new IC SDK release the manifest.json file at https://sdk.dfinity.org/manifest.json has to set its tags.latest field to the new version. The following explains how to do that.

  1. Edit the public/manifest.json file such that it points to the new IC SDK version and make sure this is merged in master.

  2. Similarly to releasing the IC SDK there's a install-sh job that builds a CD script for publishing the manifest.json and install.sh to our CDN.

  3. This job is built on the sdk jobset which tracks the master branch.

  4. deployer.dfinity.systems is configured with the publish-sdk-install-sh job which will monitor the aforementioned publish.install-sh.x86_64-linux job for new builds, whenever there's a new build it will download the output (the CD script) and execute it.

Troubleshooting

This section provides solutions to problems you might encounter when using the IC SDK via dfx command line

Project Reset

This command will remove the build directory and restart your replica:

dfx stop && dfx start --clean --background

Using Internet Identity Locally

You can deploy the Internet Identity canister into your replica alongside your project by cloning https://github.com/dfinity/internet-identity. From the internet-identity directory, run the following command:

II_ENV=development dfx deploy --no-wallet --argument '(null)'

There are more notes at https://github.com/dfinity/internet-identity#running-locally that may be helpful.