DEV Community: Max

Building a Custom Shell in Rust from scratch

Max — Mon, 10 Feb 2025 07:37:09 +0000

Introduction

Building a custom REPL (Read-Eval-Print Loop) in Rust is a great way to deepen your understanding of system programming, async I/O, and command parsing. In this article, we'll walk through the process of creating a simple shell that can execute basic commands like echo, ls, and cd.

A REPL (Read-Eval-Print Loop) is an interactive programming environment that continuously reads user input, evaluates it, prints the result, and loops back for more input. Our shell will follow this same structure:

Read – Capture user input from standard input (stdin).
Evaluate – Convert input into a structured Command type and execute it.
Print – Display relevant output to the user via standard output (stdout).
Loop – Wait for the next command and repeat the cycle.

To keep things simple, our shell will support the following commands:

echo – Print text to the console.
ls – List files in the current directory.
pwd – Show the present working directory.
cd – Change directories.
touch – Create new files.
rm – Remove files.
cat – Read and display file contents.

Along with this guide, I've also created a YouTube video demonstrating the entire build process from start to finish, which you can check out here:

And the complete source code can be found here

Project setup

Before diving into implementation, let’s set up our Rust project and add the necessary dependencies. We'll use cargo, Rust’s package manager, to create a new project.

cargo new shell

This will create a new Rust project inside a shell/ directory with the usual Cargo.toml and src/main.rs files.

Dependencies

For this project we only need 2 dependencies:

Tokio – A powerful asynchronous runtime that allows us to handle user input and I/O operations efficiently.
Anyhow – A lightweight error-handling library that simplifies working with Result types.

Add them to your Cargo.toml file:

[dependencies] 
anyhow = "1.0.95" 
tokio = { version = "1.43.0", features = ["full"] }

Error handling

Error handling is a critical part of any shell, as we need to gracefully handle issues like missing files, invalid commands, and permission errors. Instead of manually defining a complex error-handling system, we’ll use the anyhow crate to simplify the process.

Why `anyhow`?

Rust’s standard error handling requires defining detailed Result<T, E> types for every function that can fail. While powerful, this can become cumbersome. anyhow provides a streamlined approach by allowing us to return a generic error type (anyhow::Error) that captures various failure cases without extra boilerplate.

Setting Up Error Handling

To integrate anyhow, create a new file called src/errors.rs and add:

pub type CrateResult<T> = anyhow::Result<T>;

This creates a reusable type alias, CrateResult<T>, which we’ll use throughout our code for functions that may return errors.

Now, import this module in main.rs so we can use it across our project:

mod errors;

With this in place, we can now handle errors more cleanly in our shell’s command execution and I/O operations.

I/O operations

Now that we’ve set up error handling, it’s time to implement I/O operations—the backbone of our REPL loop.

Setting Up the REPL Loop

We’ll run our REPL (Read-Eval-Print Loop) in a dedicated asynchronous task using tokio::spawn. While this isn’t strictly necessary, it’s a great example of managing async tasks in Rust.

Add the following code to main.rs:

use errors::CrateResult;
use tokio::{
    io::{AsyncBufReadExt, AsyncWriteExt},
    task::JoinHandle,
};

fn spawn_user_input_handler() -> JoinHandle<CrateResult<()>> {
    tokio::spawn(async {
        // Initialize stdin and stdout
        let stdin = tokio::io::stdin();
        let stdout = tokio::io::stdout();

        let mut reader = tokio::io::BufReader::new(stdin).lines();
        let mut stdout = tokio::io::BufWriter::new(stdout);

        stdout.write(b"Welcome to the shell!\n").await?;

        while let Ok(Some(line)) = reader.next_line().await {
            // Log user input for now (we'll process commands later)
            println!("User entered: {}", line);
        }

        Ok(())
    })
}

Breaking It Down:

tokio::spawn(async { ... }) → Runs the REPL loop in an async task.
BufReader::new(stdin).lines() → Reads user input line by line.
BufWriter::new(stdout) → Buffers output for improved performance.
Looping with reader.next_line().await → Continuously reads user input.
Logging input (println!) → Right now, we just print what the user types (we’ll process commands later).

Hooking It Up to `main`

Now, update main.rs to start the REPL loop and handle potential errors:

#[tokio::main]
async fn main() {
    let user_input_handler = spawn_user_input_handler().await;

    if let Ok(Err(e)) = user_input_handler {
        eprintln!("Error: {}", e);
    }
}

This ensures that if anything goes wrong during execution, we’ll log the error and exit cleanly.

Command handling

Now that our shell can read user input, we need a way to interpret and execute commands.

Since our shell supports a fixed set of commands, we’ll use an enum to represent them. Enums in Rust provide a safe, type-checked way to handle different command variants without relying on fragile string comparisons.

Defining the Command Enum

Create a new file src/command.rs and define our Command enum:

use anyhow::anyhow;

#[derive(Clone, Debug)]
pub enum Command {
    Exit,
    Echo(String),
    Ls,
    Pwd,
    Cd(String),
    Touch(String),
    Rm(String),
    Cat(String),
}

Each variant represents a command, and those requiring an argument (like echo, cd, touch, rm, and cat) store a String inside them.

Parsing User Input into Commands

To convert user input into a Command, we’ll implement TryFrom<&str> for Command:

impl TryFrom<&str> for Command {
    type Error = anyhow::Error;

    fn try_from(value: &str) -> Result<Self, Self::Error> {
        let split_value: Vec<&str> = value.split_whitespace().collect();

        match split_value[0] {
            "exit" => Ok(Command::Exit),
            "ls" => Ok(Command::Ls),
            "echo" => {
                if split_value.len() < 2 {
                    Err(anyhow!("echo command requires an argument"))
                } else {
                    Ok(Command::Echo(split_value[1..].join(" ")))
                }
            }
            "pwd" => Ok(Command::Pwd),
            "cd" => {
                if split_value.len() < 2 {
                    Err(anyhow!("cd command requires an argument"))
                } else {
                    Ok(Command::Cd(split_value[1..].join(" ")))
                }
            }
            "touch" => {
                if split_value.len() < 2 {
                    Err(anyhow!("touch command requires an argument"))
                } else {
                    Ok(Command::Touch(split_value[1..].join(" ")))
                }
            }
            "rm" => {
                if split_value.len() < 2 {
                    Err(anyhow!("rm command requires an argument"))
                } else {
                    Ok(Command::Rm(split_value[1..].join(" ")))
                }
            }
            "cat" => {
                println!("{}", split_value[1..].join(" "));
                if split_value.len() < 2 {
                    Err(anyhow!("cat command requires an argument"))
                } else {
                    Ok(Command::Cat(split_value[1..].join(" ")))
                }
            }

            _ => Err(anyhow!("Unknown command")),
        }
    }
}

Breaking It Down:

Splitting the input → We use .split_whitespace() to break the input into words.
Matching commands → We check the first word (split_value[0]) to extract the user’s command.
Handling arguments → Commands like echo, cd, etc., require additional arguments, so we check split_value.len() < 2.
Error handling → We return Err(anyhow!(...)) if the command is unknown or missing.

Integrating Command Parsing into `main.rs`

Now, import the Command module at the top of main.rs:

use command::Command;

mod command;

Let’s integrate this new type into src/main.rs to provide uniform handling for user inputs. Create the below function:

async fn handle_new_line(line: &str) -> CrateResult<Command> {
    // Leverages the TryFrom trait implemented above
    let command: Command = line.try_into()?;

    match command.clone() {
        // Placeholder
        _ => {}
    }
    Ok(command)
}

Now update the REPL loop in spawn_user_input_handler to call this function on user’s inputs:

while let Ok(Some(line)) = reader.next_line().await {
    let command = handle_new_line(&line).await;

    if let Ok(command) = &command {
        match command {
            _ => {}
        }
    } else {
        eprintln!("Error parsing command: {}", command.err().unwrap());
    }
}

At this point, our shell can parse user input’s and match commands, but the command execution is incomplete. Next, we’ll improve logging, then implement the command logic for each, starting with filesystem operations like ls, pwd, cd, and file manipulation.

Improve logging

Let’s improve the logging for our shell so that using it feels more familiar. To do this we should first create a helper method that returns the Shell’s current directory, we will need to log this after each command to emulate a normal Shell’s behaviour.

Create the file src/helpers.rs and add this method:

use crate::errors::CrateResult;

pub fn pwd() -> CrateResult<String> {
    let current_dir = std::env::current_dir()?;

    Ok(current_dir.display().to_string())
}

And import this new file into our module:

mod helpers;

Now lets modify the logging inside our REPL loop to print “>” in the terminal before users enter their commands and also to log the users present working directory after each command. Update your spawn_user_input_handler to match the following:

fn spawn_user_input_handler() -> JoinHandle<CrateResult<()>> {
    tokio::spawn(async {
        let stdin = tokio::io::stdin();
        let stdout = tokio::io::stdout();

        let mut reader = tokio::io::BufReader::new(stdin).lines();
        let mut stdout = tokio::io::BufWriter::new(stdout);

        stdout.write(b"Welcome to the shell!\n").await?;

        stdout.write(pwd()?.as_bytes()).await?;
        stdout.write(b"\n>").await?;
        stdout.flush().await?;

        while let Ok(Some(line)) = reader.next_line().await {
            let command = handle_new_line(&line).await;

            if let Ok(command) = &command {
                match command {
                    _ => {}
                }
            } else {
                eprintln!("Error parsing command: {}", command.err().unwrap());
            }

            stdout.write(pwd()?.as_bytes()).await?;
            stdout.write(b"\n>").await?;
            stdout.flush().await?;
        }

        Ok(())
    })
}

Commands

Now we have built a system to interpret and execute commands, now we need to implement the logic for each.

Exit

Let’s first add the exit command so user’s can close the terminal, to do this modify the while loop in src/main.rs to break when this command is detected:

if let Ok(command) = &command {
    match command {
        Command::Exit => {
            println!("Exiting...");
            break;
        }
        _ => {}
    }
}

Echo

The echo command simply prints out the arguments given to it, which is useful for displaying messages or testing output. Handle the Echo command in handle_new_line:

Command::Echo(s) => {
    println!("{}", s);
}

Ls

The ls command lists files in the current directory.

Create a helper function in src/helpers.rs:

pub fn ls() -> CrateResult<()> {
    let entries = fs::read_dir(".")?;

    for entry in entries {
        let entry = entry?;
        println!("{}", entry.file_name().to_string_lossy());
    }

    Ok(())
}

Handle Ls in handle_new_line:

Command::Ls => {
    helpers::ls()?;
}

Pwd

The pwd command prints the current working directory, we’ve already defined this function so just add the relevant match case in handle_new_line:

Command::Pwd => {
    println!("{}", helpers::pwd()?);
}

Cd

The cd command changes the current directory.

Create a helper function in src/helpers.rs:

pub fn cd(path: &str) -> CrateResult<()> {
    std::env::set_current_dir(path)?;
    Ok(())
}

Handle Cd in handle_new_line:

Command::Cd(s) => {
    helpers::cd(&s)?;
}

Touch

The touch command creates an empty file.

Create a helper function in src/helpers.rs:

pub fn touch(path: &str) -> CrateResult<()> {
    fs::File::create(path)?;
    Ok(())
}

Handle Touch in handle_new_line:

Command::Touch(s) => {
    helpers::touch(&s)?;
}

Rm

The rm command removes a file.

Create a helper function in src/helpers.rs

pub fn rm(path: &str) -> CrateResult<()> {
    fs::remove_file(path)?;
    Ok(())
}

Handle Rm in handle_new_line:

Command::Rm(s) => {
    helpers::rm(&s)?;
}

Cat

The cat command reads and prints the contents of a file.

Create a helper function in src/helpers.rs:

pub fn cat(path: &str) -> CrateResult<String> {
    let pwd = pwd()?;
    let joined_path = std::path::Path::new(&pwd).join(path);
    let contents = fs::read_to_string(joined_path)?;
    Ok(contents)
}

Handle Cat in handle_new_line:

Command::Cat(s) => {
    let contents = helpers::cat(&s)?;
    println!("{}", contents);
}

Conclusion

We’ve successfully built a simple REPL/Shell in Rust that supports basic commands like ls, pwd, cd, touch, rm, and cat. The architecture is modular, making it easy to extend with additional commands.

This is just the beginning! You can add more features, such as:

Command history
Autocompletion
Piping commands
Background execution

If you want to dive deeper, check out the accompanying YouTube video that walks through the build process step by step

ASMR Programming - REPL Shell in Rust 🦀 (Outside - NO TALKING) - YouTube

Happy coding! 🚀

Recreating the Apple Calculator in Rust using Tauri, Yew and Tailwind

Max — Thu, 30 Nov 2023 22:05:40 +0000

Introduction

In this tutorial, we will be rebuilding the Apple calculator using Rust. This project is designed to be a stimulating challenge, providing a hands-on experience with several key technologies:

Tauri: An innovative framework for building lightweight desktop applications.
Yew: A modern Rust framework for creating frontend web apps.
TailwindCSS: A utility-first CSS framework for rapid UI development.

At a high-level the Apple calculator can be broken down into some key areas of functionality:

Numeric Buttons (0-9)
Operational Buttons (Add, Subtract, Multiply, Divide, Equals)
Special Function Buttons: Percentage, Invert Sign, Decimal Point, Clear

We will be working through these step-by-step in this tutorial, creating reusable components where possible. Here is the source code

Additionally, to complement this guide, I have prepared YouTube video demonstrating the entire build process. You can watch it here:

And if you want to see more of my work, feel free to explore these links: Twitter YouTube

Let's get started!

Setup

Run the following command in your console:

yarn create tauri-app

Answer the prompts as follows:

Project name: calculator-app
Frontend language: Rust (cargo)
UI template: Yew - (https://yew.rs/)

Setup tailwind

Integrating Tailwind CSS into our project will give us a powerful yet simple way to style our components. First, ensure you have npx installed, a tool that allows executing npm package binaries. It's a part of npm, and you can learn more about it here.

To create a Tailwind configuration file, run:

npx tailwindcss init

This command generates a tailwind.config.js file in your project's root directory. Modify this file to include our Rust files and also add the colors we need for our button backgrounds:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.rs"],
  theme: {
    extend: {
      colors: {
        background: "#172425",
        darkGrey: "#2d3131",
        lightGrey: "#4d5250",
        orange: "#fd8d18",
      },
    },
  },
  plugins: [],
};

Next, create a CSS file named src/input.css and insert the following Tailwind directives:

@tailwind base;
@tailwind components;
@tailwind utilities;

To integrate this stylesheet into your app, update the index.html file in the root directory:

<link href="output.css" data-trunk rel="css" />

This ensures that the generated CSS is included in the app.

Title bar style:

The Apple calculator doesn't have the title bar normal programs do, let's make some modifications to our Tauri config to fit that style:

{
.  ...
  "tauri": {
    ...

    "windows": [
      {
        "titleBarStyle": "Transparent",
        "title": ""
      }
    ]
  }
}

Setting up the calculator

Let's first setup the states we need for our calculator, these are the main states we will need:

temp_value: Tracks the current input from the user.
memory: Stores the ongoing calculation or result.
action: Holds the current action (like Add, Subtract).
trailing_dot: If the decimal point was the last input with no subsequent digits.
has_dot_pressed: If the temp_value has a decimal point

Modify src/app.rs to include the states:

#[function_component(App)]
pub fn app() -> Html {
    let temp_value: UseStateHandle<Option<f32>> = use_state(|| None);
    let memory: UseStateHandle<f32> = use_state(|| 0.0);
    let action: UseStateHandle<Option<Action>> = use_state(|| None);
    let trailing_dot: UseStateHandle<bool> = use_state(|| false);
    let has_dot_pressed: UseStateHandle<bool> = use_state(|| false);
}

Let's also add a display for the current calculator value, showing temp_value if it exists, otherwise memory:

let display_value: f32 = {
    if let Some(i) = *temp_value {
        i
    } else {
        *memory
    }
};

html! {
    <div class={classes!("h-screen", "w-screen", "bg-background", "flex-col", "flex")}>
        <div class={classes!("flex", "justify-end", "text-5xl", "pr-2", "py-1")}>
            {display_value}{match *trailing_dot {
              true => ".",
              false => "",
            }}
        </div>
    </div>
}

🐣 We now have the very basic beginnings of our calculator:

Let's continue giving it life!

Defining Actions and Operations

Within src/app.rs let's create an enum to represent calculator operations, this enum will be used for basic arithmetic. Let's call this enum Action and add a way to caste it to a string, so that we can easily display it in our UI later on:

#[derive(Clone, Copy, PartialEq)]
pub enum Action {
    Add,
    Subtract,
    Multiply,
    Divide,
    Equals,
}

impl Action {
    pub fn to_string(&self) -> String {
        match self {
            Action::Add => "+".to_string(),
            Action::Subtract => "-".to_string(),
            Action::Multiply => "x".to_string(),
            Action::Divide => "÷".to_string(),
            Action::Equals => "=".to_string(),
        }
    }
}

Button Components

For a unified aesthetic across our calculator, create src/buttons/button_styles.rs. This file will contain the common styles for our buttons, ensuring consistency and ease of maintenance:

use yew::{classes, Classes};

pub fn get_button_styles(extra_classes: Classes) -> Classes {
    classes!(vec![
        classes!(
            "flex",
            "flex-1",
            "items-center",
            "justify-center",
            "rounded-none",
            "border-[0.25px]",
            "border-black",
            "text-xl",
            "font-bold",
            "hover:border-black" // override base styles
        ),
        extra_classes
    ])
}

Now, let's develop two primary button components: NumberButton for digits and ActionButton for operations.

Number button:

This component handles digit inputs (0-9). It takes a floating-point value, displays it, and invokes the specified callback function upon interaction:

use yew::{classes, function_component, html, Callback, Html, Properties};

use crate::buttons::button_styles::get_button_styles;

#[derive(Clone, PartialEq, Properties)]
pub struct Props {
    pub value: f32,
    pub onclick: Callback<f32>,
}

#[function_component]
pub fn NumberButton(Props { value, onclick }: &Props) -> Html {
    let value = *value;

    html!(
      <button class={get_button_styles(classes!("bg-lightGrey", "active:bg-[rgb(180,180,180)]"))} onclick={onclick.reform(move |_| value)}>
        {value}
      </button>
    )
}

Action button:

This component, slightly more complex, handles operational inputs like Add, Subtract, etc. It displays the provided action and communicates it back when the button is pressed. Additionally, it changes its style based on the whether this action button is currently the selected action:

use yew::{classes, function_component, html, Callback, Html, Properties};

use crate::{app::Action, buttons::button_styles::get_button_styles};

#[derive(Clone, PartialEq, Properties)]
pub struct Props {
    pub action: Action,
    pub selected_action: Option<Action>,
    pub onclick: Callback<Action>,
}

#[function_component]
pub fn ActionButton(
    Props {
        action,
        selected_action,
        onclick,
    }: &Props,
) -> Html {
    let action = *action;

    let is_selected = {
        if let Some(selected_action) = selected_action {
            *selected_action == action
        } else {
            false
        }
    };

    let classes = {
        if is_selected {
            classes!(
                "border-[1.2px]",
                "border-black",
                "h-full",
                "w-full",
                "flex",
                "items-center",
                "justify-center"
            )
        } else {
            classes!("")
        }
    };

    html!(
      <button class={get_button_styles(classes!("bg-orange", "active:bg-[rgb(184,115,51)]"))} onclick={onclick.reform(move |_| action)}>
          <div class={classes}>{action.to_string()}</div>
      </button>
    )
}

To make these button components accessible in our main app, we create src/buttons.rs:

pub mod action_button;
pub mod button_styles;
pub mod number_button;

Then, import this module in src/main.rs for seamless integration:

mod buttons;

Calculator top row

First, let's define the top row of our calculator's interface, update your html in src/app.rs to be:

html! {
  <div class={classes!("h-screen", "w-screen", "bg-background", "flex-col", "flex")}>
    <div class={classes!("flex", "justify-end", "text-5xl", "pr-2", "py-1")}>
      {display_value}{match *trailing_dot {
        true => ".",
        false => "",
      }}
    </div>
    <div class={classes!("flex", "flex-1", "flex-row")}>
      <button onclick={clear_state} class={get_button_styles(classes!("bg-darkGrey","active:bg-lightGrey"))}>
        {match clear_all {
          true => "AC",
          false => "C",
        }}
      </button>
      <button onclick={invert_sign} class={get_button_styles(classes!("bg-darkGrey","active:bg-lightGrey"))}>
        {"±"}
      </button>
      <button onclick={apply_percentage} class={get_button_styles(classes!("bg-darkGrey","active:bg-lightGrey"))}>
        {"%"}
      </button>
      <ActionButton action={Action::Divide} onclick={handle_action_button.clone()} selected_action={*action}  />
    </div>
  </div>
}

We have some missing functionality required to support these new buttons:

clear_state - Clearing
invert_sign - Inverting the sign (- to +)
apply_percentage - Applying a percentage to the value
handle_action_button - Handling actions

Let's walk through each of these

Clearing:

There are 2 distinct types of state clearing; CE (Clear everything) or C (Clear), this is how most calculators function and you'll notice on the Apple calculator that the clear button text changes depending on this state. When we clear everything, the major difference is that memory is also cleared, we only want to do this if; there is no temporary value, current action or a trailing dot. Let's implement this:

let clear_all = {
    if (*temp_value).is_some() || (*action).is_some() || *trailing_dot {
        false
    } else {
        true
    }
};

let clear_state = {
    let temp_value = temp_value.clone();
    let action = action.clone();
    let memory = memory.clone();
    let trailing_dot = trailing_dot.clone();
    let has_dot_pressed = has_dot_pressed.clone();

    Callback::from(move |_| {
        if clear_all {
            memory.set(0.0);
            temp_value.set(None);
            action.set(None);
        } else {
            action.set(None);
            temp_value.set(None);
        }

        trailing_dot.set(false);
        has_dot_pressed.set(false);
    })
};

Inverting the sign & applying the percentage:

The methods invert_sign and apply_percentage are similar; they either modify temp_value if it exists, otherwise they modify memory:

let invert_sign = {
    let temp_value = temp_value.clone();
    let memory = memory.clone();

    Callback::from(move |_| {
        if let Some(i) = *temp_value {
            temp_value.set(Some(i * -1.0));
        } else {
            memory.set(*memory * -1.0);
        }
    })
};

let apply_percentage = {
    let temp_value = temp_value.clone();
    let memory = memory.clone();

    Callback::from(move |_| {
        if let Some(i) = *temp_value {
            temp_value.set(Some(i / 100.0));
        } else {
            memory.set(*memory / 100.0);
        }
    })
};

Handle the action button:

This is a core piece of our functionality; handling actions. This essentially works by applying actions to our temporary value and memory to get our new result.

You'll notice this method applies the previous action that was pressed, not the new action. This is because when you press an action button on the calculator it doesn't immediately apply it, you then need to type in a temporary value to operate against. This action is processed when the next action button is pressed, typically this is equals but it also natively supports chaining calculations:

let handle_action_button = {
    let temp_value = temp_value.clone();
    let memory = memory.clone();
    let action = action.clone();
    let trailing_dot = trailing_dot.clone();
    let has_dot_pressed = has_dot_pressed.clone();

    Callback::from(move |passed_action: Action| {
        // If there is an action already pressed and a temporary_value, then we want to apply that previous action
        if let (Some(existing_action), Some(temp_value)) = (*action, *temp_value) {
            match existing_action {
                Action::Add => {
                    memory.set(*memory + temp_value);
                }
                Action::Subtract => {
                    memory.set(*memory - temp_value);
                }
                Action::Multiply => {
                    memory.set(*memory * temp_value);
                }
                Action::Divide => {
                    memory.set(*memory / temp_value);
                }
                Action::Equals => {
                    memory.set(temp_value);
                }
            }
        } else {
            let memory_update = match *temp_value {
                Some(i) => i,
                None => *memory,
            };

            memory.set(memory_update);
        }
        if passed_action != Action::Equals {
            action.set(Some(passed_action));
        } else {
            action.set(None);
        }

        // Reset our temporary states
        temp_value.set(None);
        trailing_dot.set(false);
        has_dot_pressed.set(false);
    })
};

We will now have a pretty sleak, but somewhat useless calculator:

Major button rows

Next, we'll add 3 additional rows, which will support 1-9 number buttons and 3 additional actions: Multiply, Subtract and Add. Insert the following code into the HTML macro in src/app.rs, positioning it below the previously created top row:

  <div class={classes!("flex", "flex-row", "flex-1")}>
    <NumberButton value={7.0}
      onclick={handle_number_button_press.clone()} />
    <NumberButton value={8.0}
      onclick={handle_number_button_press.clone()} />
    <NumberButton value={9.0}
      onclick={handle_number_button_press.clone()} />
    <ActionButton action={Action::Multiply}
      onclick={handle_action_button_press.clone()} selected_action={*action} />
  </div>
  <div class={classes!("flex", "flex-row", "flex-1")}>
    <NumberButton value={4.0}
      onclick={handle_number_button_press.clone()} />
    <NumberButton value={5.0}
      onclick={handle_number_button_press.clone()} />
    <NumberButton value={6.0}
      onclick={handle_number_button_press.clone()} />
    <ActionButton action={Action::Subtract}
      onclick={handle_action_button_press.clone()} selected_action={*action} />
  </div>
  <div class={classes!("flex", "flex-row", "flex-1")}>
    <NumberButton value={1.0}
      onclick={handle_number_button_press.clone()} />
    <NumberButton value={2.0}
      onclick={handle_number_button_press.clone()} />
    <NumberButton value={3.0}
      onclick={handle_number_button_press.clone()} />
    <ActionButton action={Action::Add}
      onclick={handle_action_button_press.clone()} selected_action={*action} />
  </div>

We have most of the functionality already to support this, the only missing part is the functionality required to support number buttons. To do this, we need to handle appending numbers to temp_value, and also managing decimal points:

let handle_number_button = {
    let temp_value = temp_value.clone();
    let trailing_dot = trailing_dot.clone();
    let has_dot_pressed = has_dot_pressed.clone();

    Callback::from(move |value: f32| {
        if let Some(i) = *temp_value {
            let trailing_dot_string = match *trailing_dot {
                true => ".",
                false => "",
            };

            let new_value = format!("{}{}{}", i, trailing_dot_string, value);

            temp_value.set(Some(new_value.parse::<f32>().unwrap()));
        } else {
            if *trailing_dot {
                let value = format!("0.{}", value).parse::<f32>().unwrap();
                temp_value.set(Some(value));
            } else {
                temp_value.set(Some(value));
            }
        }

        if *trailing_dot {
            trailing_dot.set(false);
            has_dot_pressed.set(true);
        }
    })
};

Our calculator will now look like this and be almost complete:

Final row

Finally, we add the bottom row to our calculator, completing the UI:

<div class={classes!("flex", "flex-1", "flex-row")}>
    <div class={classes!("flex", "flex-1")}>
        <NumberButton value={0.0} onclick={handle_number_button.clone()} />
    </div>
    <div class={classes!("flex", "flex-1")}>
        <button onclick={handle_dot_press} class={get_button_styles(classes!("bg-lightGrey"))}>
            {"."}
        </button>
        <ActionButton action={Action::Equals} onclick={handle_action_button.clone()} selected_action={*action}  />
    </div>
</div>

Great, the only missing functionality for this is handle_dot_press, this function ensures that only one decimal point can be included in a number, ensuring correctness:

let handle_dot_press = {
    let trailing_dot = trailing_dot.clone();
    let has_dot_pressed = has_dot_pressed.clone();

    Callback::from(move |_| {
        if *has_dot_pressed {
            return;
        }

        trailing_dot.set(true);
    })
};

Done!

🥳 Congratulations! We've successfully built a fully functional calculator that mimics the Apple calculator's design and functionality.

I hope you found this tutorial insightful and engaging. For more content and updates, connect with me on Twitter and YouTube.

Create a Full stack Rust desktop App with Tauri, Yew and Tailwind CSS

Max — Thu, 16 Nov 2023 22:44:08 +0000

In this tutorial, we're going to be building a desktop Pomodoro timer app using Tauri and Yew. I especially like this build because it uses rust for every single aspect (except CSS of course). If you're unfamiliar with the the Pomodoro technique, it is a time management method shown to help maintain productivity throughout your day, which is especially important in fields like software development.

We'll be using some community packages; gloo-timers for timer functionality and yew-feather for icons. Additionally, we'll style our components using Tailwind, and I'll guide you through its setup in this tutorial.

Along with this build I've put together a YouTube video demonstrating the build from start to finish, can see that here:

Also you can find the source code here

Project setup

Let's start by setting up the project, for this we will use the Tauri CLI. This command requires yarn, which can be installed following the instructions here.

Run the following command in your console:

yarn create tauri-app

Answer the prompts as follows:

Project name: pomodoro-app
Frontend language: Rust (cargo)
UI template: Yew - (https://yew.rs/)

After completing these steps, you'll have a pomodoro-app directory with the necessary boilerplate to kickstart our Tauri app. Note: If any dependencies are missing, the CLI will guide you through the installation.

Install Dependencies:

Let's install our additional dependencies now:

cargo add yew-feather gloo-timers

Enable System Tray:

To display our timer's status in the system tray, we need to enable Tauri's system-tray functionality. Begin by updating the Tauri dependency in src-tauri/cargo.toml to include the system-tray feature:

tauri = { version = "1.5", features = ["shell-open", "system-tray"] }

Next, configure an icon for the system tray. Modify the tauri field in src-tauri/tauri.conf.json to specify an icon path:

{
  ...
  "tauri": {
    "systemTray": {
      "iconPath": "icons/icon.png",
      "iconAsTemplate": true
    },
    ...
  }
}

Ensure to keep the existing settings intact while adding the systemTray object.

After these changes, reinstall the Tauri app packages:

cargo install --path ./src-tauri

Improve Development Experience:

Enhancing the development workflow is crucial for efficiency. Currently, closing the window terminates the server, and there's no way to reopen the window once closed. Let's refine our src-tauri/main.rs file to address these issues:

fn main() {
    // Create the system tray object
    let tray = SystemTray::new();

    tauri::Builder::default()
        .on_window_event(|event| {
            match event.event() {
                // Prevents the dev server from exiting when we close the window
                tauri::WindowEvent::CloseRequested { api, .. } => {
                    event.window().hide().unwrap();
                    api.prevent_close();
                }
                _ => {}
            }
        })
        // Include the system tray and open the window when the icon is pressed
        .system_tray(tray)
        .on_system_tray_event(|app, event| match event {
            SystemTrayEvent::LeftClick {
                position: _,
                size: _,
                ..
            } => {
                let window = app.get_window("main").unwrap();
                window.show().unwrap();
            }
            _ => (),
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

This update ensures that closing the window hides it instead of shutting down the server, and clicking on the system tray icon will reopen the window.

Setup Tailwind:

To create a Tailwind configuration file, run:

npx tailwindcss init

This command generates a tailwind.config.js file in your project's root directory. Modify this file to include our Rust files:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.rs"],
  theme: {
    extend: {},
  },
  plugins: [],
};

Next, create a CSS file named src/input.css and insert the following Tailwind directives:

@tailwind base;
@tailwind components;
@tailwind utilities;

To integrate this stylesheet into your app, update the index.html file in the root directory:

<link href="output.css" data-trunk rel="css" />

This ensures that the generated CSS is included in the app.

Start Services:

With the setup complete, it's time to start the development server and the Tailwind watcher service. Open two separate terminals and execute the following commands:

Tauri Dev Server:

cargo tauri dev

Tailwind Watcher Service:

npx tailwindcss -i ./src/input.css -o ./output.css --watch

These commands will start the Tauri development server and initiate Tailwind's process to watch for any changes in your CSS file, ensuring real-time updates.

Timer

State hooks:

To manage our timer, we'll use three state hooks in src/app.rs. These hooks are crucial for handling different aspects of our timer's functionality:

session_length: Determines the duration of a session, allowing users to adjust it with buttons.
timer_duration: Tracks the elapsed time in a work or break session.
timer_state: Manages three distinct states of the timer - Paused, Running, and Break.

Update src/app.rs with the following code to define these states:

use yew::prelude::*;

#[derive(PartialEq, Copy, Clone, Debug)]
pub enum TimerState {
    Paused,
    Running,
    Break,
}

#[function_component(App)]
pub fn app() -> Html {
    let session_length = use_state(|| 25 * 60); // Default 25 minutes
    let timer_duration = use_state(|| 0);
    let timer_state = use_state(|| TimerState::Paused);

    html! {
        <div class={classes!("flex", "items-center", "justify-center", "flex-col", "h-screen")}>
            {"Pomodoro Timer"}
        </div>
    }
}

Timer Logic:

Next, we'll implement the logic to update timer_duration every second. We'll use a use_effect_with_deps to create a timer that updates our state:

use_effect_with_deps(
    move |props| {
        let (timer_duration, timer_state, _) = props.clone();

        let timeout = Timeout::new(1_000, move || {
            if *timer_state != TimerState::Paused {
                timer_duration.set(*timer_duration + 1);
            }
        });

        move || {
            timeout.cancel();
        }
    },
    (
        timer_duration.clone(),
        timer_state.clone(),
        session_length.clone(),
    ),
);

This sets up a one-second timeout updating the timer_duration, unless the timer is paused. When the component unmounts, the timeout is canceled. We also need to clone our states multiple times, so we can move the ownership into the use_effect_with_deps closure and then the Timeout::new closure.

Timer UI:

For the timer display, we'll be formatting the time into MM:SS format, create src/helpers.rs and add the following function for time formatting:

pub fn format_time(seconds: u32) -> String {
    let minutes = seconds / 60;
    let seconds = seconds % 60;
    format!("{:02}:{:02}", minutes, seconds)
}

Include this helper in src/main.rs:

mod helpers;

Now let's create a directory to hold our UI components: src/components and create the file src/components/timer_display.rs for the timer UI. This component will display the timer and the buttons required to increase our session length. Let's first define the imports, props and integrate the MM::SS formatting:

use yew::prelude::*;
use crate::{app::TimerState, helpers::format_time};

// Define the component's properties
#[derive(Clone, PartialEq, Properties)]
pub struct Props {
    pub timer_state: UseStateHandle<TimerState>,
    pub timer_duration: UseStateHandle<u32>,
    pub session_length: UseStateHandle<u32>,
}

#[function_component]
pub fn TimerDisplay(props: &Props) -> Html {
    let is_expired = *props.timer_duration > *props.session_length;

    let get_session_display: String = {
        let Props {
            timer_duration,
            session_length,
            ..
        } = props.clone();

        if is_expired {
            format_time(*timer_duration)
        } else {
            format_time(*session_length - *timer_duration)
        }
    };

    html! {
        <div class={classes!("flex", "flex-col", "space-y-2", "items-center", "mb-3")}>
          <p class={classes!("text-5xl", "min-w-[50px]", "text-right")}>
              {get_session_length}
          </p>
        </div>
    }
}

We need to allow our app to have access to this component, do this by creating the file src/components.rs and exposing the timer_display module:

pub mod timer_display;

Finally, integrate the TimerDisplay component in src/app.rs:

html! {
    <div class={classes!("flex", "items-center", "justify-center", "flex-col", "h-screen")}>
        <TimerDisplay timer_state={timer_state.clone()} timer_duration={timer_duration.clone()} session_length={session_length.clone()} />
    </div>
}

Congratulations 🎉, we now have a really basic viewer for our time remaining:

Session indicator:

Currently it's a bit confusing what is going on with the timer, let's resolve this by creating a simple indicator to display the timer state. This requires an additional method in timer_display.rs:

let session_state_display = {
    let timer_state = props.timer_state.clone();

    match *timer_state {
        TimerState::Paused => "Paused".to_string(),
        TimerState::Break => {
            if isExpired {
                "Finished break".to_string()
            } else {
                "On break".to_string()
            }
        }
        TimerState::Running => {
            if isExpired {
                "Finished session".to_string()
            } else {
                "In session".to_string()
            }
        }
    }
};

We will integrate this method into our UI later on in the tutorial.

Adjusting Session Length:

For dynamic control over the session length, we will use Callback closures. These methods will be triggered by buttons to increase and decrease the session length, let's define them:

let increase_session_length = {
    let session_length = props.session_length.clone();

    Callback::from(move |_: ()| {
        session_length.set(*session_length + 60 * 5); // Increase by 5 minutes
    })
};

let decrease_session_length = {
    let session_length = props.session_length.clone();
    Callback::from(move |_: ()| {
        session_length.set(*session_length - 60 * 5); // Decrease by 5 minutes
    })
};

Finally, we integrate all the logic we've developed into our UI with proper styling:

html! {
    <div class={classes!("flex", "flex-col", "space-y-2", "items-center")}>
        <div class={classes!("flex", "flex-row", "space-x-3")}>
            <button onclick={move |_| {
                decrease_session_length.emit(());
            }} class={classes!("p-2", "border-2", "border-red-500")}>
                { "- 5" }
            </button>
            <p class={classes!("text-5xl")}>
                {get_session_length}
            </p>
            <button onclick={move |_| {
                increase_session_length.emit(());
            }} class={classes!("p-2", "border-2", "border-green-500")}>
                { "+ 5" }
            </button>
        </div>
        {session_state_display}
    </div>
}

Our application will now have improved controls, allowing us to increase and decrease the timer state and it will also display more information, making the UI easier to understand.

System Tray Updating:

To manage and display the timer's status in the system tray, we need to define the necessary data structures and functions. Start by declaring a struct for setting the tray title and the required wasm method:

#[derive(Serialize, Deserialize)]
struct SetTitleArgs<'a> {
    title: &'a str,
}

// Defines an async Rust function to call Tauri, used for updating the system tray state.
#[wasm_bindgen]
extern "C" {
    #[wasm_bindgen(js_namespace = ["window", "__TAURI__", "tauri"])]
    async fn invoke(cmd: &str, args: JsValue) -> JsValue;
}

Then, create a function that determines the appropriate tray title based on the current state:

pub fn get_tray_title(timer_state: TimerState, timer_duration: u32, session_length: u32) -> String {
    match timer_state {
        TimerState::Paused => String::from("Paused"),
        TimerState::Running => {
            if timer_duration >= session_length {
                return format!("Finished session: {}", format_time(timer_duration));
            }
            return format!(
                "In session: {}",
                format_time(session_length - timer_duration)
            );
        }
        TimerState::Break => {
            if timer_duration >= session_length {
                return format!("Finished break: {}", format_time(timer_duration));
            }
            return format!("Break: {}", format_time(session_length - timer_duration));
        }
    }
}

Inside src/app.rs, update the use_effect_with_deps to handle tray title updates, add the below snippet under the let timeout = ... declaration:

let (timer_duration, timer_state, session_length) = props.clone();

// Spawn a thread so that it can await the async call
spawn_local(async move {
    let args = to_value(&SetTitleArgs {
        title: get_tray_title(*timer_state, *timer_duration, *session_length).as_str(),
    })
    .unwrap();

    invoke("set_title", args).await;
});

For the Tauri application in src-tauri/src/main.rs, implement the set_title command to update the system tray:

#[tauri::command]
async fn set_title(app_handle: tauri::AppHandle, title: String) {
    if let Err(e) = app_handle.tray_handle().set_title(&title) {
        eprintln!("error updating timer: {}", e);
    }
}

Add this to your tauri::builder::default() under .on_system_tray_event:

.invoke_handler(tauri::generate_handler![set_title])

Timer Controls:

We will now implement the core timer controls, allowing us to start, pause, reset the timer, and initiate or finish a break. Create the file src/components/timer_controls.rs and let's first define our imports, required props and TimerControl declaration:

use yew::prelude::*;
use yew_feather::{Coffee, Pause, Play, RefreshCcw};
use crate::app::TimerState;

#[derive(Clone, PartialEq, Properties)]
pub struct Props {
    pub timer_state: UseStateHandle<TimerState>,
    pub timer_duration: UseStateHandle<u32>,
    pub session_length: UseStateHandle<u32>,
}

#[function_component]
pub fn TimerControls(props: &Props) -> Html {
    let Props {
        timer_state,
        timer_duration,
        session_length,
    } = props;
}

Callbacks:

To handle the various user interactions, we will need to declare a variety of Callback<()> instances, each altering the state in a unique way:

let start_timer: Callback<()> = {
    let timer_state = timer_state.clone();

    Callback::from(move |_| {
        timer_state.set(TimerState::Running);
    })
};

let pause_timer: Callback<()> = {
    let timer_state = timer_state.clone();

    Callback::from(move |_| {
        timer_state.set(TimerState::Paused);
    })
};

let reset_timer: Callback<()> = {
    let timer_state = timer_state.clone();
    let timer_duration = timer_duration.clone();
    let session_length = session_length.clone();

    Callback::from(move |_| {
        timer_state.set(TimerState::Paused);
        timer_duration.set(0);
        session_length.set(25 * 60); // Reset to 25 minute session time
    })
};

let take_break: Callback<()> = {
    let timer_state = timer_state.clone();
    let timer_duration = timer_duration.clone();
    let session_length = session_length.clone();

    Callback::from(move |_| {
        timer_state.set(TimerState::Break);
        timer_duration.set(0);
        session_length.set(5 * 60); // 5 minute break time
    })
};

let finish_break: Callback<()> = {
    let timer_state = timer_state.clone();
    let timer_duration = timer_duration.clone();
    let session_length = session_length.clone();

    Callback::from(move |_| {
        timer_state.set(TimerState::Running);
        timer_duration.set(0);
        session_length.set(25 * 60); // Reset state to 25 minutes
    })
};

Rendering the buttons:

The returned HTML depends on the timer_state, we want to return varying controls to the user depending on whether the timer is; Running, Paused or Break. Let's use a match block to handle this:

match **timer_state {
    TimerState::Running => {
        html!(
          <div class={classes!("flex", "flex-row", "space-x-2")}>
            <button class={classes!("p-3")} onclick={move |_| {
              take_break.emit(());
            }}>
              <Coffee />
            </button>
            <button class={classes!("p-3")} onclick={move |_| {
              pause_timer.emit(());
            }}>
              <Pause />
            </button>
            <button class={classes!("p-3")} onclick={move |_| {
              reset_timer.emit(());
            }}>
              <RefreshCcw />
            </button>
          </div>
        )
    }
    TimerState::Paused => {
        html!(
          <div class={classes!("flex", "flex-row", "space-x-2")}>
            <button class={classes!("p-3")} onclick={move |_| {
              take_break.emit(());
            }}>
              <Coffee />
            </button>
            <button class={classes!("p-3")} onclick={move |_| {
              start_timer.emit(());
            }}>
              <Play />
            </button>
            <button class={classes!("p-3")} onclick={move |_| {
              reset_timer.emit(());
            }}>
              <RefreshCcw />
            </button>
          </div>
        )
    }
    TimerState::Break => {
        html!(
          <div class={classes!("flex", "flex-row", "space-x-2")}>
            <button class={classes!("p-3")} onclick={move |_| {
              finish_break.emit(());
            }}>
              <Play />
            </button>
          </div>
        )
    }
}

And finally let's integrate this component into our src/app.rs by adding the following line after our <TimerDisplay /> component:

<TimerControls session_length={session_length.clone()} timer_state={timer_state.clone()} timer_duration={timer_duration.clone()} />

Great work! You will now have a fully functional UI and a useful tool that you can continue to iterate on over time assisting you in your software development

Conclusion:

Congratulations! 🎉 You've just built a full-stack Rust desktop app using Tauri and Yew, complete with a functional Pomodoro timer. This app not only serves as a practical tool for managing work and break periods but also demonstrates the power and flexibility of Rust in creating desktop applications.

I hope this tutorial has been insightful and enjoyable. Rust's growing ecosystem offers a unique approach to desktop application development, combining performance, safety, and modern tooling.

If you enjoyed the tutorial and want to see more of my other work checkout the links:
Twitter
YouTube

DEV Community: Max

Building a Custom Shell in Rust from scratch

Introduction

Project setup

Dependencies

Error handling

Why anyhow?

Setting Up Error Handling

I/O operations

Setting Up the REPL Loop

Breaking It Down:

Hooking It Up to main

Command handling

Defining the Command Enum

Parsing User Input into Commands

Breaking It Down:

Integrating Command Parsing into main.rs

Improve logging

Commands

Exit

Echo

Ls

Pwd

Cd

Touch

Rm

Cat

Conclusion

Recreating the Apple Calculator in Rust using Tauri, Yew and Tailwind

Introduction

Setup

Setting up the calculator

Button Components

Calculator top row

Major button rows

Final row

Done!

Create a Full stack Rust desktop App with Tauri, Yew and Tailwind CSS

Project setup

Timer

System Tray Updating:

Timer Controls:

Conclusion:

Why `anyhow`?

Hooking It Up to `main`

Integrating Command Parsing into `main.rs`