philipp's blog

hecto: Appendices

🏗️ Construction Notice

The old (complete, but outdated) version of hecto is available here. You are looking at the 2024 version of hecto, which is still unfinished. You can follow the progress of the rewrite here. Once it’s done, this notice will be deleted.


How the annotated commits work

Most steps in this tutorial are presented as a link to an annotated commit. Each commit shows you the changes you need to make to the previous step’s code to get to the current step, with comments explaining each interesting code line.

Here is an example commit.

Each diff contains one block per modified file. Each block starts with a header that contains the filename of the file you need to edit ("src/main.rs"). After the header, the contents of the file are shown. Additions are highlighted in green, deletions in red. The old line numbers are printed at the left, the new line numbers on the right. Comments are displayed below each interesting code line, with the label (Author) telling you that the same person who did the commit did the comment (me).

On the top right, you will find two important settings:

Further, on the top right of a code block, you find a ... button. Clicking on it allows you to hide the comments, to focus on the change itself. For example, this link brings you to the verbose version with comments, which helps you to reason about each code line. This link brings you to a more concise version of the same change without comments or whitespace changes.

What to do if you are stuck

The first few commits are designed for you to follow along and copy them.

Some of the code in this tutorial is very tricky to type in exactly, especially if you’re not used to Rust. It’s specially easy to make a mistake when you’re making a change to a line, and you think you’re done changing that line, but you missed one little change to another part of that same line. It’s important to take your time, and compare the changed parts of the diff character-by-character with your code to make sure they’re the same.

If you suspect you made an error, but don’t know where it is or how far back you might’ve made the error, you should get your computer to do a diff between your version of hecto and the tutorial’s version of hecto for whatever step you’re on.

You will need git to do this. To install git, follow these official instructions. Once you have git installed, clone the hecto-tutorial repository by running git clone https://github.com/pflenker/hecto-tutorial.git. cd into the repo using cd hecto-tutorial. Each link to a commit has a commit ID on the top left side, which you can check out.

To check out the commit above, you’d type:

$ git checkout 2e090ab

The folder then contains all files with the contents of that step.

You can compare your files with files of this folder by running something like git diff --no-index -b ../path/to/your/main.rs main.rs . This will show you the changes you would need to make to your main.rs to get it to look like the one in the repo. The -b option ignores whitespace, so it won’t matter if you use a different indent style than the one in the tutorial.

After some time, you’ll get assignments to try and solve on your own. I recommend to use the last commit from me before the assignment as a starting point for your own experiments. That way, you can compare your current state to the next commit from me once you’re stuck.

To compare your current code with the commit above, you’d type:

$ git diff 2e090ab

Where to get help

The easiest way to get help is commenting directly on code lines you don’t understand on GitHub. If your question is not directly related to a specific code line (or you’d rather not use GitHub), and the hints above are not sufficient to help you out, feel free to contact me. You can find several ways of reaching me on my home page.

Ideas for improvements and features

If you want to extend hecto on your own, I suggest trying to actually use hecto as your text editor for a while. You will very quickly become painfully aware of all sorts of features you’re used to having in a text editor, but are missing in hecto. Those are the features you should try to add. And you should use hecto when you work on hecto.

If you're still looking for ideas, here's a small list. If you complete some of them, let me know!

Why I wrote hecto

Back in 2019 (when I wrote the first version of this tutorial), I was mostly only familiar with JavaScript. Sure, I had some Java experience in the past, but over the years this knowledge has started to fade.

At the same time, Rust was the fairly new kid on the block, so I was looking for a way to learn it. My first idea was to play around with a web server, but then it occurred to me that this would be close to what I always do when I try out shiny new things. Then one day, Paige Ruten’s excellent tutorial to build your own editor in C hit the Front Page of Hacker News (again), sparking the idea of this tutorial. kilo is complex enough to pose a challenge, and thanks to Paige it’s sufficiently well understood so that I could focus on learning the language without getting lost in the details of implementing a text editor.

The Name

hecto follows more modest goals than kilo. After all, I just took a pre-existing idea and rewrote it, so it seemed prudent to choose a “smaller” name for my final project1.

Contributions

Contributions are welcome! There are three types of them:

Please note that I do not offer a Code of Conduct at this point, and that sending me any contribution does not guarantee that it will make its way into the tutorial text or code. This is a pet project of mine, not my full-time job. Be nice.

Credits

Salvatore Sanfilippo aka antirez is the author of kilo. He wrote a blog post about it, in which he explains how he reused code from two of his other projects to quickly throw together kilo in just a few hours during a couple already busy weekends.  kilo was the starting point upon which Paige Ruten has built her own version of kilo. How she did it is described more thoroughly in a text of hers which is eerily similar to this one. Then she turned this into an incredible tutorial called “Build Your Own Text Editor”, which is basically what I remixed into the tutorial you’re looking at right now. If you want to know more about Paige, visit viewsourcecode.org.

I have seen Paige’s tutorial popping up on Hacker News frequently and always thought of actually implementing it. Instead, I combined her tutorial with my efforts to lern Rust “the rust way”.

If you want to know more about me, visit philippflenker.com.

License

Attribution & Indication of Changes

Since this work is based on prior work licensed under CC BY 4.0, I am required to properly attribute the original authors indicate the changes I did to the original work, which I’ll happily do here:

These blog posts are based firmly on the original tutorial, but the code has not only been adapted to rust by using the closest Rust counterpart, but by trying to solve things “the Rust way”. All explanations of the original have been checked, revised, adapted to Rust where appropriate, expanded where I found it valuable or otherwise rewritten when I saw the need to.

For anything that you can’t cleanly attribute with this guidance, the following rule probably applies: If it’s insightful or witty, it’s Paige. If it’s redundant, self-evident, dumb or redundant, it’s me.

Acknowledgements

Thanks go out to:

This post is part of the tutorial hecto: Build Your Own Text Editor in Rust. Find more information, especially around licensing and credits, here. This post was last updated 1 week ago.

  1. Explanation: kilo comes from Greek and means 1000, as the original goal of this program was to build a text editor in less than 1000 lines. hecto means 100.

#hecto