Tutorial: Hello World Console

Let's write the most basic application: printing "Hello, world!" to the console.

You can follow along in zaplib/examples/tutorial_hello_world_console.

1. Cargo.toml

The Cargo.toml file is where you configure your project much like you would in a package.json. This one simply imports Zaplib locally. If you use Zaplib outside of this repo, you'd need to specify a version.

[package]
name = "tutorial_hello_world_console"
version = "0.0.1"
edition = "2021"

[dependencies]
zaplib = { path="../../main" }

2. src/main.rs

The src/main.rs file is the entrypoint for your application.

use zaplib::*;                          // import all Zaplib functions globally

struct App {}                           // normally this would hold state 

impl App {
    fn new(_cx: &mut Cx) -> App {                         
        App {}                          // initialize & return an empty App                     
    }

    fn handle(&mut self, _cx: &mut Cx, event: &mut Event) {  
        match event {                   
            Event::Construct => {       // match on the Construct event (the first event)
                log!("Hello, world!");  
            }
            _ => {}                     // ignore all other events
        }
    }
    fn draw(&mut self, _cx: &mut Cx) {}
}

main_app!(App);                        

Let's break it down a bit. (For now, try to ignore the &mut type annotations.) App is a struct that implements three methods:

  1. new returns an initialized App struct.
  2. handle is the entrypoint into Zaplib's event handling system. We will go in depth on various event types in a different tutorial. For now, we'll put our log!() call in the the Construct event.
  3. draw is called when requesting a draw. This will control what gets shown on the application window, which we don't use yet.

The call to main_app!() tells Zaplib to use the App struct for all its eventing and rendering.

3. Run the app natively

In your shell:

cargo run -p tutorial_hello_world_console

Hurray! It prints Hello, world! 🥳

Notice how this program currently never exits on its own. That behavior is similar to the web version, where the program doesn't exit until the browser window is closed. In our case here we don't have a native window yet, so terminate the program using CTRL+C.

3. Compile to WebAssembly

cargo zaplib build -p tutorial_hello_world_console

4. index.html

The index.html file simply imports the Zaplib runtime, and initializes it by pointing at the compiled WASM file for this example. If you use Zaplib outside of this repo, you'd likely use npm or yarn to install and import the Zaplib runtime.

<head>
    <meta charset="utf-8" />
</head>

<body>
    <script type="text/javascript" src="/zaplib/web/dist/zaplib_runtime.development.js"></script>
    <script>
        zaplib.initialize({
            wasmModule: 'target/wasm32-unknown-unknown/debug/tutorial_hello_world_console.wasm'
        });
    </script>
</body>

5. Run the server

In your shell:

cargo zaplib serve

5. Open the app in Chrome

http://localhost:3000/zaplib/examples/tutorial_hello_world_console

Open the browser console, and see how it has printed "Hello, world!".

Congratulations, you've written your first Zaplib program! 😄