Forem: Warp

Introducing Warp: The Terminal for the 21st Century

Warp — Sun, 08 May 2022 18:04:33 +0000

Introducing Warp

Today, I’m proud to officially introduce Warp, a from-first-principles reinvention of the terminal to make it work better for developers and teams. As of today, Warp is in public beta and any Mac user can download and use it for free.

We are also excited to announce that we’ve raised some funds to grow Warp ($23M), both from wonderful firms (GV, Neo, BoxGroup) and world-class operators like Dylan Field (who led our Series A), Elad Gil, Jeff Weiner, and Marc Benioff.

Why Reinvent the Terminal?

Walk by any developer’s desk and you are likely to see two apps open: their code editor and their terminal (sometimes the code editor is the terminal!).

Both are crucial to developer productivity. The code editor is where developers write code; the terminal is where they do pretty much everything else, from building code to running and deploying it, interacting with source control, configuring their cloud systems, and more.

And yet only one of these two apps – the code editor – has experienced meaningful product improvement over the past 40 years. Compared to using VS Code, using the terminal is like stepping back in time to the 1970s. Only 70% of developers use VSCode, while 100% use the terminal. So why is the terminal experience still so lackluster?

Our Product Vision

At Warp, our product vision is to bring the terminal into the present in order to help developers build the future.

‍We are doing this by fixing the two biggest pain points that exist in today’s terminals:

Terminals are hard to use
They don’t work for teams

These are pain points that I’ve personally experienced again and again in my twenty years as an engineer, and I’m sure readers feel the same.

‍To get good at using a terminal before Warp, users had to do all sorts of complex configuration, master arcane key shortcuts, and memorize abstruse commands. Even then, seemingly simple things like copying a command’s output or positioning the mouse cursor were still difficult.

‍Warp makes input and output easy, and removes the need for most configuration. Input works like a modern text-editor, and output works like a data notebook. Moreover, Warp makes command-entry fast and fun by suggesting commands for commonly used tools and providing built-in workflows that save developers time.

‍In short, Warp makes the terminal work for the developer, rather than the other way around.

Secondly, up until Warp, terminals have been inherently single-user, local applications. But as I learned when I was leading engineering on Google Docs – and as Dylan showed with Figma – every productivity application is more powerful when it’s collaborative. This is true 100% of the time – from Figma to GDocs to Notion to Front – and I’m confident that the terminal is no exception.

Terminal “collaboration” means not just GDocs-style real-time collaboration, but asynchronous collaboration through sharing commands, settings, and history. It means increased knowledge-sharing through wikis and READMEs that run directly in the terminal. It means making the terminal safer and more secure via integrated password-management and audit logging. It means making the terminal a more extensible and customizable platform, with a nice modern ecosystem.

Finally, all of this needs to be built with speed and compatibility in mind – Warp is made in Rust with GPU-accelerated graphics, and works with existing shells like zsh, fish and bash.

Go Try Warp!

Nine months ago we launched Warp in private beta behind a waitlist. Since then, thousands of developers have made Warp their daily driver, given us feedback, and allowed us to greatly improve the product.

Today, we are removing our waitlist and launching our public beta. We are calling it a “beta” because we know there are still some issues to smooth out, but we are confident that even today the experience is meaningfully better than in other terminals.

If you use a Mac, please give it a shot and let us know how it goes. Otherwise, sign up here to be notified when Warp is ready for your platform.

Welcome to the future of the terminal.

How we designed themes for the terminal - a peek into our process

elvis kahoro — Thu, 17 Mar 2022 05:16:23 +0000

It’s no secret that people love to customize their UIs. With the rampant adoption of light mode and dark mode and the long history of themes in terminals and IDEs, the power to make your UI fit your functionality or aesthetic needs is huge. Here at Warp we knew how important it is to create a great theming system for our users. Some key goals were to ensure compatibility with existing themes, easy customization and sharing.

Let’s start with how themes work in existing terminals and what we wanted to improve.

Themes only control the text display, yet the rest of the UI remains the same. We want to deliver a more cohesive and immersive experience.
Themes are hard to control, you have to turn a ton of individual “knobs” in order to get something that looks good. It’s not easy to get what you want and add your personal preference. We want to make customization simple, flexible and quick.
Themes are hard to share. Importing and exporting themes are different and can require several steps. We want to make it a one click simple experience to import and share.

The foundation

To ensure warp could be compatible with all other existing themes we started with the standard foundation of 16 ANSI colors. Using these standards as our foundation allows practically every terminal theme to be used in warp.

We wanted to take it one step further and have the theme extend to the whole UI. Since we custom built Warp’s UI this allows us to have full control of the look and feel.

The first step of that was to consider the UI accent areas like the tab indicator and block selection. We want these areas to pop and gain your attention while also adding some visual flair. We needed to add another color attribute which we naturally called the accent color.

Being able to change the accent color gave themes a wider range of customization just from one color change without changing the look and functionality of the core theme.

UI theming

There is a bit more UI to cover within Warp like contextual menus, auto suggestion overlays, dialogs, command palette. The text coloring could easily be inherited from the theme and the accent color used for the same conditions, though we wanted the UI surface to stand out from the background. The last thing we wanted to do is to add yet another color attribute.

Starting with dark and light themes we had to handle the UI layering in different ways. To achieve separation from the background for dark themes, we added a white overlay which aligns with the core text color, and for light themes the opposite, black overlay which also aligns with the core text color.

We created a consistent style called “UI surface” which would be the background of all the overlay UI elements.

It consists of the theme background color, the opposite overlay color and an outline.

This basic system allows for a different UI surface leveraging the same color system. Seen here in dark and light mode.

The really neat part is how this easily extends to existing themes like Dracula and Solarized. For existing themes we convert, we will choose an accent color from the core 16 colors that we feel match the best. If you want to change it, no sweat, you can customize the accent color to any of the 16 theme colors or any custom color you like to add your personal preference to existing themes.

Image backgrounds

So with the standard theme color system and an added accent color attribute, we can easily customize the whole Warp UI. Yet we didn’t want to stop there, what about adding photos and advanced color treatment?

We experimented with adding photo backgrounds with color themes that matched and loved the results.

We also added the ability to support gradients, which can drastically change the look of a theme and add additional depth and visual pizzaz.

Dracula regular:

Dracula with gradients:

Customization

We want our user to have the power to make amazing themes, so we are working on a theme editor that makes customizing themes super simple. For lightweight use, you can start with our default dark or light theme and change the accent color. Choose one of many popular themes we have built into warp or import your favorite. If you want to go for even more customization, add a photo, make your accent color a gradient. With just a few customization you can radically change the way your terminal looks and feels.

Sharing

Currently, there are ton of different sites and resources to get terminal themes, each of them with totally different ways to download themes, from a file download, github repo, etc.

For Warp themes, we want to build a one stop shop for themes. One spot where you can browse, install and share themes all with one click. We also want individual themes to be easily shareable from user to user within the app.

Check out themes now

It’s been really exciting working on themes in Warp. Building a system that can accommodate existing themes, expanding on them within Warp and giving users more control to customize and share. We can’t wait to see what themes get created.

You can check out the base theme experience in Warp now, where you can choose from a set of themes and customize via an external file. Shortly gradients and image support will be rolling out. Customization and sharing are down the road.

We are all super excited to get all these theming features out, we have a bit of work ahead of us! Please let us know if there are any ideas that brew up, we would love your input!

Request early access to our beta. We look forward to your input!

What’s so special about PS1? Fun with customizing Bash command prompts

cieplik — Thu, 17 Mar 2022 05:13:44 +0000

Long ago, when I was still a console newbie, I copied my friend’s bash configuration file. It had all the necessary stuff already included - aliases, colors, and most importantly: a nice prompt setup. I used it on all machines I had access to due to all the extra context it provided. For example, it would turn red when I was on a production machine, show me a current git branch from the repository I was working on, and indicate whether I had any changes to commit by showing a star.

Today there are a seemingly endless set of tools for configuring the command prompt to your liking, but back then things like Starship were completely non-existent. Most developers I know have customized their prompts in one way or another. This fact, combined with the feedback we’ve received from the Warp community, was good motivation to dig deeper into prompt customization in Warp.

In this post I’m going to tell you how we implemented support for PS1 in Warp, and why adding it was technically challenging. Along the way, we’ll also tackle the DCS (device control string) and some fun shell tricks!

Hey, Cieplik, what actually is PS1?

Glad you asked! PS1 is one of the few variables used by the shell to generate the prompt. As explained in the bash manual, PS1 represents the primary prompt string (hence the “PS”) - which is what you see most of the time before typing a new command in your terminal. On top of that there are actually few more - from PS0 to PS4, each of them executed and printed in different contexts of command execution. For example, you’ll see PS2 whenever the command has multiple lines as a secondary prompt string. And then zsh also provides RPS1, which displays the Prompt String on the right-hand side… there's a lot to work with.

Each of the Prompt String variables can easily be customized with the backslash-escaped special characters, but they can also contain shell function calls or even emojis, since most modern terminals support unicode.

With Warp in the works we made a decision to provide useful defaults for users to help them hit the ground running when using a new app. This included the prompt. We explicitly decided to not support PS1 in Warp, as it could clash with the bootstrapping script and PRECMD/PREEXEC hooks we use to create blocks of inputs and outputs. By implementing our own default prompt we had much more control over the user experience, and that was critical at the early stages. Eventually, however, it became obvious that our users really need their custom setups and lack of certain information on the prompt may actually slow them down. It came time for us to honor the user’s PS1 settings. Keep in mind that this is not our last word on this topic

What’s under the Prompt String’s hood?

In Warp, because we buffer the user’s input, we can’t allow the shell to directly render the prompt. Instead we use the metadata from the shell to do our own rendering. Our app receives it from the shell via the PRECMD hook, to do things like retrieve the current git branch, which is used in Warp’s default prompt. We use a special escape sequence and a JSON string packed with data to pass all the necessary information.

This is why we decided that the best way to support PS1 in Warp is to pass it as part of our PRECMD hook. The first challenge, however, comes from printing the variable into this JSON string.

Your PS1 is usually a set of variables, like information about the colors you want to see, but sometimes it can be a function call too. We have to translate it into a rendered Prompt String - a set of escape sequences and characters that tells the terminal the exact string to print and how to print it.

Here’s the example of an oh-my-zsh PS1 setting

> echo $PS1
%F{magenta}%n%f at %F{yellow}%m%f in %B%F{green}%~%f%b$(git_prompt_info)$(ruby_prompt_info)
$(virtualenv_info) $(prompt_char)

In zsh rendering a prompt is actually quite simple. You just print it. (and the shell expands all parameters for you via prompt parameter expansion.) We insert the output into our JSON and display it on our terminal.

Note that the middle prompt is the output of the print command, prepended with "rendered prompt" for clarity.

Bash does have a similar way of expanding prompt parameters as zsh does, so we could easily run echo ${PS1@P} in our script to get the rendered prompt and call it a day! Except…

That functionality has only been introduced in bash 4.4+. But Macs do not ship with that by default (this is related to a licensing change: since version 4.0, bash switched to a GPL license, which is not supported by Apple). The question, then, is how do we render the PS1 in older versions of bash without using any special tools or libraries?

The way we ended up solving this issue is by invoking a subshell, executing a very simple command in it, capturing the entire subshell output (including the prompt), and then manipulating it to only capture the prompt itself.

This is the final code we’re currently using in Warp to get the value of the rendered bash prompt:

$(echo -e "\n"  | PS1="$WARP_PS1" bash --norc -i 2>&1 | head -2 | tail -1)

Let me break that down, pipe by pipe:

echo -e "\n" prints an empty line in our subshell;
PS1="WARP_PS1" bash --norc -i 2>&1 we pass a previously captured $WARP_PS1 value as the PS1 in the subshell, and specify that no configuration files should be loaded (norc argument) to improve the performance of this operation; the -i flag denotes an interactive shell, while 2>&1 redirects the stderr to stdout, which allows us to capture the rendered prompt;
Head & tail operations simply help us manipulate the output to extract the prompt only.

That’s it. We've got our rendered prompt, we can start showing it in Warp!

Escaping the Prompt

Some things and places are really hard to escape, like the Russian city of Omsk, where even stray dogs cannot leave. Escaping in the terminal realm is really close to that experience, and Prompt String seems to make it even harder.

When juggling shell data and passing it to Warp via our PRECMD hook, we escape escape sequences that may break our JSON string with our magic sed invocation:

sed -E 's/(["\])/\\1/g; s/''\t''/\t/g; s/''\r''/\r/g; /\n/'

This is actually a series of replacements:

All double-quotes and backslashes are replaced with their escaped versions (\” and \);
\b (backspace), \t (tab), \f (form feed), \r (carriage return) are all replaced with their escaped versions;
We add an escaped \n (new line) on every line explicitly, since sed analyzes the input line-by-line and thus is not aware of the actual new lines.

This worked great, yet with the Prompt String you actually get many more things to escape: it’s not uncommon for the rendered prompt to include some extra bells and whistles (I mean the actual bell character - \a) and lots of other non-printable characters and escape sequences (most significant being \x1b aka \e or \033, which is literally ESC). Note that those sequences also had to be double escaped, to not only create a valid JSON string, but also not break our Rust implementation when unescaped! At least we were able to use the same tool for both supported shells this time!

In the first iteration, the final sed call looked a lot like:

sed -E 's/'$'\e''/\\e/g; s/'$'\a''/\\a/g;  s/(["\\])/\\\1/g; s/'$'\b''/\\b/g; s/'$'\t''/\\t/g; s/'$'\f''/\\f/g; s/'$'\r''/\\r/g; $!s/$/\\n/'

Back to the whiteboard

At this point, we started testing internally. It was then that we found a mysterious behavior.

A common tool used to customize the prompt in zsh - oh-my-zsh - is used by many team members. The prompt rendering worked for every theme...except the default oh-my-zsh theme. When the theme was used, the entire bootstrapping script would fail, leaving Warp in an unusable state.

Robby Russell’s oh-my-zsh prompt theme

It turned out the little arrow (➜) to the left was the root cause!

With shells and terminal emulators it always makes sense to analyze the actual bytes that are being processed. Let's check what’s under the hood of this little arrow:

This particular emoji consists of 4 bytes: e2, 9e, 9c and 0a. A careful reader may notice that both 9e and 9c bytes come from the extended ASCII table, but do they carry any special meaning? When in doubt, it’s always good to go back to the source - in this case, check the shell parser documentation. For completeness, let's quickly unpack what VT100 (and other VTs) is, and what this mysterious DCS is that are both mentioned in the linked docs:

VT100 was a Video Terminal introduced in the 70s. It was one of the first machines that allowed for cursor control with ANSI-escape codes, and added a bunch of other control options. Later on its spec became a de facto standard, and modern terminal emulator programs try to follow it (including Warp).

Control characters and control sequences in the terminal world are special ANSI-escape characters that control the terminal’s behavior. It can be anything from the cursor position, mouse control, even colors. DCS (device control string) is a special control sequence that is followed by a data string. You can find out more here.

unhook

When a device control string is terminated by ST, CAN, SUB or ESC, this action calls the previously selected handler function with an “end of data” parameter. This allows the handler to finish neatly.

As it turned out - the 9c byte carried a special meaning in a terminal world - it’s an ST (string terminator) escape sequence, which also happens to denote the unhook operation. As a result, the emoji in our JSON string would prematurely end the PRECMD hook, making it impossible for Warp to fully start.

From there the solution was simple - rather than trying to escape emojis and unicode characters that may have similar issues in the future, we simply encoded the entire Prompt String as a hexadecimal string. This completely eliminated the need for using sed and simplified our shell script.

Below you'll find a snippet with our current precmd function (example in bash):

   warp_escape_ps1 () {
           tr '\n\n' ' ' <<< "$*" | xxd -p | tr -d '\n'
        }

                # Format a string value according to JSON syntax - Adapted from https://github.com/lework/script.
        warp_escape_json () {
            # Explanation of the sed replacements (each command is separated by a `;`):
            # s/(["\\])/\\\1/g - Replace all double-quote (") and backslash (\) characters with the escaped versions (\" and \\)
            # s/\b/\\b/g - Replace all backspace characters with \b
            # s/\t/\\t/g - Replace all tab characters with \t
            # s/\f/\\f/g - Replace all form feed characters with \f
            # s/\r/\\r/g - Replace all carriage return characters with \r
            # $!s/$/\\n/ - On every line except the last, insert the \n escape at the end of the line
            #              Note: sed acts line-by-line, so it doesn't see the literal newline characters to replace
            #
            # tr -d '\n' - Remove the literal newlines from the final output
            #
            # Additional note: In a shell script between single quotes ('), no escape sequences are interpreted.
            # To work around that and insert the literal values into the regular expressions, we stop the single-quote,
            # then add the literal using ANSI-C syntax ($'\t'), then start a new single-quote. That is the meaning
            # behind the various `'$'\b''` blocks in the command. All of these separate strings are then concatenated
            # together to form the full argument to send to sed.
            sed -E 's/(["\\])/\\\1/g; s/'$'\b''/\\b/g; s/'$'\t''/\\t/g; s/'$'\f''/\\f/g; s/'$'\r''/\\r/g; $!s/$/\\n/' <<<"$*" | tr -d '\n'
        }

        warp_precmd () {
            # $? is relative to the process so we MUST check this first
            # or else the exit code will correspond to the commands
            # executed within this block instead of the actual last
            # command that was run.
            local exit_code=$?
            # Clear the prompt again before the command is rendered as it could
            # have been reset by the user's bashrc or by setting the variable
            # on the command line.
            if [[ -n $PS1 ]]; then
              WARP_PS1="$PS1"
            fi
            unset PS1
            unset PROMPT
            # Escaped PS1 variable
            local escaped_ps1
            if [[ $WARP_FEATURE_FLAG_HONOR_PS1 == "1" ]]; then
              # Tricking the shell into rendering the prompt
              # Note that in more modern versions of bash we could use ${PS1@P} to achieve the same,
              # but macOs comes by default with a much older version of bash, and we want to be compatible.
              deref_ps1=$(echo -e "\n"  | PS1="$WARP_PS1" bash --norc -i 2>&1 | head -2 | tail -1)
              escaped_ps1=$(warp_escape_ps1 "$(echo "$deref_ps1")")
            fi
            # Flush history
            history -a
            # Reset the custom kill-whole-line binding as the user's bashrc (which is sourced after bashrc_warp)
            # could have added another bind. This won't have any user-impact because these shortcuts are only run
            # in the context of the bash editor, which isn't displayed in Warp.
            bind -r '"\C-p"'
            bind "\C-p":kill-whole-line
            local escaped_pwd
            escaped_pwd=$(warp_escape_json "$PWD")
            local escaped_virtual_env=""
            if [ ! -z "$VIRTUAL_ENV" ]; then
                escaped_virtual_env=$(warp_escape_json "$VIRTUAL_ENV")
            fi
            local escaped_conda_env=""
            if [ ! -z "$CONDA_DEFAULT_ENV" ]; then
                escaped_conda_env=$(warp_escape_json "$CONDA_DEFAULT_ENV")
            fi
            local git_branch
            git_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
            local escaped_git_branch
            escaped_git_branch=$(warp_escape_json "$git_branch")
            # At this point, escaped prompt looks something like
            # \\u{001B}\\u{005B}\\u{0030}\\u{0031}\\u{003B} ...
            # We need to maintain the double quoting of \\u in the message that
            # is sent otherwise the receiving side will interpret the value
            # as JS string literals of the form \uHEX, and will include
            # ctrl characters (like ESC) in the json, which will cause a JSON
            # parse error.
            # Note WARP_SESSION_ID doesn't need to be escaped since it's a number
            local escaped_json="{\"hook\": \"Precmd\", \"value\": {\"pwd\": \"$escaped_pwd\", \"ps1\": \"$escaped_ps1\", \"git_branch\": \"$escaped_git_branch\", \"virtual_env\": \"$escaped_virtual_env\", \"conda_env\": \"$escaped_conda_env\", \"exit_code\": $exit_code, \"session_id\": $WARP_SESSION_ID}}"
            warp_send_message "$escaped_json"
        }

Future of the prompt

Warp now has the option to honor the user's PS1 setting. It works with most configurations, though you’ll find the full compatibility table in our docs.

It is not, however, the last time you'll hear from us about working on the prompt. Our key product principles include fixing the UI and providing a great out-of-the box experience. One of the ideas we're currently exploring is Context Chips - our low-calorie approach to snacking on bite-size information.

We’re working on plenty of interesting problems just like this one at Warp; and we’re hiring! If you want to be a part of our team and work together on improving the day-to-day life of developers from around the world - check out our careers page.

Fantastic terminal programs and how to quit them

Zheng Tao — Thu, 17 Mar 2022 05:12:31 +0000

There’s a popular meme about exiting vim.

More earnestly, there’s even a LinkedIn learning course on how to use vim. The first module is dedicated to how to exit.

Why is it so hard? This seems like an odd problem to have. When’s the last time you’ve thought about exiting your web browser, MSWord, or any other application on your computer?

It’s not just Vim, but the user experience on the terminal as a whole.

The terminal predates human computer interaction. It existed before Xerox PARC lab & Apple Computer worked on personal computing and GUIs. Apple introduced some human interface guidelines in 1977, which have been copied pretty much everywhere else -- but the terminal has stayed the same.

It’s true that some popular terminal programs were created after this all happened, but there’s a big difference in their philosophy of the user.

Today, it’s not revolutionary to say, as Apple did in their human interface guidelines, that “people are not trying to use computers—they’re trying to get their jobs done.” In the terminal, it’s just the opposite: for example, people are trying to use tmux to experience the tao of tmux.

The terminal is hard to use. Interactive terminal programs are particularly difficult and they behave unlike anything else on your computer.

As intimidating it is to get started, it can be extremely valuable to know how to use these programs. They are cross-platform, available on even the most limited environments, keyboard-accessible, and if you’re on a remote host it’s often the best option to accomplish some task.

Here’s the basic ins-and-(literally!)outs for a bunch of programs, why they can be non intuitive, and why other modern apps aren’t difficult in the same way.

Vim

Vim has a number of different modes. By default, it’s in “normal” mode. Hitting ‘i’ will get you into “insertion” mode which edits the text content directly. You’ll need to get out of insertion mode (esc) to communicate a quit command to vim.

We’re used to modeless text editors today. They’re the default editors everywhere: on computers, phones and tablets – natively and on the web.

License plate of Larry Tesler, “Primary inventor of modeless editing and cut, copy, paste.”

When you are in any mode aside from normal mode, it’s communicated in the bottom left. Many tools use a similar status bar UI. This can be easy to miss if you don’t already know to look here.

Status bar in Vim

When they do use modes, other apps today clearly indicate the mode. If you go from an editing mode to viewing mode in GDocs, you can’t miss it. Any design app will also change the cursor to indicate what you’re doing.

Changing modes in Figma

From normal mode in Vim, we can type : to get into Cmd-line mode. This makes the cursor jump from the content to the bottom-left, and vim commands can be typed.

Finally, we can type q <enter> to quit.

If you have some unsaved content, vim won’t let you quit, to ensure you don’t lose anything.

One option is to go nuclear and force quit :q!.

Otherwise, you can save the file. If there’s already a filename, :wq or :x will let you save and quit. If you did come from the empty state, there’s no file here yet so you will have to explicitly save to a file (:w filename) before quitting.

Emacs

The keybinding to quit emacs is Ctrl-X + Ctrl-C.

This key sequence is more complicated - and I’ve definitely messed it up before when doing this the first couple times.

Emacs does give some visual feedback in the bottom-left corner after typing the first Ctrl-X.

It’ll also tell you if you messed up in the same place. But you can also inadvertently type a bunch of stuff that edits the file, and you won’t necessarily get this feedback.

Relative to vim, it’s a little easier to deal with editing a file and saving it, because emacs will ask you how to deal with an unsaved file.

Emacs doesn’t have modality, but its shortcuts are more complicated in general. A lot of functionality in emacs uses the Meta key. For example Meta-f and Meta-b move forward and back one word respectively.

While it used to be a thing, modern keyboards don’t include the Meta key. Most terminal emulator apps will let users map some other key to imitate Meta instead. It’s not typically on by default, and sometimes one has to dig quite a lot to do this.

Mapping Option to Meta in iTerm2

We generally won’t see key sequences this complicated in other places on the computer outside of the terminal. At the very least, other apps are not going to use a key that no longer exists and put the burden on the user to figure out how to make it available.

Nano

Quitting nano is not hard relative to other things. There’s a status bar that hints Ctrl-X will exit.

Many people have found themselves in nano because git or arc put them there, even when they have not chosen it as an editor.

This is some pretty unforgiving UX. It’s rare outside of the terminal to end up in an application where you may not know how to exit.

Tmux

Tmux is a terminal multiplexer. It provides a lot of functionality, and one basic way to think of it is a way to manage multiple running shells arranged in a number of “windows” + panes.

For tmux, any attempt to communicate directly to tmux involves typing Ctrl-b (we call this the prefix key). There are two main options for getting out: Ctrl-b + d will detach the screen session. Ctrl-b+ :kill-session kills the current session.

When typing command sequences after the prefix key, no feedback is given and you’ll have to internalize these commands to use tmux.

Remembering the one prefix key is not as hard as remembering all the commands to work regularly in a terminal multiplexer. In my experience, pros mess up basic tmux commands again and again.

These programs epitomize remember-and-type over see-and-point. As Apple’s human interface guidelines puts it:

“Command-line interfaces require the user to remember a command and type it onto the computer. This kind of interface makes considerable demands on the user’s memory -- especially when the commands are complex or cryptic. Such an interface is especially galling to the new or infrequent user, but it distracts all users from their task and focuses attention instead on the computer’s needs.”

Furthermore, “users rely on recognition, not recall; they shouldn’t have to remember anything the computer already knows.”

Developers know this principle very well when it comes to their code. Djikstra famously said “the competent programmer is fully aware of the limited size of his own skull. He therefore approaches his task with full humility, and avoids clever tricks like the plague.” The mantra DRY (Don’t Repeat Yourself) is programmer dogma and is present in many programming books and classes. This principle has not made it into the terminal’s user interactions.

Summary

Every program here consistently quits in a different way from all the other ones.

A final point here is, even though we are used to discussing these commands as “keyboard shortcuts”, these are not alternatives but the only way to run the command. Popular guides will also encourage usage of these programs by saying they are “keyboard accessible." The idea that keystrokes can provide a productivity boost but shouldn’t be the only interface is ingrained in the English language.

Program	How to exit
vim	Get out of insertion mode by hitting esc Type :q
emacs	Ctrl-x Ctrl-c
nano	Ctrl-x
vim	Ctrl-b + d (detaches session) Ctrl-b + :kill-session to kill session
screen	Ctrl-a + d (detaches session) Ctrl-a + k (kill session)
Normal terminal session	Ctrl-d (End-of-Transmission / EOT)

At Warp, we believe the terminal also can be a delightful product, in addition to a powerful utility. We are building a terminal from the ground-up with the user in mind.

Request early access to our beta. We look forward to your input!

Who’s behind Warp? - Meet the team

cieplik — Thu, 17 Mar 2022 05:10:57 +0000

My idea for a perfect opening line of this blog post was to use a quote about the importance of building a great team. I scrolled through pages of quotes from personas such as Henry Ford, or Michael Jordan, eventually settling on… nothing. We all know that teamwork is critical and a huge part of engineering work, no need to back this up by famous people’s quotes! It becomes even more important in small companies and startups, such as Warp—where everyone works together to deliver the best terminal experience to other developers. In the last post we uncovered a little bit about how we think about building the product; in today’s, I’ll introduce you to people behind Warp and the story of how we built the new terminal!

Why did I join Warp?

Let me start by telling you my part of this story.

As a person who rides a 700lbs motorcycle that doesn’t have a reverse (try parking that thing!) and a digital clock is its most advanced piece of technology; who writes her code in Vim and still mixes all the ingredients for the cake manually—I clearly like to... do things in a more traditional way. No wonder the terminal has been my main tool ever since I started working as an engineer.

I was initially very skeptical about Warp—after all bash scripts, grep,sedandawk` can already get you a pretty long way when working with the terminal, right? I was still curious about what the company has to offer, and that’s why I joined one of the first user research sessions. I even borrowed a MacOS laptop specifically for this!

This was the first time I met the entire Warp team and got to try the application. Learning about the roadmap (especially the team features that will improve efficiency and safety of devops work!) and seeing how user-focused the team is, was what got me excited about the product and the company. 2 months ago I quit my job as an Infrastructure Software Engineer in Dropbox, and joined Warp—the company that builds a next-gen Rust-based terminal.

Why did Zach decide to build a terminal?

Zach, whom you might’ve seen on Twitter or a recent webinar (talking about Warp, obviously), is the CEO of Warp. He previously worked as a Principal Engineer at Google, CTO at Time and co-founded the venture-backed startup SelfMade, yet his interests circle around improving the developer’s experience.

Zach Lloyd, Warp's CEO

There’re plenty of tools around that improve the development process in one way or another—focusing on a broad group of engineers, or on a very specific niche. However, only 2 are truly used by almost every programmer there is—they are IDEs and code editors or a terminal. The former already went a long way—we’ve had Eclipse and JetBrains, or IntelliJ; there was notepad and Atom and Sublime; and nowadays VSCode seems to be the majority’s favorite IDE and code editing tool.

On the other hand, the terminal stayed the same for almost 40 years (and still counting)! It’s slowly evolving with extra functionality coming from new shells (like fish) or prompt-tools (like starship.rs). Yet, the main experience has stayed the same, and modern terminals still emulate the physical ones, implementing the subset of functionality from VT100 (hence the correct term is actually “terminal emulator”). Lack of innovation in this area is what made Zach take a closer look at building a terminal. And that’s how Warp was born.

People behind Warp

Soon, Shikhiu, Michelle, and Aloke joined Zach in the effort of working on Warp. The initial prototype was an Electron app, though the poor performance pushed the team to pivot and rewrite the application in Rust. Besides making Warp an OS-native, and blazingly fast application which utilizes GPU rendering, Rust is a language with a strong community support and tools that make it easy to ramp up new developers (Rustlings, we’re looking at you!). As a result the team (with support from Nathan Sobo—the Atom editor creator) created a Rust UI framework which we plan to open source in the near future.

Michelle used to work as an engineering intern in Facebook, Slack, and Robinhood. She also pursued an entrepreneurial path co-founding the first health tech incubator in Yale and creating her own health tech app during her college years. Viral growth and user feedback loops are clearly her thing, however, not the only thing. Michelle has a black belt in taekwondo; loves watching movies and analyzing them for hours afterwards; and recently she started to learn how to drive (on the streets of New York City!).

The only person who did not pick up Rust (just yet), is Shikhiu. His excuse is being the Founding Designer. As a master of Figma, Shikhiu creates mockups of new Warp features in minutes, helping the team visualize the work and iterate faster. He recently told me he’s into plants, which would explain why the “leafy” terminal theme (soon to ship in Warp) is so beautiful. He used to work at Adobe and later on at Google where he led a team of 30+ designers on design for the Docs suite, yet (luckily for us) he chose to join us to reimagine the terminal product experience!

Work in progress of themes in Warp - with "leafy" being one of the concepts!

Working as a TL for Google Docs, Aloke had already collaborated with Shikhiu during his time in Google. He also came across multiple TODOs left in the Google Docs codebase by the mysterious zachlloyd, but hadn't had a chance to work with Zach prior to joining Warp. Before his interview with Warp, Aloke dropped a very sharp knife on his foot, but decided to tough it up and pass the interview with a bleeding foot. This definitely showed how dedicated he is, though we are all glad that he saw a doctor and his foot is now fully healed… Besides cooking as a hobby, Aloke lifts (not just our spirits) and is very much into public transportation. He gets triggered by lack of periods at the end of the comment, since that makes it an incomplete sentence—I like to think it was the reason he started working on completions in Warp.

Currently, Warp consists of 7 engineers with Zheng, Chuck, Kevin and me joining over the course of the last 6 months.

Zheng, Chuck, Kevin & me all wearing our Warp's T-Shirts

Chuck plays a critical role in the team since he’s the only person with prior Rust experience. Besides being a mentor, who leaves helpful and constructive feedback in our PRs, Chuck collects Pez candy dispensers and can solve a Rubik’s cube in under 1 minute. One of the things that drew him to Warp is being able to improve developers’ experience first hand—he used to work in the devtools team in LinkedIn and maintains Volta tool manager. Working on the terminal was a logical next step.

After a few years of working at Dropbox, Zheng decided to dive into the startup world. First, she worked for Gem, and later on met Zach and the team. She deeply cares about the work culture, so her joining Warp says a lot about the company. She likes to travel, pet cute animals and drink good wine; and also she likes to dig really deep into why and how our users use the terminal and other tools day to day. That’s why her current main focus is driving the tmux-like experience in Warp.

Kevin is our most recent hire. He joined as a full-time engineer only a month ago, but has been working part-time at Warp for the past year. He spent his college years traveling to different countries while continuing the education remotely and recently graduated. As part of his international adventures, he interned in a Japanese company in Tokyo for 2 summers, and thanks to that polished not only his engineering skills, but also learned to speak the language! During his internships he tried himself in different fields, including data science and ML, and figured that he’s really interested in developing tools for other engineers, wanted to work on something that will have a direct impact on users and was pretty much a blank canvas. Warp matched his interests perfectly.

Over the summer, we also worked with Saumya & Matt—summer interns who delivered functionality such as notification on long running commands and custom theming. Big thanks to both of you!

Working at Warp

The team works remotely and is spread across different time zones (though we recently opened an optional office space in NYC!). The company was founded during the peak of COVID-19 pandemic, so it couldn’t have been different anyways.

We meet daily to discuss progress and show demos of new features, and organize more Zoom meetings whenever necessary. As a group of very opinionated people (who in the tech industry isn’t?), we sometimes tend to stay online longer, discussing new ideas, making sure that everybody has a space to express their point of view. Somehow we still manage to make the majority of the decisions unanimously - unless it’s about the fate of the ctrl-r keybinding… In those moments of doubt, Blue’s (Zach’s dog) appearance in the background cheers everyone up, especially when he tries to eat our CEO’s dinner. Altersnatively, Backup (my dog) sometimes comes to the standup and adds his voice to the pool of our opinions.

When it comes to figuring out the road map for Warp, we try not to rely on our personal views only. Hence, the closed beta program and user focus groups - both helping us learn what’s the right set of features to build next. Zach wrote about our 8 product principles in a separate post, and you can read more about the team’s culture and approach on his blog: thezbook.com.

And most importantly—if you feel like our culture suits you and you’re passionate about bringing the developers’ experience to the next level—we are hiring and would love to work with you!

Warp’s product principles for reinventing the terminal

Warp — Thu, 17 Mar 2022 04:56:58 +0000

At Warp, we believe we can keep what’s best about the command-line while fixing its pain points and adding super-powers.

Our goal is that using Warp every developer should be as productive as a CLI veteran.

Here are the eight principles that guide our approach:

#1: Meet developers where they are.

This means that our terminal should be backwards compatible. A developer using it for the first time should be at least as productive as they were in their old terminal. Practically speaking, this means we are creating a terminal that works with developers’ existing shells, scripts, and key bindings.

#2: Keep the power, but fix the UI.

We don’t see any reason why the terminal can’t have a more modern, intuitive interface, while maintaining the power of a primarily textual, keyboard driven experience. If a user wants to use the mouse to position the cursor, why not support that? Why not have a native autocomplete and search experience? Our goal is to create the UX that best supports what developers use the tool to accomplish, and we are pragmatic about whether that UX is character based or pixel based and whether the input mechanism is the keyboard or the mouse.

We introduced blocks to help you navigate your work in the terminal.

#3: A great out-of-the-box experience.

There are many different plugins, themes, and open-source projects that improve aspects of the CLI; e.g. tmux, mosh, OhMyZsh, and powerlevel10k. Each has its own install process, configuration scheme, update mechanism and more. Many developers end up using a very basic and underpowered version of the CLI because they never discover, configure or learn these tools. We believe there is value in an integrated, out-of-the-box experience that helps all developers be more productive immediately.

#4: Build for speed.

One of the great attractions of working in the CLI is that if you master it, you can work very quickly. That’s only true though if the underlying terminal is fast. We are building Warp on the fastest possible modern architecture. On desktop: a pure Rust app that goes directly to the GPU for rendering. On the web, a WASM app that uses WebGL.

#5: Build a platform.

Most developers will experience Warp as a terminal app, a product they launch and run. However, the CLI is more than an app, it’s a platform, much like iOS or Windows. It has (primitive) mechanisms for discovering apps, installing them, running them, but it lacks many of the affordances of modern platforms, like an app-store, a unified way of securely installing and removing apps, a well defined API for developers to configure the runtime environment, and more. While we are starting by focusing on the terminal app and experience, we eventually want to build the best possible CLI platform.

#6: Leverage the cloud.

The basics of computing have changed since the advent of the CLI, and no change has been more profound than the rise of the internet. Once you start to think about it, there are a lot of leverage points: why is shell history limited by your local hard-drive? Why doesn’t your shell configuration follow you across machines? Why can’t you transfer a CLI session to the browser so you can keep working on the go? (Don't worry, though, Warp is local-first, and all cloud features will be opt-in. You can find out more in our privacy policy).

#7: Build for teams.

Developers today work in teams on shared projects. Because of this, most applications developers use are collaborative in one sense or another. Github is a good example, as is VSCode live session sharing. And yet the CLI is still primarily a single-user tool, with collaboration facilitated by copy/paste, screenshots, and screen-sharing, rather than a true multi-player experience. We believe that CLI-based teamwork is a very powerful concept, extending beyond google-docs real-time collaboration, to facilitating asynchronous workflows like command-reviews, shared devops terminals and more.

Real time collaboration & session sharing is one of the features we're working on.

#8: Build for everyone.

The CLI traditionally has a bit of a mystique around it; developers feel like hackers when they use it, and there’s almost a rite of passage in conquering its idiosyncrasies. We believe that the CLI should be more accessible, more humane, and more useful to all developers. Too many are turned off by the intimidating UI. Many aspiring developers have their first experience using the CLI (it’s how they set up development environments), and that first experience is often very negative because the interface is so hard and creates so much incidental complexity. We want to fix this and make a modern CLI for all developers.

We truly believe that following all eight above principles will help us deliver the terminal that will finally bring the developers’ experience to the next level! And while we’re focused on building Warp, you can still meet us in our Discord community where we discuss Warp with developers from around the world. Request early access if you haven’t already. We look forward to your feedback.

The terminal is on life support. Is it worth saving?

Warp — Thu, 17 Mar 2022 04:50:00 +0000

Why doesn’t the terminal work like the rest of your apps? Developer tools have evolved towards reusability, composability, and collaboration. Meanwhile, terminals are inherently single-user, linear, and ephemeral.

For instance:

Developers work in teams, but terminals don’t support collaboration
Developers rely on sharing knowledge, but all my terminal work disappears every time I close a session
Developers work across machines, but my terminal environment is tethered to my computer
Developers are becoming accustomed to nice interfaces, but the terminal inflicts pain and makes me feel like an idiot when I try to do moderately complicated things

In spite of these obvious shortcomings, terminals persist!

A lot of developers swear by them. And I understand why: if you know what you’re doing, the terminal’s text-based interface is fast, efficient, composable, and programmable. Terminals are awesome power tools.

So we have an interesting situation: terminals are both obviously useful and highly antiquated. How did we get here? What’s the best way forward?

In the rest of this post, I’ll argue that

Terminals persist because CLIs are the best interface for a lot of developer tasks
Their antiquated architecture has stifled innovation
This has in turn caused terminals to lose share to GUIs
The right way forward is to keep what’s best about the terminal, but modernize it...which is what we are working on at Warp

And for those who don’t want to read a whole blog post, you can get a sneak peek at Warp up front:

A preview of Warp showing blocks, text-editing, native completions and visual hisory.

Terminals persist because CLIs are good interfaces for developers

As a simple example, say you have written a program and suspect it’s leaking file handles but aren’t sure. If you are comfortable in the terminal you can run a few commands to see what’s going on:

First you can find your program’s process id using ps and grep:

ps aux | grep {program-name}

Then you can see how many files it has open:

lsof -p {process-id} | wc -l

And you can use watch to track this over time to see if your debugging theory is right.

A GUI is almost all downside for this use case. Slower, less-flexible, won’t work over ssh, etc, plus it would be a pain to build. There are lots of developer tasks like this.

Even though capital-letter CLIs have a lot of use-cases, the current implementation of the terminal is really bad for reasons mentioned earlier - no collaboration, transient sessions, bad UX, etc.

Consequently, terminals are losing developer market share to user-friendly and modern GUI apps like VSCode, Postman, and more.

Why hasn’t anyone already fixed the CLI?

People have tried, but the terminal architecture makes it really difficult to innovate.

Terminals and shells only support the character-in-character-out protocol of a teletype, a piece of hardware that hasn’t been used in most new developers’ lifetimes. Specifically, the terminal sits on one side of a PTY and the shell sits on the other. Between them flows a sequence of characters. The only structure in place is a set of character codes that control how the terminal lays out and paints its buffer.

Because shells are responsible for parsing input and running programs, terminals don’t know even basic things about what's happening; e.g. what separates a command from its output from the next command? Was the command successful? What text was written to stdout vs. stderr? Terminals have a knowledge deficit.

Conversely, shells have a much richer understanding of all this, but they have extremely limited capabilities on the UX side. They can't handle mouse interactions or render graphics, like for instance a completion UI. Shells have a capability deficit.

As someone wanting to modernize "the CLI", you are faced with the fact that there actually is no single CLI app – there are terminals and shells. Trying to fix the experience at the shell level can be somewhat effective – e.g. ohmyzsh, fzf, thefuck – but it can never fix fundamental accessibility issues and it will never make the terminal feel like a modern app.

In order to really modernize the CLI, you need to start with the terminal, and keep pushing further and further into the world of shells, ultimately ending up with a better integrated experience. This is hard, but we think it's worthwhile because of the productivity gains it will unlock.

Warp: a more accessible, powerful terminal

At Warp we are building a new Rust-based terminal that keeps what’s best about the CLI while modernizing and upgrading the experience. One awesome thing about how we are building it is that it works with your existing shell so it's easy to try.

If you’re interested in how we are pushing the technical limits, please give How Warp Works a read.

A quick preview

Rather than a single buffer, we divide terminal output into a sequence of commands - making it easy for them to navigate, copy, save, and share units of work.

Warp is a block-based terminal

We make input more familiar and usable, replacing the character buffer with a full-fledged text editor built in Rust, and equipping it with intellisense-like autocomplete:

Built-in completions and documentation

And finally, we want to transform the terminal from an inherently single user utility into a modern collaborative app where sessions, blocks, and environments are all persistent, searchable and shared by link (being very mindful of security and privacy).

These types of features are just the start, and part of a larger set of principles we have for improving the terminal’s CLI.

If you’re interested in learning more, please check out our site and request early access here. We are still in the early days of implementing our vision but would love feedback and input as we move forward.

How Warp Works

Aloke Desai — Thu, 17 Mar 2022 04:27:16 +0000

Warp is a new high-performance terminal built entirely in Rust that makes you and your team more productive and the CLI easier to use. The input editor for commands is a full text-editor that supports selections, cursor positioning, and shortcuts like you are used to in other apps. Commands and their output are visually grouped into blocks, and existing shortcuts like up-arrow and ctrl-r have new visual menus to make them easier to use.

In this article, I walk through how we built the foundation of Warp: the UI, blocks, and the input editor. Building this foundation ultimately helped us unblock even more exciting features that we’re launching in the coming months, like infinite history, real-time collaboration, and shared environment variables.

Designing Warp required us to be intentional about our stack at nearly every level. At the start we had a key requirements:

Speed: Speed is critical when using a terminal, especially for commands that can have a lot of output. In practice, this means Warp should always be running at 60fps even on 4K or 8K monitors.

Compatibility with Existing Shells: Warp needs to work with popular existing shells like Bash, ZSH, and Fish and with existing keybindings.

Multiplatform, including supporting the Web: Warp needs to run on multiple platforms, including rendering Warp in a browser to support real-time collaboration.

Integration with shells to support blocks (including over SSH): To support features like blocks, Warp needs to be able to integrate deeply with the current running session in the shell.

Arbitrary UI elements: Unlike traditional terminals that mostly just render characters, Warp needs to render arbitrary UI elements (snackbars, overflow menus, etc). This is critical to our vision of making the terminal more accessible and functional.

Native and Intuitive Editing: Warp needs a full text editor to support intuitive editing (e.g. selecting text, cursor positioning, and multiple cursors) that users are familiar with from other modern applications.

Rust + Metal

One of the most important priorities when building Warp was speed. Many terminals built on Electron are capable tools but can quickly lag under certain conditions. Since we’re adding a layer of UI on top of the terminal, we wanted to be sure we chose a stack that would allow us to be in the upper echelon of terminals in terms of speed even while rendering more complicated UI elements.

There are quite a few points during the process of outputting text to the terminal screen that can be potential performance bottlenecks for a terminal. A few include:

Reading from the pseudoterminal: Reading from the pseudoterminal (see the Implementing Blocks section for more context on what a pseudoterminal is) and parsing ANSI escape sequences can be expensive, especially if there is a program running that prints a lot of output to the screen (such as cating a large file)
Rendering: Depending on the implementation, actually rendering pixels onto the screen can be expensive. If the terminal has output that is constantly changing, this can very quickly cause a terminal to feel laggy and be under 60fps.
Scrolling: Once the terminal viewport is full, new lines that are printed out to the terminal require the previous lines to be scrolled up before re-rendering. Scrolling speed often scales with the number of visible lines in the viewport.

The diagram below shows the output of vtebench for scrolling in various terminals. For some reason Hyper generally could not handle running the benchmarks at all and did not terminate after a reasonable amount of time.

Speed for scrolling a single line in various terminal. This was computed by running the scrolling test from vtebench in various terminals at the same window size. For some reason Hyper generally could not handle running the benchmarks at all and did not terminate after a reasonable amount of time

After a very brief experiment with Electron, we quickly pivoted to building in Rust and rendering directly on the GPU using Metal (Mac’s GPU API). As a low-level systems language, Rust was appealing because of its speed and also its strong developer community: using crates.io for package management was a breeze and our entire team (none of whom had written Rust before) onboarded very quickly with tools like Rustlings. More importantly, Rust has a pretty extensive platform support--allowing us to write in a single language and then build for Mac, Linux, Windows, and ultimately the web by compiling to WASM.

Why Render on the GPU?

Most applications that you use are rendered on the CPU using standard OS frameworks to render. For example, MacOS provides APIs to its Core Graphics framework to render items like shapes and arbitrary paths directly on the CPU. Rendering on the CPU is relatively simple because of these high level APIs for drawing and can be pretty fast for 2D graphics and text. Rendering on the GPU is typically much lower level (there are no equivalent APIs for rendering shapes or text) but performs well for 3D graphics or any task that requires high throughput.

Interestingly, GPU-accelerated rendering for terminals has become fairly standard recently (iTerm, Hyper, Kitty, and Alacritty all support it). It may seem that rendering on the CPU would be better suited since it’s mostly just text and 2D shapes that are being rendered. However, terminal rendering is more complex now than it was in the 80s. Terminals today need to be able to render high resolution text on a 4K display and possibly at a very high FPS since some displays run at 240hz or even higher.

Efficient use of a GPU renderer (minimizing state changes between two frames, rasterizing glyphs only once, and minimizing the number of draw calls) can push rendering on the GPU to 400+ fps, which typically isn’t possible using a CPU renderer.

Eliminating as many software and architectural bottlenecks on the CPU allows us render at well over 144fps, even on a 4K monitor. We chose Metal over OpenGL as our GPU API since we knew we were going to target MacOS as our first platform. The Metal debugging tools in Xcode are excellent, allowing us to inspect texture resources and easily measure important metrics like frame rate and GPU memory size.

But how do you render arbitrary UI elements on the GPU?

Supporting arbitrary UI elements on the GPU is tricky. Rendering on the GPU with Metal is very low level, the API essentially only allows to render triangles using a vertex and fragment shader or to sample from a texture to render images.

The key insight here is that for Warp the only thing we needed to render is rectangles, images, and glyphs (which are often rendered via a texture atlas). Making use of this insight drastically reduced the complexity of using Metal: we built shaders for each of these primitives in around 200 lines of code and don’t need to touch the shaders when adding new UI components since they are composed of these primitives.

However, we still needed a higher level of abstraction to render UI elements on top of the characters rendered as part of the terminal output. The lack of a stable UI framework for Rust has been a known issue for a while (see areweguiyet.com) and the available options get even more bare if you want to support Metal as the rendering backend. Options we considered were Azul and Druid, however both were still very experimental at the time and didn’t support Metal (Druid doesn’t have any GPU rendering backend yet and Azul only supports OpenGL).

Given the lack of stable options, we decided to build our own UI framework in Rust, which essentially amounted to building the architecture of a browser. Though this would have been a significant engineering hit to build this from scratch, we partnered with Nathan Sobo, co-founder of the Atom text editor, who had already started building a Rust UI framework that was loosely inspired by Flutter. We use this UI framework to build an element tree for our app that we can then render using various rendering backends (for now just Metal, but we plan to add OpenGL and WebGL as we support more platforms).

At the rendering level, we started by building primitive abstractions (such as a rect, image, and glyph) that we render in Metal. We compose these abstractions to build higher level elements such as a snackbar, a context menu, or a block. We expect this separation between elements and the actual GPU pipeline to serve us well as we support more platforms that don’t support Metal: all we need to do is reimplement these primitives (<250 lines of shader code) in the respective GPU API while leaving our elements and anything higher in the stack untouched. We hope to open source this UI framework as we iterate on it, we already think it’s a capable framework for rendering in Rust.

Rendering on the GPU has been fruitful thus far: even with many UI elements and a lot of terminal output we are still able to render > 144 FPS. For example, over the past week the average time to redraw the screen in Warp was only 1.9 ms!

Implementing Blocks

The reason you don’t see a feature like blocks (with the exception of Upterm) in most other terminals is because the terminal has no concept of what program is running, or really of anything that’s happening within the shell. At a high level, a terminal reads and writes bytes from a pseudoterminal to interact with the shell. This technology is very antiquated--the shell essentially thinks it is interacting with a physical teletype terminal even though they haven’t been used in practice in over 30 years!

A terminal implements the VT100 spec, which is used to communicate information from the shell to the terminal. For example if the shell wants to tell the terminal to render text red, bold, and underline it would send the following escape code, which the terminal then parses and renders with the appropriate styles:

\033[31;1;4mHello\033[0m

https://stackoverflow.com/questions/4842424/list-of-ansi-color-escape-sequences covers how colors are represented via escape sequences very well. It’s also just generally one of my favorite stackoverflow answers--make sure to read the interlude!

Given all the terminal sees is characters in and characters out, trying to determine when a command is run is next to impossible using just the characters from the pseudoterminal.

Thankfully, most shells provide hooks for before the prompt is rendered (zsh calls this precmd) and before a command is executed (preexec). Zsh and Fish have built in support for these hooks. Though bash does not have built in support for these hooks, scripts like bash-preexec exist to mimic the behavior of other shells. Using these hooks, we send a custom DCS (Device Control String) from the running session to Warp. This DCS contains an encoded JSON string that includes metadata about the session that we want to render. Within Warp we can parse the DCS, deserialize the JSON, and create a new block within our data model.

Data Model

The VT100 spec represents the viewport in terms of rows and columns which naturally leads to most terminals using a grid as their internal data model. We started by forking Alacritty’s model code, which was well suited for us because it was already written in Rust and is tailored to be as performant as possible. Nathan Lilienthal and Joe Wilm, two of the maintainers of Alacritty, were early supporters of Warp and were extremely gracious in reviewing early design docs and providing their technical expertise.

We quickly realized, however, that a single grid would not work for building a feature like blocks: separating commands from each other requires ensuring that terminal output is actually written on separate lines of a grid and can’t be overwritten by output from another command. Neither of these can be guaranteed by the VT100 spec. For example, consider a command like

bash-5.1$ printf "hello"
hellobash-5.1$

Here printf "hello" output the text "hello", but no newline was inserted, so the prompt for the next command was inserted on the same line. Similarly, escape sequences exist that allow moving the cursor up within the visible screen by n rows, allowing any command to overwrite any command that was already executed. With a traditional grid data model, we wouldn’t be able to support the case where a single line had the command from one block and the output from another. We also didn’t want the output from one command to be able to overwrite the contents from a previous block.

To fix these issues, we create a separate grid for each command and output based on the precmd/preexec hooks we receive from the shell. This level of grid isolation ensures we can separate commands and their output without having to deal with the output of one command overwriting that of another. We found this approach to be a good balance of being faithful to the VT100 spec and using the existing Alacritty grid code with rendering blocks in a more flexible way that was traditionally prescribed by a teletype terminal. This model gives us more flexibility for implementing features for a single block that are traditionally for an entire terminal grid. For example, searching per block and copying the command/output separately are trivial to implement if our model separates each command and output into their own submodel.

Input Editor

Together with Nathan Sobo, we built a full-fledged text editor as our input editor as an editor view in our framework. Building this as a full text editor unblocked features like multiple cursors and selections within the editor and also will let us use the editor as the default editor within the shell if we ever want to support it.

Because we built our own command line editor, we had to re-implement all the existing shortcuts users are used to while editing (such as up arrow, ctrl-r, and tab completion) while also balancing implementing new modern shortcuts like Move Cursor By Word or Select All that previously didn’t exist in the shell line editor. We built an action dispatching system into our framework that can be triggered based on keybindings so implementing all these shortcuts was relatively trivial. This also made it easy to enable/disable various shortcuts depending on the state of the app: for example “ctrl-r” for searching previous commands should only be enabled if the input editor is visible.

Building the editor also heavily relied on a SumTree, a custom data structure that is essentially a Rope that can hold generic types and can index the type on multiple dimensions.

Like many text editors, we use the SumTree to hold the contents of our buffer. We also use the SumTree for transformations of the editor that don’t affect the underlying buffer contents (such as code folding, holding unselectable and uneditable annotations, etc). Representing transformations as a SumTree allows us to efficiently query for both the buffer text and the display text at any given point in the editor. We also use SumTrees to keep track of the operations (or edits) on the buffer. We intentionally designed our editor to be an Operation-based CRDT from the start, so that we can support real-time collaboration within the editor.

Looking Forward

Looking forward, our stack opens up the ability to realize our full vision of what Warp can be. By choosing Rust and building a UI framework that is rendering-platform agnostic, we can easily scale to other platforms and even the web by compiling to WASM (a mistake we made was to not think about which crates will and won’t compile to WASM early on) and rendering with WebGL.

One feature that the web rendering enables is real-time collaboration. You can share a secure link to your teammate to debug issues in real-time https://github.com/warpdotdev/warp/issues/2.

We can also leverage the “Blocks” model to enable users to search history by more than just the command: https://github.com/warpdotdev/warp/issues/1.

Our precmd and preexec hooks also provide the necessary technical foundation for Environment variable sharing: https://github.com/warpdotdev/warp/issues/3.

** * Edit: When we published this post, we had not set up our Github issues yet. We have since transferred the technical implementation details to Github.*

Conclusion

Performance is one of our most important features--it’s a feature most users won’t notice on a day-to-day basis but it makes a huge difference in building a quality product for the end user.

If you’re interested in learning more, please check out our site and request early access to our beta here. We are still in the early days of implementing our vision but would love your feedback and input as we move forward!

Rust's Rules Are Made to Be Broken

Charles Pierce — Wed, 02 Mar 2022 17:18:43 +0000

We’ve talked in the past about why we chose to build Warp in Rust. Since making that decision, one thing that stands out is how productive we are as a team while still reaping the performance benefits of a systems level language. A big reason for that productivity is the borrow checker.

By enforcing its rules at compile time, Rust’s borrow checker is able to make guarantees about the memory safety of our app, which lets us focus more of our energy on building the future of the terminal and less on chasing down use-after-free bugs.

At the same time, the borrow checker can be a source of frustration. Sometimes, you need to do something that breaks the rules but don’t want to throw the safety out the window. Fortunately, the Rust standard library provides helpful types to let you do just that: break the rules!

Shared Ownership

The first borrow checker rule we’re going to break is single ownership: By default in Rust, every piece of data has a single owner, and when that owner goes out of scope, the data is cleaned up. This is great for ergonomics as you don’t have to worry about manually allocating and freeing memory! [1]

However, sometimes you don’t want data to have only a single owner. Maybe you want the data to pass through different parts of your program that will each run for different lengths and there’s no way to know how long in total the data needs to exist. Maybe you’re prototyping and don’t yet want to tackle ownership and lifetimes in a more concrete way. Whatever the reason, you really would like to have multiple owners for some data, so that it lasts as long as all of them combined.

Reference counting to the rescue!

Built into the Rust standard library are two types that provide shared ownership of the underlying data: Rc and Arc (short for ‘Reference counted’ and ‘Atomically reference counted’, respectively).

Both of these types give shared ownership of the contained data by tracking the number of references and ensuring the data will last as long as there are any active references. They each implement Clone and Drop: cloning increments the reference count while dropping one decrements it. The data is kept alive as long as there are references and only cleaned up once all of the clones have gone out of scope. For example, this snippet uses Rc to share ownership of two pet objects between two owners:

#[derive(Debug)]
struct Pet {
    name: String,
}

impl Pet {
    fn new(name: String) -> Self {
        Self { name }
    }
}

struct Person {
    pets: Vec<Rc<Pet>>,
}

fn main() {
    // Create two pets with shared ownership
    let cat = Rc::new(Pet::new("Tigger".into()));
    let dog = Rc::new(Pet::new("Chase".into()));

    // Create one person who owns both pets
    let brother = Person {
        pets: vec![cat.clone(), dog.clone()],
    };

    // Create another person who _also_ owns both pets
    let sister = Person {
        pets: vec![cat, dog],
    };

    // Even if one person gives up ownership, the other person still has shared ownership,
    // so the pets are kept around (yay!)
    drop(sister);
    println!("Pets: {:?}", brother.pets)
}

Both types incur a small amount of runtime overhead to maintain the reference count. The key difference between them is that Arc is thread safe, while Rc isn’t. Arc uses atomic operations to manage the reference count, which gives it a higher runtime cost but makes it safe to share between threads. If you’re only working in a single thread, then Rc is the faster alternative.

The last important fact about Rc and Arc is that they only allow you to get immutable references to the underlying data.[2] Since they fundamentally represent shared data, allowing mutable references would violate Rust’s safety guarantees by allowing for data races and use-after-free errors.

Unique Borrows

“But wait!,” you say, “What if I want to share mutable data between parts of my app?” Luckily, the next borrow checker rule we’re going to break is unique borrows: In order to mutate something, you need to have a unique (also called mutable) reference to the data. The borrow checker enforces that you can only have one mutable reference or any number of immutable references, but never a combination of the two, so you can’t ever mutate data that another part of the program is trying to read at the same time.

This restriction works great most of the time, but we’re here to break the rules! Two cases where you might want to mutate data without having a mutable reference are:

Caching an otherwise immutable calculation (i.e. memoization)
The above shared ownership case with Rc or Arc
For bending the compile-time borrowing rules, the compiler provides several helpful types, each with their own sets of drawbacks. All of them let you safely mutate data behind an immutable reference, using different approaches to make sure that your program is still safe.[3]

RefCell
First up is RefCell, which moves the enforcement of unique borrows from compile-time to runtime. Similar to Rc, RefCell uses reference counting to track how many borrows are active while the program is running. If you ever try to take a mutable reference and another reference at the same time, RefCell will immediately panic! So when using RefCell, it’s up to you to make sure that your program doesn’t try to read and write the same data at the same time.

Here's an example of using RefCell to cache intermediate results for something that is otherwise immutable:

struct FibonacciCalculator {
    cache: RefCell<HashMap<usize, usize>>,
}

impl FibonacciCalculator {
    /// Calculate the Nth fibonacci number, caching the result to prevent recalculation
    /// Note that this takes `&self`, not `&mut self`!
    fn calculate(&self, n: usize) -> usize {
        // Base case
        if n <= 2 {
            return 1;
        }

        // Check the cache
        if let Some(value) = self.cache.borrow().get(&n) {
            return *value;
        }

        // Calculate and cache the value
        let result = self.calculate(n - 1) + self.calculate(n - 2);

        self.cache.borrow_mut().insert(n, result);

        result
    }
}

Also, the reference counting in RefCell is not thread safe, so it’s not possible to share RefCell data between threads. For mutating shared data between threads, we need to turn to our next tool.

Locking Types
The next two types are Mutex and RwLock, which both provide ways to access mutable references from an immutable reference in a thread-safe way. They do this by completely blocking the thread until it is safe to access the data. This provides a strong guarantee that the access is safe, but also has a major pitfall: Deadlocks. Deadlocks occur when two threads are blocked waiting for access to data that the other thread is holding. Similar to RefCell, it's up to you to make sure the logic of your program doesn't hold onto some data while waiting for access to other data leading to a deadlock.

For example, the following snippet uses a Mutex to increment a counter in parallel in two new threads, then reads the final result from the original thread:

// Create a shared, mutable counter
let counter = Arc::new(Mutex::new(0));

// Spawn one thread incrementing the counter
let counter1 = counter.clone();
let handle1 = thread::spawn(move || {
    for _ in 0..10 {
        *counter1.lock().unwrap() += 1;
    }
});

// Spawn another thread incrementing the counter
let counter2 = counter.clone();
let handle2 = thread::spawn(move || {
    for _ in 0..10 {
        *counter2.lock().unwrap() += 1;
    }
});

// Wait for the threads to complete
handle1.join().unwrap();
handle2.join().unwrap();

// Will write "Value: 20", since each thread incremented the counter 10 times.
println!("Value: {}", *counter.lock().unwrap());

The key difference between the two types is how they handle different kinds of access. A Mutex doesn’t care about whether you are trying to read or write the data, only a single thread can have access at a time. All other threads have to wait until the current consumer gives up their access.

By contrast, RwLock follows Rust’s rules: Any number of threads can have read-only access to the underlying data or a single thread can have write access, but no combination. Attempting to obtain write access will block until there are no active readers and vice versa.

The thread safe nature of these locking types makes them some of the most powerful ways to share mutable data, however it comes at potentially significant performance cost: Locking the thread so that no other work can be done until the data is available. If our data is simple enough, the last type we’re going to look at can provide shared access across threads without needing to lock.

Atomics

Atomic types are available for integer and boolean primitives. These types all provide methods to mutate or read the data as a single operation, so that nothing can happen in between and there is no possibility for data races.

For example, if you want to increment a counter, instead of reading the value, adding one, then writing the value, you would use the fetch_add method that does all of that in a single block.

Atomics are often used as the building blocks for more complicated thread-safe sharing or one-off initialization. As mentioned above, Arc uses an atomic counter internally to manage the reference counting in a thread-safe way.

The beauty of all of these types is that they provide a way to break the borrow checker rules while still maintaining Rust’s safety guarantees. Understanding which rules each type breaks is the key to knowing which tool you need. If you’re looking for shared ownership without copying, you want the reference counted types. If you’re looking for mutability without Rust’s strict mutable references, reach for interior mutability. And if you need shared mutable state, it’s not uncommon to use a combination of them: Rc<RefCell<T>> or Arc<Mutex<T>> are combinations for single- and multithreaded shared mutable ownership, respectively.

If you’re interested in breaking more of Rust’s rules and pushing the terminal into the future, we’re hiring at Warp! Or if you’d just like to check out our Rust-based terminal, request early access below:

Request early access to Warp

Using tree data structures to implement terminal split panes - more fun than it sounds

Yunfan Yang — Wed, 19 Jan 2022 19:35:26 +0000

Most popular command line tools and code editors like VSCode and Tmux support split panes: they provide a handy way for users to visually organize different workflows and keep track of processes that are happening in parallel. One of the first things I learned when doing web development was to have two panes – one for running the server and one for checking and pushing code to Github.

Using split panes is one thing; building them is another. I never thought I would need to build split panes from scratch until I joined Warp – at Warp, we are building a high-performance terminal written entirely in Rust.

As part of building it, we had to build native split panes. Here are our key product requirements. Developers should be able to:

Infinitely split the screen in any direction (approximately).
Remove panes from the screen.
Navigate across panes with arrow keys.
Arbitrarily resize panes.

Representing panes in a two dimensional array?

The first piece is figuring out what data structure to use to represent these panes. The first data structure that comes to mind to represent panes is a two dimensional array. Intuitively, it has some great properties we could take advantage of: for example, it captures how panes are laid out visually, so if we want to navigate in a certain direction, we simply need to change the row and column index to get the target pane. Pushing new panes is straightforward as well, we just need to either insert it into an empty cell or create a new row/column if the cell is currently occupied.

Figure 1: Example of a screen split into four panes and its representation with a two dimensional array.

Intuitive as it may be, we encountered some issues:

Representation ends up becoming sparse: Users should be able to split the panes in any arbitrary way – they could have two panes on row 0 and five panes on row 1. This will fill the two dimensional array with many empty cells. As a result, navigation becomes harder since simply increasing or decreasing the current cell's row/column index might lead to an empty cell.
Performance does not scale: Inserting and removing panes could be memory expensive. For example, if we need to insert a new pane to the right of pane 0, we will have to allocate a new row and shift the content of every pane in the rows after. This will get increasingly expensive as users create more panes.

Representing panes with trees

The Zed editor (originally created by Nathan Sobo) provides an interesting approach: using trees to represent panes. Trees are well suited for this problem:

Trees could be unbalanced: This solves the obstacle we had when using the two dimensional array as we could split panes in any arbitrary way and still represent them efficiently in a tree.
Trees could be recursive: We won’t need to worry about allocating an entire new row or column for each pane. Instead, we just need to insert a new branch when a user adds another pane.
Trees could be hierarchical: We could represent the relationship between panes and their sub-panes with parent nodes and child nodes.

Each tree can have only two different types of nodes – a branch or a pane node. A pane node, as its name suggests, represents a pane on the screen. This should always be a leaf node within a tree. A branch node holds information about the spatial relationships between its children. In our use case, the branch node represents the direction a pane is split, which can be either vertical or horizontal. An example of how a snapshot of pane state could be represented as a tree is shown below.

Figure 2: Example of a screen split into three panes and its representation with a tree.

The way we define pane trees and their components in Warp looks like the following:

Node {
    BranchNode,
    PaneNode,
}

Direction {
    Horizontal,
    Vertical
}

BranchNode {
    split_direction Direction,
    children Node[],
}

PaneNode {
   id,
}

How to Add and Remove Panes?

After we settled on trees as the data structure, we had to figure out how to modify these trees to add and remove panes.

For adding panes, we could consider it as “splitting” the current pane node into a branch with two child nodes. For example, in the simple case when user hits split horizontally on a single pane, the tree before and after the action would look like the following:

Figure 3: Change of tree state when adding a new pane

What about panes that are nested under other branches? This becomes more complicated as we could have two different scenarios: splitting in the same direction and splitting in a different direction as the parent branch.

_Splitting in the same direction_

_Splitting in a different direction_

The algorithm we use here is to recursively traverse down the tree until we locate the deepest branch that hosts the current pane (depth-first search). In case the branch’s split direction is the same as the new pane’s split direction, we simply insert a new pane node into the children vector. When the split direction is different, we instead replace the pane node with a new branch node that has the new split direction and the current and new added panes as its children.

Removing panes is very similar to the reverse of adding panes. There’s one special case we need to keep in mind – if a branch node has only one pane node, we should collapse them into one pane node as there is no longer a “split”. Thus the algorithm should keep track of the branch’s children size after removing the target pane, once it’s below the size of two, we return the last pane node and the parent branch should replace the branch node with the returned pane node.

With regard to the performance of adding and removing panes, the run-time complexity should be O(N) where N is the number of nodes in the tree. The main source of algorithm runtime is from the depth-first algorithm used to locate the current pane. The memory complexity should be O(1) since we only need to change the target pane and its parent branch at most.

/// Tree for all of the split panes
///
/// Holds the root node.
pub struct PaneData {
    pub root: PaneNode,
}

/// Single Node in the tree of panes.
pub enum PaneNode {
    /// A collection of terminals split in a specific direction
    Branch(PaneBranch),
    /// A single terminal
    Leaf(EntityId),
}

/// The result of attempting to remove a pane from a branch
enum BranchRemoveResult {
    /// The pane was not found in this sub-tree
    NotFound,
    /// The pane was found and removed, no further action is needed
    Removed,
    /// The pane was found and removed, leaving only a single node in the branch, so it needs to
    /// be collapsed into the parent
    Collapse(PaneNode),
}

pub struct PaneBranch {
    axis: SplitDirection,
    pub nodes: Vec<PaneNode>,
}

impl PaneData {
    pub fn split(
        &mut self,
        old_session_id: EntityId,
        new_session_id: EntityId,
        direction: SplitDirection,
    ) -> bool {
        self.root.split(old_session_id, new_session_id, direction)
    }

    pub fn remove(&mut self, session_id: EntityId) -> bool {
        self.root.remove(session_id)
    }
}

impl PaneNode {
    fn split(
        &mut self,
        old_session: EntityId,
        new_session: EntityId,
        direction: SplitDirection,
    ) -> bool {
        match self {
            PaneNode::Leaf(session) => {
                if *session == old_session {
                    *self = PaneNode::Branch(PaneBranch::new(old_session, new_session, direction));
                    true
                } else {
                    false
                }
            }
            PaneNode::Branch(branch) => branch.split(old_session, new_session, direction),
        }
    }

    fn remove(&mut self, session_id: EntityId) -> bool {
        match self {
            // Leaves can only be removed from the containing branch
            PaneNode::Leaf(_) => false,
            PaneNode::Branch(branch) => match branch.remove(session_id) {
                BranchRemoveResult::NotFound => false,
                BranchRemoveResult::Removed => true,
                BranchRemoveResult::Collapse(last_node) => {
                    *self = last_node;
                    true
                }
            },
        }
    }
}

impl PaneBranch {
    fn new(old_session: EntityId, new_session: EntityId, axis: SplitDirection) -> Self {
        PaneBranch {
            axis,
            nodes: vec![PaneNode::Leaf(old_session),PaneNode::Leaf(new_session)],
        }
    }

    fn split(
        &mut self,
        old_session_id: EntityId,
        new_session_id: EntityId,
        direction: SplitDirection,
    ) -> bool {
        for (idx, (_, node)) in self.nodes.iter_mut().enumerate() {
            match node {
                PaneNode::Branch(branch) => {
                    if branch.split(old_session_id, new_session_id, direction) {
                        return true;
                    }
                }
                PaneNode::Leaf(pane) => {
                    if *pane == old_session_id {
                        // If the split comes in the same direction as the previous splits
                        // on this sub-tree, we can insert the new pane into the nodes directly
                        if direction == self.axis {
                            self.nodes.insert(
                                idx + 1,
                                PaneNode::Leaf(new_session_id),
                            );
                        } else {
                            // Otherwise, split the current leaf into a perpendicular branch
                            *node =
                                PaneNode::Branch(PaneBranch::new(*pane, new_session_id, direction));
                        }
                        return true;
                    }
                }
            }
        }
        false
    }

    fn remove(&mut self, session_id_to_remove: EntityId) -> BranchRemoveResult {
        for (idx, (_, node)) in self.nodes.iter_mut().enumerate() {
            match node {
                PaneNode::Branch(_) => {
                    if node.remove(session_id_to_remove) {
                        return BranchRemoveResult::Removed;
                    }
                }
                PaneNode::Leaf(pane) => {
                    if *pane == session_id_to_remove {
                        self.nodes.remove(idx);
                        if self.nodes.len() == 1 {
                            // Safety: We know that there is an element in `self.nodes`
                            return BranchRemoveResult::Collapse(self.nodes.pop().unwrap().1);
                        } else {
                            return BranchRemoveResult::Removed;
                        }
                    }
                }
            }
        }

        BranchRemoveResult::NotFound
    }
}

Navigating Panes with Arrow Keys

One challenge we encountered when creating split panes was supporting navigation with arrow keys in a way that mapped to the visual layout of the panes. Although visually the panes are organized in two dimensional space, the pane tree does not maintain the spatial knowledge of which panes are next to each other. Take the state below as an example: when the user hits the right key on the top left corner, in a two dimensional array representation, we might just increment the column index by 1 to get the top right pane. However, in a tree representation, we will need to first traverse up the tree until we find a branch with the same split direction as our navigation direction and then traverse down that subtree until we hit the target node.

Figure 4: How navigation with arrow keys works in the tree structure.

Since multiple nodes could exist in the sub-tree, one heuristic we use to make the navigation experience more natural is to focus on the first child node if the navigation direction is right or down and focus on the last child node if the direction is left or up. In the end, the run-time complexity of navigation will also be O(N) as the depth-first search to locate the current pane is O(N) and traversing up to locate the target pane is O(N) as well.

fn find_pane_by_direction(
    &self,
    session_id: EntityId,
    direction: Direction,
) -> FindPaneByDirectionResult {
    for (idx, (_, node)) in self.nodes.iter().enumerate() {
        let res = node.pane_by_direction(session_id, direction);

        match res {
            FindPaneByDirectionResult::Found(_) => return res,
            FindPaneByDirectionResult::Located => {
                // If the axis is different, we left for the parent branch to handle.
                if direction.axis() != self.axis {
                    return res;
                }

                let target_pane_id = match direction {
                    Direction::Left | Direction::Up => {
                        if idx == 0 {
                            return res;
                        }
                        self.nodes[idx - 1].1.last_pane()
                    }
                    Direction::Right | Direction::Down => {
                        if idx == self.nodes.len() - 1 {
                            return res;
                        }
                        self.nodes[idx + 1].1.first_pane()
                    }
                };

                if let Some(id) = target_pane_id {
                    return FindPaneByDirectionResult::Found(id);
                } else {
                    break;
                }
            }
            FindPaneByDirectionResult::NotFound => (),
        }
    }
    FindPaneByDirectionResult::NotFound
}

Representing Pane Sizes

Every pane should be resizable. Due to how all panes together occupy a space with set dimensions, resizing one pane will lead to the resizing of multiple other panes as well. For example, in the case where one screen is split into four equal panes, dragging the border in the center will actually cause all four panes to be resized as shown below.

Figure 5: Resizing one pane could lead to multiple other panes to resize as well.

With this ripple effect of individual pane sizes, saving the absolute pane size in each node is undesirable as we will need to recalculate all sizes on each resize call. Thus, we decided to save the ratio each child node takes of the branch node’s size instead (we call it the flex ratio). When rendering, we pass in the available size from the root node and go down the branches, deriving each individual pane size based on the split direction and the flex ratio in the branch node. If you want to know more about how Warp renders on the GPU with its native UI framework, check out our blog post here!

The new BranchNode will look like:

BranchNode {
    split_direction Direction,
    flex_ratio f32[], # this should add up to 1.0
    children Node[],
}

Figure 6: An example of how we derive the absolute size for each pane using the flex ratio, assuming we start with a screen with dimension 1024 by 768 and the pane is split into four panes. We could walk down from the root pane to first derive the dimensions of the branch nodes and then use that information to calculate the absolute size of each individual pane.

Summary

Personally, I’m a big fan of how the simple split pane UI makes the terminal so much more powerful. It’s been really exciting to work on designing and programming the split pane functionality within Warp myself. Although there are still many remaining features yet to be implemented that are available in iTerm and Tmux (drag and drop panes!), having a native implementation of the split pane unlocks many more possible things we could do in Warp to make the developer experience even better.

Join our waitlist and let us know what we could make to further improve split panes in Warp!

How to draw styled rectangles using the GPU and Metal

Michelle Lim — Thu, 18 Nov 2021 17:35:12 +0000

This is a tutorial on drawing styled rectangles using Metal graphics shaders. Learn how to draw a rectangle, add borders, round the rectangle’s corners, and fill the rectangle with linear gradients.

Why render on the GPU

For apps that require fast rendering, such as video processing apps or 3D game apps, using the GPU for rendering is often required. The GPU has more cores and so can perform data-parallel calculations like calculating pixel position and color very quickly.

The tradeoff of using the GPU is that we have to implement shaders. However, for a modern UI app, you'd only have to implement them for glyphs, icons, and rectangles. Warp's UI, for example, is entirely composed of those three primitives.

This tutorial will focus just on shaders for rectangles. The snack bar, centered at the top of the window, is just a rectangle with a border and rounded corners.

We will walk through drawing a rectangle, adding borders, rounding the rectangle’s corners, and filling the rectangle with a linear gradient. We will cover interesting graphics concepts like distance fields, vector projections, and antialiasing.

This tutorial is aimed at beginners who are new to GPU rendering. The code examples are in Metal, Apple’s official shader API.

Here is the table of contents: you can feel free to jump to any section.

Why render on the GPU
How to draw a basic rectangle using shaders
How to draw borders on a rectangle using shaders
How to draw rounded rectangles using shaders
How to fill rectangles with gradients using shaders
Putting it all together

How to draw a basic rectangle using shaders

We provide instructions to the GPU via a pair of functions: the vertex shader and the fragment shader. The vertex shader’s job is to produce the positions that need to be drawn. The fragment shader takes these positions and determines the color for every pixel within these position boundaries. In the case of a triangle, the vertex shader produces the three vertices, and the fragment shader fills the triangle pixel by pixel.

Let’s draw a rectangle with shaders.

For the vertex shader, we normalize the coordinates of the vertex to be independent of the viewport. Concretely, we do this by dividing the coordinates by half of the viewport (see the diagram above from these Apple Metal docs).

For the fragment shader, we can return the interpolated color of the pixel.

Here is the code we’re using. Notice that we also pass in PerRectUniforms—a struct that holds the origin, size, and color information of the rectangle the vertex comes from. This information helps us infer information about each vertex and calculate the color of each pixel.

rect_vertex_shader(
   uint vertex_id [[vertex_id]],
   constant vector_float2 *vertices [[buffer(0)]],
   constant PerRectUniforms *rect_uniforms [[buffer(1)]],
   constant Uniforms *uniforms [[buffer(2)]]
) {
   float2 pixel_space_position = vertices[vertex_id] * rect_uniforms->size + rect_uniforms->origin;
   vector_float2 viewport_size = uniforms->viewport_size;

   RectFragmentData out;
   out.position = vector_float4(0.0, 0.0, 0.0, 1.0);
// Normalize coordinates of the vertex
   out.position.xy = pixel_space_position / (viewport_size / 2.0);
   out.position.z = rect_uniforms->z_index / uniforms->max_z_index;
   out.color = rect_uniforms->background_color;

   return out;
}

fragment float4 rect_fragment_shader(RectFragmentData in [[stage_in]])
{
   return in.color;
}

For brevity, we’ll focus only on writing the shaders for the rendering pipeline. We recommend:

Apple’s ‘Using Metal to Draw a View’s Content’ to learn how to use MetalKit to create a view and send rendering commands to draw on it
Apple’s ‘Using a Render Pipeline to Render Primitives’ explains how to use the shaders in the rendering commands to draw a shape on the view.

We used the code above, along with MetalKit and our custom layout engine, to draw the first iteration of tabs in Warp.

How to draw borders on a rectangle using shaders

While drawing borders, the rectangle stays the same size and shape. Hence, we do not need to alter our vertex shader. Instead, we just have to edit the fragment shader.

The fragment shader processes a pixel at a time. For each pixel, we have to figure out whether it is inside or outside the border. First, we calculate the border boundary by subtracting the border widths corresponding to the pixel’s quadrant. If the pixel is above and to the right of the center of the rectangle, then we should subtract the rectangle corner by the border top and the border bottom.

And so on and so forth:

fragment float4 rect_fragment_shader(
       RectFragmentData in [[stage_in]],
constant Uniforms *uniforms [[buffer(0)]])
{
   vector_float2 border_corner = in.rect_corner;
   if (in.position.y >= in.rect_center.y) {
       border_corner.y -= in.border_bottom;
   } else {   
       border_corner.y -= in.border_top;
   }
   if (in.position.x >= in.rect_center.x) {
       border_corner.x -= in.border_right;
   } else {
       border_corner.x -= in.border_left;
   }
   ...

}

With the border corner obtained, we can then assign pixels outside the border corner with the border color, the ones inside with the background color.

...
return in.position.xy > border_corner ? border_color : background_color;

And that’s how we form the bordered rectangle in Warp’s tab bar:

How to draw rounded rectangles using shaders

To round the corners of the rectangle, we need a framework that tells the the fragment shader whether a pixel falls inside or outside a rounded edge.

Distance fields are functions that help us define non-rectangular edges. Given a pixel, a distance field outputs its distance to the nearest edge of a shape. This is a useful API for fragment shaders, which only has access to one pixel at a time.

Using distance fields to express rounded corners

The following diagram draws out four distance fields of a rectangle (lines). Each line represents pixels that are the same distance away from the edge of a rectangle, similar to contour maps in geography. Notice that each distance field matches the outline of rounded rectangles.

A rounded rectangle is simply a union of a “shrunk rectangle” and the area within the distance field of size corner_radius.

We derive the new rectangle corner of the shrunk rectangle by subtracting the corner radius from the original rectangle corner. We want pixels outside the shape to be transparent, i.e. for the alpha channel of its color to be 0. And pixels inside to be opaque, i.e. alpha = 1.

The distance field of our rounded shape is simply the distance field of the shrunk rectangle minus the corner radius.

The formula for distance field of a rectangle is:

Where p is the vector of the pixel, and R is the vector of the rectangle corner. Check out Inigo Quilez’s derivation of the distance field function here.

The actual R of the shrunk rectangle is rect_corner-corner_radius. Substituting that in gives us a distance function for the shrunk rectangle. We then get the distance function for the rounded rectangle by subtracting the corner radius.

float distance_from_rect(vector_float2 pixel_pos, vector_float2 rect_center, vector_float2 rect_corner, float corner_radius) {
   vector_float2 p = pixel_pos - rect_center;
   vector_float2 q = abs(p) - (rect_corner - corner_radius);
   return length(max(q, 0.0)) + min(max(q.x, q.y), 0.0) - corner_radius;
}

Anti-aliasing

The code above will render a rectangle with rounded corners. However, the rounded edges will look jagged:

From learnopengl.com

This happens because there is a sharp cutoff between the pixels inside the shape and outside the shape. We only encounter this issue now because with rounded corners, the edges of our shape do not fit squarely into the pixel grid of a screen. The solution is to gradually transition the pixel color across the boundary. A handy function is smoothstep(edge0, edge1, x) which performs a smooth Hermite interpolation between 0 and 1 when edge 0 < x < edge1.

if (corner_radius > 0) {
   color.a *= 1.0 - smoothstep(-0.75, -0.1, shape_distance);
}

For rounded rectangles with borders, we perform the same antialiasing between the background and border. Here in this code, background_distance refers to the distance field from the non-border contents of the rectangle.

background_distance = distance_from_rect(in.position.xy, in.rect_center, border_corner, corner_radius);
if (border_color.a != 0) {
   color = mix(background_color, border_color, smoothstep(-0.5, 0.5, background_distance));
}

Now, we can render rounded bordered UIs like in Warp:

How to fill rectangles with gradients using shaders

Linear gradients can be specified by a start and end color, as well as the starting coordinates and the ending coordinates. For example, we can specify a horizontal gradient using (0,0) and (0,1) as coordinates.

We can perform the mixing of the colors with Metal’s mix function: mix(start_color, end_color, h). It returns the linear blend of start_color + (end_color – start_color) * h.

We want the variable h to represent the progression of the pixels along the direction of the gradient. To do so, the trick is to project the position of the pixel to the direction of the gradient. Pixels closer to the end of the gradient will have a larger magnitude and pixels closer to the start of the gradient will have a smaller magnitude.

float4 derive_color(float2 pixel_pos, float2 start, float2 end, float4 start_color, float4 end_color) {
   float2 adjusted_end = end - start;
   float h = dot(pixel_pos - start, adjusted_end) / dot(adjusted_end, adjusted_end);
   return mix(start_color, end_color, h);
}

We can now produce gradient UI elements, like this header in Warp:

Putting it all together

You can read through the complete code sample here.

Alongside glyphs and images, the rectangles we produce from these shaders form the UI surface of Warp. Using the GPU for rendering is what enables us to render large amounts of terminal text and UI at over 60fps on a 4K screen.

Our newer and more complicated UI components are compositions of these building blocks. This has enabled us to create a robust and maintainable UI framework. The code for all our primitives span only 300 lines.

If you want a fast performant terminal with modern UI, come join our waitlist on our website here.