Using an actor in the Hello, World! program

In Getting started, you had your first look at a simple program for the Internet Computer platform involving an actor object and asynchronous messaging. As the next step in learning to write programs that take advantage of actor-based messaging, this tutorial illustrates how to modify a traditional Hello, World! program to define an actor, then deploy and test your program using your local replica network.

Before you begin

Before starting the tutorial, verify the following:

  • You have downloaded and installed the SDK as described in Getting started.

  • You have stopped any network replica processes running on the local computer.

This tutorial takes approximately 20 minutes to complete.

Create a new project

To create a new project for this tutorial:

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

  2. Change to the folder you are using for your Internet Computer sample projects.

  3. Create a new project by running the following command:

    dfx new actor_hello
  4. Change to your project directory by running the following command:

    cd actor_hello

Verify the default configuration

You have already seen that creating a new project adds a default dfx.json configuration file to your project directory. In this tutorial, you only need to verify that the default settings reflect your new project name.

To check the default dfx.json configuration file:

  1. Open the dfx.json configuration file in a text editor.

  2. Check the default settings for the actor_hello project.

    For example:

      "canisters": {
        "actor_hello": {
          "frontend": {
            "entrypoint": "src/actor_hello/public/index.js"
          },
          "main": "src/actor_hello/main.mo"

    You can rename any of the files or directories specified in the dfx.json configuration file. If you make any changes, however, be sure that the names you use for your files and directories match the names specified in the dfx.json configuration file.

    If you plan to use the default directory and file names, no changes are necessary.

  3. Close the file to continue.

Modify the default template program

You have already seen that creating a new project creates a default src directory with a template main.mo file. In this tutorial, you modify the template code to create a simple "Hello, World!" program.

To modify the default template source code:

  1. Change to the source code directory for your project by running the following command:

    cd src/actor_hello
  2. Open the template main.mo file in a text editor and delete the existing content.

    The next step is to write a program that prints a statement like the traditional "Hello, World!" sample program. If you were writing this program to run on a platform other than the Internet Computer, the Motoko code might look similar to the following:

    func main() {
       print "Hello, World! from DFINITY\n"
       };
    main()

    You could also write the program in Motoko without the main function at all, like this:

    print "Hello, World! from DFINITY\n"

    To compile the program for the Internet Computer, however, your program must include an actor object with a public function.

  3. Copy and paste the following sample code into the main.mo file:

    import Debug "mo:base/Debug";
    actor HelloActor {
       public query func hello() : async () {
          Debug.print ("Hello, World from DFINITY \n");
       }
    };

    This code sample uses the public query func to define a query method because, in this case, the actor_hello program doesn’t make any changes to the state of the canister or perform any operations that would update the data you are accessing.

    For more information about using a query call, see query calls in Canisters include both program and state.

Build and deploy the program

You now have a program that you can compile into an executable WebAssembly module that you can deploy—using the canister model—on your local replica network.

To build the program executable:

  1. Build the WebAssembly executable by running the following command:

    dfx build --skip-frontend
  2. Start the Internet Computer network on your local computer by running the following command:

    dfx start --background
  3. Deploy your actor_hello project on the local network by running the following command:

    dfx canister install actor_hello

Query the canister

You now have a program deployed as a canister on your local replica network and can test your program by using the dfx canister call commands.

To test the program you have deployed on the local replica network:

  1. Use dfx canister call to call the hello function by running the following command:

    dfx canister call actor_hello hello
  2. Verify that the command returns the text specified for the hello function.

    For example, the program displays "Hello, World! from DFINITY" in output similar to the following:

    debug.print: Hello, World! from DFINITY
  3. Stop the Internet Computer processes running on your local computer by running the following command:

    dfx stop