This DFINITY Canister Software Development Kit (SDK) is an Alpha release that provides tools, sample code, and documentation to help you create programs to run on a locally-deployed Internet Computer client node.

Important
For this Alpha release, only macOS and Linux platforms are supported. In addition, you won’t be able to install your programs on an externally-managed Developer Network just yet, but that capability is coming soon.

By developing programs that run on the Internet Computer platform, you can deploy secure, tamper-proof applications and provide web-based services without the restrictions or expense of a proprietary infrastructure, the complexities of database management and maintenance, or the investment in hardware required to run enterprise-scale software.

If you want to learn more about the Internet Computer platform and how it can transform distributed computing and the application landscape, check out Reinventing the internet.

If you are ready to start developing applications that run on the Internet Computer platform, it only takes a few minutes to get up and running.

Before you begin

Before you download and install this release of the SDK, verify the following:

  • You have an internet connection and access to a shell terminal on your local macOS or Linux computer.

  • You have Developer Command Line Tools installed if you are running the demonstration on a macOS computer. You can check whether you have the Developer Command Line Tools installed by running xcode-select -p. You can install the developer tools by running xcode-select --install.

Download and install

The most straightforward option for accessing the DFINITY Canister Software Development Kit (SDK) is to download the SDK package from within a terminal shell on your local computer. With this installation option, you can be logged on as any user and no additional software is required.

To download and install from a terminal shell:

  1. Open a terminal shell on your local computer.

    For example, on macOS open the Applications folder, then open Utilities and double-click Terminal.

  2. Download and install the SDK package by running the following command:

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

    This command prompts you to read and accept the license agreement before installing the dfx command-line interface executable and its dependencies on your local computer.

  3. Review the license agreement, then type y and press Enter if you want to continue with the installation.

    Do you agree and wish to install the DFINITY ALPHA SDK [y/N]?

    + The default response is No. You must type y and press Enter to continue.

    The command displays information about the components being installed on the local computer.

Verify the SDK is ready to use

If the installation script runs without any errors, everything you need to start developing programs that run on the Internet Computer platform will be available on your local computer.

To verify the SDK is ready to use:

  1. Open a terminal shell on your local computer, if you don’t already have one open.

  2. Check that you have the SDK developer command-line interface installed and the executable is available in your PATH by running the following command:

    dfx --version

    The command displays version information for the developer command-line interface similar to the following:

    dfx 0.4.1
  3. Preview usage information for the other developer command-line interface sub-commands by running the following command:

    dfx --help

    The command displays usage information for the dfx parent command and its subcommands.

Create a new project

You are now ready to create a new project for your first sample application.

To create a new project directory for your first application:

  1. Create a new project directory for your first application by running the following commands:

    dfx new hello

    The dfx new hello-world command creates a new hello-world project with a default project directory, some template files, and a new Git repository for your project.

  2. Change to your project directory by running the following command:

    cd hello

Build the program

Your new hello project includes a simple default program in the src/hello directory that you can compile.

To build the program executable:

  1. View the contents of the source directory for your project directory by running the following command:

    ls -l src/hello

    Note that the src/hello directory includes a default main.mo program for your project and a public directory. For this Quick start, you only need to use the main.mo program.

  2. Build the executable from the default main.mo file by running the following command:

    dfx build
  3. Verify the command displays output similar to the following:

    Building hello...

Start the local network and deploy

You now have a program that can be deployed on your local client network.

  1. Start the Internet Computer network on your local computer by running the following command:

    dfx start --background

    Depending on your platform and local security settings, you might see a warning displayed. If you are prompted to allow or deny "client" incoming network connections, click Allow.

    The --background option starts Internet Computer client processes then runs them in the background so that you can continue to the next step without opening another terminal shell on your local computer.

  2. Deploy the default program on the local network by running the following command:

    dfx canister install hello
  3. Call the predefined greet method in the program by running the following command:

    dfx canister call hello greet "there" --type string

    This example uses the dfx cansister call command to pass "there" as an argument of type string to the greet function.

  4. Verify the command displays the return value of the greet function (Hello, there!).

    For example:

       Application: P2P/IngressPool
        Nov 13 10:54:31.543 INFO Insert an ingress message in Ingress pool
       Application: Http Handler
        Nov 13 10:54:31.545 INFO in handle read
    ("Hello, there!")
  5. Stop the Internet Computer client processes running on your local computer by running the following command:

    dfx stop

Next steps

This Quick start touched on only a few key steps to introduce the basic workflow you follow to develop programs of your own. There are more detailed examples and tutorials for you to explore in the Developer’s Guide and in the Motoko Language Reference.