Jekyll2026-09-21T03:31:51+00:00/feed.xmlNotes to selfMike Treit's blog.Building the Crafting Interpreters repo on Windows2026-01-11T15:00:00+00:002026-01-11T15:00:00+00:00/programming,/windows/2026/01/11/BuildingCraftingInterprersRepoOnWindows
Crafting Interpreters
I have been hearing about the book Crafting Interpreters, by Robert Nystrom, for a few years now. I have heard nothing but good things about it.
As someone who collects and reads many programming-related books, I decided to order a copy and check it out.
So far, a few chapters in, I am impressed. The book is written in a slightly whimsical style that, given the intimidating nature of the underlying subject matter, makes it much more approachable than it might be otherwise.
As a self-taught programmer who has spent most of their career working on large back-end server systems, I have no experience in things like writing compilers or interpreters. So I am rather looking forward to trying something outside of my usual comfort zone.
Trying out the Lox language
Chapter 3 is a tutorial of the Lox programming language, the language you will be creating interpreters for as you work through the book. As the author points out, it is not much fun to work through a tutorial if you cannot actually try the language, so he suggests starting by running his implementation at the Crafting Interpreters Repo
As the README for that repo points out, Robert does not use Windows and a few extra steps might be required to build the code on Windows rather than just executing his provided makefile.
For instance, the provided makefile uses POSIX commands like find, rm, and printf that don’t work directly on Windows.
The code in question is not very complicated or difficult to build, so instead we will just write some simple PowerShell scripts to take the place of the makefile.
I could have used Windows Subsystem for Linux (WSL) but, well, I do not particularly enjoy programming on linux. I find the experience on Windows much more enjoyable.
So, without further ado, here is a brief guide to how I got things working.
Building on Windows
It ended up not being particularly difficult, just a few steps to get the right tooling installed. I assume you are already using modern PowerShell (pwsh.exe) for the rest of this guide.
What follows covers building the clox (C) and jlox (Java) interpreters from the repo.
The main repository, as of early 2026, uses older Dart dependencies that need updating for modern Dart versions. Edit tool/pubspec.yaml and update the environment and dependencies sections:
# Create build directoriesif(!(Test-Pathbuild)){mkdirbuild}if(!(Test-Pathbuild\release)){mkdirbuild\release}if(!(Test-Pathbuild\release\clox)){mkdirbuild\release\clox}# Compile C source filesgcc-std=c99-Wall-Wextra-Werror-Wno-unused-parameter-O3-flto-cc\*.c# Move object files to build directoryMove-Item*.obuild\release\clox\# Link the executablegcc-std=c99-Wall-Wextra-Werror-Wno-unused-parameter-O3-fltobuild\release\clox\*.o-obuild\clox.exe# Copy to root for convenienceCopy-Itembuild\clox.execlox.exe
Build jlox (the Java Interpreter)
# Create build directoriesif(!(Test-Pathbuild\java)){mkdirbuild\java}if(!(Test-Pathbuild\java\com)){mkdirbuild\java\com}# Compile the AST generator tooljavac-cpjava-dbuild\javajava\com\craftinginterpreters\tool\*.java# Run the AST generator to create generated source filesjava-cpbuild\javacom.craftinginterpreters.tool.GenerateAstjava\com\craftinginterpreters\lox# Compile the jlox interpreterjavac-cpjava-dbuild\javajava\com\craftinginterpreters\lox\*.java
Create jlox.ps1 Wrapper
Create a file named jlox.ps1 in the root directory with this content:
# Wrapper script to run jlox (Java interpreter)java-cpbuild\javacom.craftinginterpreters.lox.Lox$args
Testing the Interpreters
Test clox (C Interpreter)
Run the interpreter in interactive mode:
.\clox.exe
Try some Lox code:
> print "Hello from clox!";
Hello from clox!
> var x = 10 + 5;
> print x;
15
Press Ctrl+C to exit.
Test jlox (Java Interpreter)
Run the interpreter in interactive mode:
.\jlox.ps1
Try some Lox code:
> print "Hello from jlox!";
Hello from jlox!
> var x = 10 + 5;
> print x;
15
Press Ctrl+C to exit.
Run Test Files
You can also run Lox source files directly:
# Create a test file@'
print "Testing clox...";
var a = 1;
var b = 2;
print a + b;
'@|Out-File-EncodingUTF8test.lox# Run with clox.\clox.exetest.lox# Run with jlox.\jlox.ps1test.lox
Notes
For convenience, I have collapsed the build instructions into a single helper script (build.ps1):
# Build cloxWrite-Host"Building clox..."-ForegroundColorGreenif(!(Test-Pathbuild\release\clox)){mkdir-Forcebuild\release\clox|Out-Null}gcc-std=c99-Wall-Wextra-Werror-Wno-unused-parameter-O3-flto-cc\*.cMove-Item*.obuild\release\clox\-Forcegcc-std=c99-Wall-Wextra-Werror-Wno-unused-parameter-O3-fltobuild\release\clox\*.o-obuild\clox.exeCopy-Itembuild\clox.execlox.exe-Force# Build jloxWrite-Host"Building jlox..."-ForegroundColorGreenif(!(Test-Pathbuild\java\com)){mkdir-Forcebuild\java\com|Out-Null}javac-cpjava-dbuild\javajava\com\craftinginterpreters\tool\*.javajava-cpbuild\javacom.craftinginterpreters.tool.GenerateAstjava\com\craftinginterpreters\loxjavac-cpjava-dbuild\javajava\com\craftinginterpreters\lox\*.javaWrite-Host"Build complete!"-ForegroundColorGreenWrite-Host"Run .\clox.exe or .\jlox.ps1 to start the interpreters"
Run with:
.\build.ps1
Conclusion
And there we have it. Now we can play around with the Lox programming language and get a feel for how it works, before moving on to the actual act of implementing our own interpreter for the language.
]]>New Windows Machine Setup - Cheat Sheet2026-01-05T10:00:00+00:002026-01-05T10:00:00+00:00/programming,/windows/2026/01/05/NewMachineThe right tools for the job
Being productive as a programmer starts with having the right set of tools.
Here is my go-to list of tools I always install when setting up a new Windows machine.
]]>The tragedy of ToList()2024-07-30T10:00:00+00:002024-07-30T10:00:00+00:00/programming,/.net/2024/07/30/ToListWhat do you see when you come across code like this?
docList.OrderByDescending(item=>item.Score).ToList().ForEach(item=>{// Do something with item.});
I see a tragic pit of failure for the ignorant, or callous indifference from those who should know better.
Either way, let’s discuss.
A bit of context
C programmers think memory management is too important to be left to the computer. LISP programmers think memory management is too important to be left to the user.
– Ellis and Stroustrup, The Annotated C++ Reference Manual
Automatic garbage collection (GC) in programming languages is a beautiful thing. It frees the programmer to focus on the essence of the problem they are trying to solve, not the minutiae of how the computer hardware actually implements the solution. This is especially true when applying functional programming techniques, where the declarative style of such programs makes how the computation is achieved unimportant compared to what it is achieving.
Newer programmers may have an incorrect impression that GC is a new, modern technique, designed to reduce the longstanding burden of manual memory management imposed by classical languages such as C and C++. This is entirely untrue, of course, as anyone who has studied computing history will know: one of the very first high-level programming languages, predating C by more than a decade, was John McCarthy’s LISP, a functional language that introduced the technique of garbage collection to the world. This was circa 1959, at the dawn of computing, a date so long ago that the modern generation can likely hardly fathom it.
GC makes a bargain with the programmer: leave the memory management to me, at the cost of losing complete control over every aspect of how your program is executed, including things like when memory is freed. This, consequently, means accepting some possible performance overhead and inefficiency in exchange for increased simplicity and correctness. Memory safety and correctness issues are historically one of the greatest sources of bugs in computer software, so in a very large percentage of cases this is a highly acceptable tradeoff.
Even in the world of systems programming, where the mere thought of GC is anathema to the extreme performance requirements and low level control needed in something like your operating system kernel, there is a push towards memory-safe languages like Rust. In a famous tweet, Mark Russinovich declared that we should consider traditional languages like C/C++ deprecated for new projects.
.NET developers have the luxury of working in an ecosystem that is memory safe by default via an excellent Garbage Collector implementation, while also providing escape hatches (unsafe, Span<T>, etc.) to allow optimization in paths where the overhead of GC might be unacceptable.
GC Quick Summary
The actual implementation of GC in .NET is a fairly complex topic; there are a lot of details related to different GC modes, various types of heaps, dealing with fragmentation and large objects, etc. I recommend reading the GC Documentation for details.
We can, however, summarize a few salient points:
The vast majority of the types you define are likely to be classes and, thus, require GC.
Application pauses and high CPU are some of the main performance issues in systems using garbage collection.
The more garbage a program generates, the more work the GC has to do.
GC Abuse
It’s not the garbage collector that’s ruining your process. The garbage is ruining your process!
The code snippet I opened this article with is tragic because it seems at first glance to so many programmers to be entirely reasonable. In fact, this kind of code is very common in my experience. This is even true in codebases where performance is critically important. Imagine a web service attempting to process hundreds or thousands of requests per-second, with minimal latency, filled with code like that.
In the minds of many programmers, more code means slower performance, less code means faster performance. Therefore, one-liners are superior! After all, how much code are we actually executing if it all fits on a single line?
These few innocuous tokens in a single line of code must be almost free, right?
ToList().ForEach(/* ... */)
Nothing could be further from the truth. The tragedy of ToList is that it seems so small, so innocent, a little flourish in the middle of a chain of calls to get us to the next item in the chain.
The issue, of course, is not about calling ToList() in and of itself. There are many reasons to take a sequence of things and turn them into a concrete list. Perhaps we want to perform a binary search, so we need the ability to access specific elements by index. Perhaps we need to make defensive copies before handing those copies to other threads, to avoid thread-safety issues. Perhaps we have a method that only accepts an IList<T> so we need to accommodate it. Or, perhaps we have an expensive LINQ query that we want to ensure only executes exactly once. These and many more possible scenarios are completely acceptable reasons to turn our sequence into a List.
However, that is not what we have in that code snippet.
Consider what the above code does for a moment. It allocates a List for the sole purpose of calling the ForEach method, because that method only exists on the concrete List<T> type. That’s right; unlike what you may have thought, the ForEach method is not part of the IEnumerable type (via LINQ), but is a one-off method defined on List<T>.
To be blunt, that ForEeach method offends the senses. It should not exist.
Why? Because it offers no advantage over simply using a traditional foreach loop, other than being able to make it a satisfying ‘fluent’ one-liner. Which leads to many developers calling ToListsolely for the purpose of calling the ForEach method!
For those of us who care about avoiding completely needless, excessive garbage on the managed heap, this is indeed a tragic misuse of an otherwise fine and upstanding method.
Think about it. We have some (potentially large) sequence of data in memory. It is most likely already backed in memory by some sort of data structure, such as a List, an Array, a HashSet, etc. Yet because we want to call the ForEach method, we make an entire copy of that data in memory, on the managed heap. Copying the array costs time, it costs CPU and it creates a bunch of additional work for the GC. All of this could be avoided by just doing the simple thing and writing a traditional foreach loop.
varorderedList=docList.OrderByDescending(item=>item.Score);foreach(variteminorderedList){// Do something with item.}
Here we have the sane version of this kind of code; no unnecessary copying of the entire list in memory, just a plain old-fashioned foreach loop.
Many developers wonder why LINQ does not provide a ForEach method. The answer is that it violates the philosophy of the functional nature of LINQ, which discourages side effects in favor of an input sequence always producing some result as output. The result can be another sequence or it can be a discrete value, but it always produces some output. In contrast, the ForEach method produces no output value at all; it is only about side effects.
Finally, if you are so enamored with one-liners and method chaining that you cannot live without the silly ForEach method, you can always trivially implement your own:
While the AddFirstTwo method accepts any IEnumerable<int>, in this case the underlying type backing the IEnumerable is already a List! Isn’t the ToList method smart enough to notice this and simply return the underlying list without allocating any memory at all?
This is an unfortunate misconception that I have seen many developers voice. The answer is no, not at all.
ToList must by definition make a new list from the underlying data. That is part of its implicit contract. The method itself is described as:
Creates a List from an IEnumerable.
Note the use of the word ‘Creates’. The method by definition always creates a new list, requiring that the contents are copied into that list from the underlying source. Any other behavior would break all sorts of code that relies on a copy being made, such as the defensive copying for thread safety scenario I mentioned earlier.
I cite this talk often when I give presentations to other developers, as it introduced me to one of my now-favorite programming concepts: non-pessimization.
The idea is to avoid writing ‘pessimized’ code, where we can think of ‘pessimization’ as the opposite of ‘optimization’; that is, going out of your way to write code that makes the computer do more work than necessary, for no good reason whatsoever.
Calling ToList().ForEach() is a perfect example of pessimization in action.
Practice non-pessimization instead. Your garbage collector, and your users, will thank you.
Here is a very simple benchmark showing the difference between using a traditional foreach loop and calling ToList().ForEach() instead:
Take particular note of the memory allocation ratio and think about the impact on the garbage collector.
Finding low hanging fruit using regular expressions
When I explore a codebase for the first time I must admit that one of the first things I do now is simply grep for ToList and see what pops up.
In fact, I have a magic regex that just finds bad code for me. (Should this be a Roslyn code analyzer instead of just a simple regex over the text of the source code? Probably!)
My preferred code search tool is ripgrep from the CLI, so my simple little technique is just this handy PowerShell function:
function bad
{
rg -i "\.(?:ToList|ToArray)\(\)\.(?!As|Json|Node\b|Index|CopyTo|FindLastIndex|AreMore)|Select\(. => .\)|(?:ToList|ToArray)\(\)\.Count > 0" --pcre2 --glob !*test* --glob !*Test* --glob *.cs $args[0]
}
What this attempts to flag, among other things, is the pattern of including a call to ToList() or ToArray() in the middle of a chain of other calls. Very often this means we are allocating a list and then throwing it away, doing nothing of value except creating additional garbage for the GC to have to deal with.
I present the following real-world example I came across recently, which the above regex called out as suspicious:
The original code for this last one really is quite terrible. Any time you see either ToList().Length > 0 or ToArray().Length > 0 or someEnumerable.Count() > 0 you immediately have to wonder why the Any() method was not used instead. Any requires only looking if there are any elements at all. The others require traversing the entire list.
(As a minor style point, using the discard character _ for an actual variable name is also a rather awful choice for readability.)
You may see variants of this anti-pattern, like this one:
Just on the off chance you were not yet convinced that this kind of code should be terminated with extreme prejudice, here is a benchmark of the above scenario.
The results speak for themselves:
Again, not just in terms of potentially much higher latency (47,000 times slower for the large list!) but also in terms of memory usage (again, in this case, 47,000 times more memory for the GC to have to eventually clean up).
Case study - select the first five keys and return them as a list
Let’s examine another concrete example of a call that my “find bad code” regex flagged, once again in some code I was working in not that long ago:
Examine this code for a moment. What do you think? Would you call this out in a code review?
Let’s say that you do, commenting “This code seems inefficient. Do we really need to make a copy of the entire list here before returning?”
You get the reply: “The interface contract requires that we return a List<T> here, so we don’t have a choice.”
Your response?
This code is an instructive microcosm of many similar small programming problems that come up in our day-to-day work all the time. We can distill the interesting part of this code (the part that calls ToList) into the following problem statement:
Given a List<T> of KeyValuePair<string, int>, take the first five items and return their keys as a List<string>.
We will simplify by assuming the list in question has at least five elements, so we can eliminate having to worry about Math.Min for the sake of this discussion.
This seems like a quite simple programming problem and, honestly, it is!
However, not all solutions are created equal.
Let’s briefly sketch out five approaches to solving this:
The original answer our hypothetical developer defended in their code review is unfathomably bad compared to the alternatives. The execution time is exponentially worse and has similarly terrible allocation numbers, meaning once again that choosing the wrong approach can easily create a massive amount of extra work for the GC.
Looking at these results and putting just a little bit of thought into them, it’s not hard to understand why the original code is so bad. Calling ToList() immediately materializes the entire list into memory. So even though we have a lazily evaluated LINQ statement (the Select), that does us no good if the next call is to ToList(), which will copy the entire sequence into a new list in memory.
Again, this is the tragedy of such a simple, innocuous seeming method call. A distracted or inexperienced developer can easily look at this code and think “looks good!” without realizing the performance landmine lurking behind it.
The LINQ variants naturally benefit from lazy evaluation / deferred execution. The LINQ query is always known to limit the results to at most five entries before it is ever executed, so we never need to pay the expense of evaluating more than five items, even if the list is a million items long.
If you’re paying attention you might ask: why is approach #2 allocating so much more memory than approaches #3, #4 and #5? Ask yourself: how many lists does that approach allocate? How many do the others allocate?
This is the kind of thing you need to condition yourself to think about when writing any kind of code that calls ToList or similar methods. Consider what is going on behind the scenes and ask yourself if this might lead to excessive memory allocations or other performance issues.
Finally, we get to see that sometimes the old ways are the best ways; even though it might not be a sleek one-liner, writing a plain old-fashioned for-loop is still 3 to 5 times faster than even the best LINQ version, and allocates 2 to 3 times less memory.
One-liners are not always better.
Nothing is black and white
The following piece of code (taken from the Newtonsoft.json codebase) seems, at first glance, to be ludicrous.
/// <summary>/// Creates an array from an <see cref="IEnumerable{T}"/>./// </summary>publicstaticTSource[]ToArray<TSource>(thisIEnumerable<TSource>source){IList<TSource>ilist=sourceasIList<TSource>;if(ilist!=null){TSource[]array=newTSource[ilist.Count];ilist.CopyTo(array,0);returnarray;}returnsource.ToList().ToArray();}
Specifically, what is up with this?
returnsource.ToList().ToArray();
The overall intent of the method seems clear enough: turn an IEnumerable<T> into an array. Why not, however, just call the existing ToArray() method that is part of LINQ?
Even if there is some justification for detecting an IList<T> and hand-writing the explicit array copy code (and it is not clear at first glance that such a justification exists), why have an extraneous ToList() before calling ToArray() in the subsequent code that handles types that are not IList<T>? Is this not committing the same sin we have been arguing against? Making an entire copy of the sequence in memory just to throw it away and allocate yet another copy by copying the List into an array?
Original sequence -> copied into new List -> copied into new Array.
Garbage everywhere!
Things are not always as straightforward as they seem, however. Consider a program that uses the above extension method:
Great, let us remove that dirty, offensive call to ToList and run it again:
// return source.ToList().ToArray();returnsource.ToArray();// Much better! 😎
Running the program again produces the following:
❯ dotnet run
Stack overflow.
Repeat 13771 times:
--------------------------------
at Program.ToArray(System.Collections.Generic.IEnumerable`1<Int32>)
at Program.Main(System.String[])
What?! Oh no! 😱
In our zealous efforts to remove an unnecessary ToList call, we introduced an incurable stack overflow bug!
What is happening here, of course, is that the ToArray that we are calling is not the one from System.Linq. It is actually the same one we just defined! If you look closely you will see that we have defined exactly the same method signature as the method from System.Linq, but because our method is in the same namespace as our class it takes precedence. This results in an infinite recursion and finally a stack overflow. 💀
In fact, it appears that this code exists in Newtonsoft.Json because it is intended to work with .NET Framework 2.0, where the Enumerable class (containing the various LINQ extension methods) did not even exist yet! It turns out that Enumerable.ToArray() does not exist in NETFX 2.0, but an explicit List<T>.ToArray() method, defined on the List<T> type itself, has existed since then. Calling ToList() here makes a ToArray() method available that will achieve the desired result without recursively stack-overflowing.
Lesson learned: even code that seems obviously wrong at first glance may be subject to subtle context that must be understood to make an informed decision about it. This is where a judicious comment explaining ‘why’ the code is the way it is can be invaluable.
Conclusion
In the bad old days of computing, so the story goes, programmers were constrained by small machines, but those days are long gone.
As programmers in the modern world, we are awash in a glut of computer memory. Many of us hardly consider the implications of the code we write. The magic garbage collector takes care of everything and all we have to do is focus on solving the business problems at hand. You actually think saving memory, squeezing space, is a thing? Ok Grandpa, let’s get you to bed.
There was a time when computer memory was at a premium. When stepping back and thinking carefully about things like time / space tradeoffs was a critical part of the creative process of programming. When peeling back the curtain and trying, at least a little bit, to understand the implications of what is happening behind the scenes was a highly-valued skill.
In the hyperbolic title of this post, I called this the tragedy of ToList. The real tragedy, however, is the loss of awareness about these kinds of issues. Of seeing page after page of code, written by well-intentioned programmers, infested with completely unnecessary performance pitfalls due to a basic lack of critical thinking about what happens when you type those simple nine characters: .ToList().
It is an excellent book. The author is a curmudgeon in the best sense of the word, and his goal is to get newer programmers to understand not just the code they write, but how the computers that execute that code actually work. Armed with this knowledge, the individual can inform their act of writing code and create much better programs as a result.
This post is something of a small attempt to achieve the same thing. To encourage stepping back and really thinking about the code we write. Even if it is just a small and simple call to ToList() embedded in a much longer, more complex piece of code.
Nothing is ever that simple.
]]>Making my favorite interview question real2023-02-03T19:00:00+00:002023-02-03T19:00:00+00:00/programming,/interviewing/2023/02/03/InterviewQuestionHere is a variation of my favorite go-to interview question:
I hand you a drive containing two files.
Each file is extremely simple: it consists of 32-bit integers, one after the other. So, the first four bytes is the first integer. The next four bytes is the second integer, and so on. The integers happen to be written in little-endian byte order.
Your task is to produce a third file containing the distinct set of integers that are shared between the two input files. For example, if the value 100 happens to be in the first file but not the second file, it should not be included in the output file. If it happens to exist in both files, then it should be included in the output file.
I need the result file by the end of the day. Other than that, I do not care at all how you produce it. Tell me how, if you were given this problem in the real world, you would actually create the result file.
Now, there are many ways to approach this problem, which is one of the reasons I like this question.
However, there is a twist to this particular problem. If a candidate happens to come up with a nice solution, I give them a variation: what if the files are absolutely enormous? How would that change how you approach solving the problem?
While I have my personal favorite solutions for tackling this, in reality I never actually bothered to produce gigantic files and see how long it would actually take to solve. I knew solutions that should work in theory, but actually trying them was kind of left as an exercise.
Sharing this problem with other programmers, I’ve been asked a few times to actually give them the kind of input files I describe in the problem. They want to tackle it!
Well, ok then, let’s do it.
Update: 10/23/2025
In the original version of this blog post I included links to the actual files hosted in the cloud. Each file was 50GiB in size, for a total of 100GiB of data.
Due, however, to the length of time needed to download such files and the also not-entirely-zero egress cost I was paying, I have removed them.
Instead, I present a small C# program to generate the files locally.
The program takes three parameters: the file to generate, the size of the file in bytes to generate and a seed value.
Pick two seed values at random and use the following to generate your own huge files:
dotnet run a.bin 53687091200 383
dotnet run b.bin 53687091200 980
If you want to take a stab at solving this problem, feel free to try to produce the third file. Remember that duplicates should be removed from the output, as we want the distinct set of shared values.
If you drop me a line telling me your two seeds and the size of the result file, I can tell you if you’re right 🙂.
Have fun!
]]>Fake Optimization2021-12-10T13:00:00+00:002021-12-10T13:00:00+00:00/programming,/performance,/c%23/2021/12/10/FakeOptimizationThe start: an online discussion
I recently participated in an online conversation between a few C# programmers who were discussing the difference between jagged arrays and multidimensional arrays in C#.
The conversation went like this:
Me: Multi-dimensional arrays are contiguous in memory. Also, the sizes are fixed, whereas a jagged array the sizes of each element can be different.
Programmer A: Much faster to loop through an int[,] than int[][].
Me: You have a benchmark for that?
Programmer B: Does it really need one... like looping through something that is contiguous in memory would be faster than looping through something that's scattered all around...right?
Me: I don't doubt it is likely faster, but I'm an empiricist and when people say "much faster" I like to know "how much". But without a benchmark, I can't say.
Programmer A: I don't have a benchmark for it.
The problem
This short discussion reveals a problem that in some ways plagues the software industry. I have seen it many times in discussions with colleagues and other programmers.
So what’s the issue?
Step back and consider what we have here.
First, there is a flatly stated claim that it is “much faster” to use a multidimensional array over a jagged array.
Second, it is considered so obviously true to Programmer B that the idea of benchmarking it seems utterly unnecessary.
Fake optimization is when someone makes a claim, such as “arrays are always faster than linked lists.” (it depends) or “for loops are faster than foreach loops in C#.” (they’re not), without actually knowing what they are talking about.
The insidiousness of fake optimization is that it very often falls under the guise of conventional wisdom, things that “obviously” must be true, so programmers blindly accept it uncritically. I’ve been hearing the “for loops are faster than foreach loops” line for decades; perhaps it was true at one point. Actually measuring it myself, however, showed that this accepted “fact” was completely bogus, at least in the context of looping over arrays in C#.
The broader point is this: we as software developers, if we want to write high quality software that is fast, the kind of software that users actually want to use, must think critically. We must question our assumptions, constantly.
In other words, we need to embrace empiricism.
Empiricism
Empiricism is a philosophy focusing on the idea that knowledge should be based on evidence, not a priori reasoning. It is one of the fundamental building blocks of the scientific method: theories that cannot be tested against real-world observations are inherently unscientific.
This idea should apply to computer programs as well as scientific theories.
In my experience, programmers who apply this philosophy to their work, emphasizing practicial experimentation and measurements over the purely theoretical, tend to build the best software. Such programmers are pragmatic. They are skeptical. They question their own assumptions and the assumptions of others. They keep everyone honest.
I have worked with some brilliant people who are not empiricists. Their approach to software is based more on theory, mathematical reasoning, beauty, perfectionism, ideal design ideas and patterns. These folks, brilliant though they are, do not write the highest quality software.
Perhaps it is better to let the theorists design the algorithms and prove the math, and let us grubby empiricists build the actual product.
I worked on an optimization problem once. The code in question did something like this:
Fetch a few hundred thousand rows from a remote database.
Round any floating point columns to two decimal places.
Apply a filter to the data in memory.
Sort the data in memory.
Return the appropriate page of results.
The overall performance of the above sequence was unacceptably slow: it was taking seconds.
A fellow co-worker assumed the issue had to be in the database query since that was the only part that was doing anything that should have been remotely expensive and was the only part that was doing I/O. Everything else was pure in-memory operations, which should be incredibly fast, even on a few hundred thousands rows of data. They went to work on improving the database code.
Being an empiricist and not liking to make assumptions, I spent some time adding highly granular performance logging instrumentation to measure where all of the time was actually being spent inside the code.
It turns out that 90% of the time was in rounding the floating point values to two decimal places. That was the bottleneck.
(If you think that sounds crazy, we can talk about how terrible DataSet and DataTable are for performance over a beer some time.)
Empiricists go where the evidence leads, and sometimes it leads to surprising places.
Benchmarking
Benchmarking is one of the great tools of the empiricist programmer. In the world of C# and .NET programming, we have the excellent BenchmarkDotNet tool to make it very easy to write high quality benchmarks.
I maintain a collection of microbenchmarks using BenchmarkDotNet at https://github.com/Treit/MiscBenchmarks. These often arise from discussions with other programmers who practice fake optimization: they make a claim about performance, but they do not have the evidence to back it up. As an empiricist, I cannot help but want to see for myself what is actually true.
It is perhaps our greatest tool to defeat fake optimization.
So when Programmer A said that iterating multidimensional arrays is “much faster” than jagged arrays, I naturally wanted to see some evidence. It made sense to me that working with contiguous memory would indeed be faster, as it works better with CPU caches and prefetching and that kind of thing. I was curious how much faster.
The original statement, that using multidimensional arrays would be “much faster”, while intuitively obvious to many programmers, was not just based on no actual evidence.
It was not just wrong.
It was spectacularly wrong.
The results in fact show the opposite: jagged arrays are faster.
That, my friends, is fake optimization.
]]>Untangling AKS, Managed Identity and Key Vault2020-11-29T16:19:00+00:002020-11-29T16:19:00+00:00/c%23,/azure,/kubernetes,/keyvault/2020/11/29/AksManagedIdentity
I collapsed into bed on a recent gloomy November evening feeling mentally exhausted. Hours had been spent reading online help. Perusing blog posts. Watching videos on YouTube. All of that, yet I didn’t seem any closer to solving my problem.
The scenario was at least conceptually simple:
I am writing a program that needs access to data stored in an Azure Key Vault.
I want the code to authenticate to KeyVault using an Azure Managed Identity.
That’s it.
Not complicated.
In fact, this is exactly the kind of scenario Managed Identity is designed for, so one would think that a guide showing exactly how to set this up would be one of the first things that turns up in an online search.
Exasperatingly, that was not my experience. While there is plentiful information out there on configuring Managed Identity for an AKS cluster, nothing I found walked through the complete end-to-end scenario where you start from scratch and end with code in an AKS cluster reading data successfully from Key Vault.
Before finally retiring for the night, I took one last stab at finding an answer: a Twitter search.
I typed into the Twitter search box on my phone: AKS Managed Identity Key Vault
…but when I navigated to their guide, I discovered it has nothing related to configuring Managed Identity! Hopes dashed, I somewhat grumpily replied to their tweet before drifting off to sleep:
Spoiler alert - I did eventually get it working
You can read the Twitter thread, but ultimately the extremely helpful Chad Kittel (@ckittel) came to my rescue and pointed me to a critical step I had been missing.
I had been following something called the Standard Walkthrough on setting up AAD Pod Identity, a critical piece required to get Managed Identity working with an AKS cluster. My mistake was thinking that the instructions in that walkthrough were complete; they were not, and the linked document on Role Assignment, which the walkthrough mentions as a kind of aside, turned out to showcase a critical step. Chad pointed this out and that lead me to a successful solution.
Learning amid overwhelming complexity
Containers, Kubernetes, AKS, Managed Identity. All of this stuff is new to me. A lot of it is rather complex.
How do we tackle learning these systems when they can seem overwhelmingly full of features and settings? Their flexibility and power are amazing, but that comes at a cost of cognitive overload when you are trying to dip your toe into the water and test things out for the first time.
Scott shows a rather hilariously dense poster showing all of the various Azure services and components and, well, overwhelming is a good way to describe it.
This is, incidentally, one of the fundamental tasks of a software developer: managing complexity. What techniques can we employ to keep our sanity?
Scott has some great advice (watch the video!) along the lines of going back to basics and starting simple, building up a deeper understanding from the ground up, piece by piece.
A book that was influential to me when I was first starting my career was The Most Complex Machine. A central theme of that book is complexity and how to deal with it. For someone self-taught who found computers to be unfathomably complicated beasts, it was enlightening to see how the ‘bottoms up’ approach to solving complex problems can be such a critical tool to understanding. The ‘black box’ technique, where we abstract away the internal complexity of an individual component or system by treating it as an opaque box that takes inputs and produces outputs, is extremely useful here. Sometimes we need to crack open the box and see what’s inside, but often we can stay at a level of abstraction where we don’t need to know exactly how it works; we just need to understand how it behaves. Solving complex problems is a matter of starting with simpler pieces and continually going through a process of composition, working upward to build something of greater complexity step-by-step.
The bottom line is that we can avoid being overwhelmed by dividing our overall problem into smaller problems that we can understand and solve individually. The final, more complex working result emerges from composing these solutions together. This is an inherently iterative process: a complete solution does not spring into existence in one fell swoop, but is instead built piece-by-piece, one small solution at a time.
The primer I wished I had found on AKS and Managed Identity
Back to our task: getting code running in AKS to talk successfully to an Azure Key Vault, using Managed Identity.
What follows is going to be the step-by-step walkthrough that I wished I had found when I was trying to get this scenario working.
There are quite a few steps, but we are going to work through them starting from the beginning and build up to a working solution one step at a time.
The need for Managed Identity
First we might ask: why Managed Identity?
A critical scenario for almost all cloud services is that we need a way of dealing with things that are intended to be kept secret. Database passwords. Certificates used for things like TLS. Credentials to talk to 3rd-party services.
Azure provides a great tool to help you keep such secrets hidden and secure: Key Vaults. However, there is an obvious chicken-and-an-egg problem: if you securely store your various secrets in Key Vault, how do you authenticate your service to prove you have permissions to access those secrets? You need…a secret! In order to generate an authentication credential (typically, an access token) you need a password or a private key or something that is itself a secret. Where do you store that?
One common solution to this problem is to have a certificate installed on every virtual machine where your code is going to run, with the private key for that certificate installed as part of a secure, one-time provisioning process for the VM. The certificate can then be set up to be used as a credential for your application that the authentication server will accept in order to grant an access token. Yes, we still have to install the certificate initially on the VM, but it’s a one-time step and after that we can re-use that VM since it will have the necessary credentials to authenticate. If we wave our hands and say that we have a secure way of doing this provisioning, we’ve solved the problem.
Sort of.
The peril of managing secrets
It’s 7:30 AM and I crack an eye open and glance at my phone. My eyes widen.
Eight missed calls from our team in China, who handles operations while our team in the USA sleeps.
Three missed calls from my boss.
A missed call from my skip-level manager.
An instant message conversation where some of our engineers are clearly desparately trying to get ahold of me.
This is not going to be a good morning.
What happened? Our secure credential that our VMs use, which we provisioned a few years ago, just…expired.
One of our services is down, there is a live site incident and because I happened to be the one who provisioned the credential originally, everyone is hoping I can somehow…‘unexpire’ the credential and get things working again. That’s…not how it works.
Certificates and other credentials expiring or being revoked or otherwise becoming invalid is not that uncommon and has to be right up there with somone pushing a bad DNS change with causing cloud service outages.
Managed Identity solves this problem.
What Manged Identity in Azure does is provide a way to associate such an identity with a particular service, yet in a way such that Azure manages the secret (essentially, the password) for that identity. You still have a Service Principal that represents your application, but instead of managing any secrets associated with that principal, Azure does it for you. Managed Identity in essence acts as a wrapper around the Service Principal concept.
In this way, you never need to know the secret for the application and do not have to worry about managing it.
In fact, you never have access to the secret so the possibility of doing something insecure and accidentally leaking it is not even a scenario.
Azure takes care of creating the secret and rotating it periodically. It will never expire underneath you or get revoked or anything else that could suddenly cause your service to no longer be able to prove its identity.
It’s a really great feature…if you can figure out how to set it up.
Setting up Managed Identity in AKS in 30 simple steps
Ok, thirty is kind of a ballpark figure, but there are quite a few steps and they are all individually fairly simple.
We are going to start from scratch. I am going to assume that you have an Azure subscription to use and that it is currently empty.
Prerequisites
We will use the following technologies, so install these in order to follow along:
You will want a code editor as well. I use both Visual Studio 2019 and Visual Studio Code (depending on what I’m doing), but neither are required to go through the rest of this guide.
At this point we have a resource group containing a Key Vault and that Key Vault contains a secret we want out application to be able to access.
The goal is to be able to access that secret when our code is running in Kubernetes, in an AKS cluster, without us having to know any secrets up front.
The next step will be to write our application code. This will be a simple .NET 5 application in C# that can access that resource.
Perform the following steps to create a new background worker service project and add the necessary NuGet package references we will need.
Replace the contents of Program.cs with the following:
Program.cs
namespaceSecretFetcher{usingSystem;usingSystem.Threading.Tasks;usingMicrosoft.Azure.KeyVault;usingMicrosoft.Azure.Services.AppAuthentication;usingMicrosoft.Extensions.Configuration;usingMicrosoft.Extensions.Configuration.AzureKeyVault;usingMicrosoft.Extensions.DependencyInjection;usingMicrosoft.Extensions.Hosting;publicclassProgram{publicstaticvoidMain(string[]args){try{Console.WriteLine($"SecretFetcher started at {DateTime.UtcNow} UTC!");CreateHostBuilder(args).Build().Run();}catch(Exceptione){Console.WriteLine(e);throw;}}publicstaticIHostBuilderCreateHostBuilder(string[]args)=>Host.CreateDefaultBuilder(args).ConfigureServices((hostContext,services)=>{services.AddHostedService<Worker>();}).ConfigureAppConfiguration((context,config)=>{varconfigSettings=config.Build();KeyVaultClientkvc;stringtoken=Environment.GetEnvironmentVariable("ACCESS_TOKEN");if(!string.IsNullOrWhiteSpace(token)){// Local development scenario, use an explicit access token from 'az login' instead of using// managed identity.kvc=newKeyVaultClient(async(string_,string_,string_)=>awaitTask.FromResult(token));}else{// Use managed identity.varazureServiceTokenProvider=newAzureServiceTokenProvider();kvc=newKeyVaultClient(newKeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));}config.AddAzureKeyVault($"https://{configSettings["KeyVaultName"]}.vault.azure.net/",kvc,newDefaultKeyVaultSecretManager());});}}
Note that the code is written to allow either passing an explicit access token in as an environment variable, or relying on managed identity to provide a token automatically via the AzureServiceTokenProvider. The former is to allow running this code in a local docker container, where managed identity is not available since the code is not actually running in Azure.
Replace the contents of Worker.cs with the following:
Worker.cs
namespaceSecretFetcher{usingMicrosoft.Extensions.Configuration;usingMicrosoft.Extensions.Hosting;usingMicrosoft.Extensions.Logging;usingSystem;usingSystem.Threading;usingSystem.Threading.Tasks;publicclassWorker:BackgroundService{privatereadonlyILogger<Worker>_logger;privatereadonlyIConfiguration_configuration;publicWorker(ILogger<Worker>logger,IConfigurationconfiguration){_logger=logger;_configuration=configuration;}protectedoverrideasyncTaskExecuteAsync(CancellationTokenstoppingToken){while(!stoppingToken.IsCancellationRequested){_logger.LogInformation("Worker running at: {time}",DateTimeOffset.Now);varsecret=_configuration["AksDemoSecret"];_logger.LogInformation($"Fetched the following value for 'AksDemoSecret': '{secret}'");awaitTask.Delay(TimeSpan.FromSeconds(10),stoppingToken);((IConfigurationRoot)_configuration).Reload();}}}}
Note that the KeyVault access is abstracted away in the following line:
varsecret=_configuration["AksDemoSecret"];
Here we are just looking for the value to come from configuration; because the KeyVault middleware we hooked up in Program.cs is implemented as a configuration provider, it is transparent and seamless to our code that the value is actually returned from KeyVault.
The underlying configuration is refreshed every 10 seconds, so if the secret changes we should be able to access the new value.
We are going to run this code in a Linux container, so build and publish the project for Linux:
dotnetpublish-rlinux-x64
Add a Dockerfile in the same folder as the csproj:
Dockerfile
FROM mcr.microsoft.com/dotnet/runtime:5.0WORKDIR /appCOPY . .CMD ["./bin/Debug/net5.0/linux-x64/SecretFetcher"]
Build and run the docker image
dockerbuild--tagsecretfetcher:latest.
We are going to first run it locally and verify it works, so get an access token we can pass in as an environment variable (again, since managed identity only works when actually running in Azure.)
This should result in some output like the following:
SecretFetcher started at 11/28/2020 23:50:52 UTC!
info: SecretFetcher.Worker[0]
Worker running at: 11/28/2020 23:50:53 +00:00
info: SecretFetcher.Worker[0]
Fetched the following value for 'AksDemoSecret': 'Sensitive data!'
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
Press ctrl+c to terminate the app running in our local container.
We have successfully set up our Azure resources and written a simple program that retrieves a secret from KeyVault when run in a local docker container. Now we will move on to getting it up and running in Azure.
Add support for managed identity
We were able to run the application in a local docker image and successfully access KeyVault, because we passed in an access token generated for our current user account, which we authenticated as via az login at the start of this demo.
When we actually run in Azure, we will use managed identity instead to acquire an access token based on our containerized service being bound to a specific service principal, using a managed identity.
Note that we extracted three identifiers for this identity: the client id, the resource id and the principal id. All three will be needed later on, so we saved them to environment variables for future use.
For Key Vault we will give explicit permissions to the managed identity principal we created.
Note that both the get and list permissions are needed for our application to successfully retrieve the secret from Key Vault.
At this point we have created the managed identity that we want our application to use to access our Key Vault. We have granted that managed identity get and list permissions on secrets in that vault. Now we will need to find a way to apply that managed identity to our application when it is running in Azure.
Create a container registry
Since our goal is to run a containerized application in Azure, we will create an Azure Container Registry to push our container images to.
Container registry names need to be globally unique, so for the purposes of this demo we are using a little trick and appending five random characters to the registry name to avoid collisions.
Note that we enabled managed identity (--enable-managed-identity) and attached our container registry (--attach-acr) as part of this process.
When you create an AKS cluster, the cluster provisioning process will create an additional resource group that the cluster uses for Azure resources that it directly controls. Since one of the main points of Kubernetes is to abstract aways various resources such as virtual machines and networking infrastructure from your applications, it will need to manipulate a variety of Azure resources to achieve that. Those resources will go in this cluster-specific resource group, which will have a name starting with ‘MC_’, followed by the name of the resource group in which you created the AKS cluster, the name of the cluster and the cluster location.
We can compose the name of that group and verify that it exists after running az aks create.
We have two managed identities in play at this point. The first is the one that we explicitly created. We granted that identity permission to read secrets from our Key Vault. That managed identity represents our application and is managed by us.
The second managed identity is the identity of the AKS cluster itself, which was created because we specified the --enable-managed-identity switch when we ran az aks create. The managed identity of the cluster can be found by inspecting the identityProfile.kubeletidentity.clientId property of the cluster. Let’s extract that identifier, as we will need it shortly.
We will not be granting the cluster itself access to our Key Vault or any other of our Azure resources, but we will be granting it specific permissions that allow it to assign our first managed identity (the one with KeyVault access) to applications running on hardware it (the cluster) controls.
We assign Virtual Machine Contributor on the resource group in which the AKS nodes actually run (the $env:CLUSTER_RESOURCE_GROUP, or the one that starts with MC_…)
We assign Managed Identity Operator on the resource group where the managed identity we want our applications to run as was created.
The above role assignments must be completed before moving on to the next step, installing AAD Pod Identity into our cluster.
Note that the above two steps, assigning these specific roles to the AKS cluster, were the critical piece that I was missing when I tried going through the standard walkthrough on setting up managed identity for an AKS cluster.
At this point the AKS cluster has been granted permissions to apply our managed identity (that can access Key Vault) to applications that run within it, and it has the ability to manage the virtual machines that will be used to run those applications.
AAD Pod Identity
In order to make managed identity work, we need to install AAD Pod Identity. We haven’t used Helm yet, but it makes doing so quite trivial, as you will see below.
Note that we had to set the nmi.allowNetworkPluginKubenet value to true. This is because AKS clusters use Kubenet by default and AAD Pod Identity is disabled on Kubenet until you explicitly enable it with this setting. The reason for this is explained on this page.
This was another step that was not clear from the standard walkthrough and was only discoverable by debugging the logs for the AAD Pod Identity containers after they were running in the cluster.
MIC and NMI components of AAD Pod Identity
AAD Pod Identity installs two services into your AKS cluster: the Managed Identity Controller (MIC) and something called Node Managed Identity (NMI). The MIC is responsible for binding managed identities to virtual machines based on the pods running on those machines. The NMI is responsible for intercepting requests to get an auth token by application code. NMI uses the configured managed identity for the application (which we will set up shortly) as the principal for the access token request.
Binding a managed identity to an application using AAD Pod Identity
We need to deploy an identity and identity binding to the cluster. These Kubernetes resources will be used by the MIC to find pods that need to have the specified identity associated with them.
First we define the identity itself, which maps to the managed identity we created earlier and gave access to our Key Vault:
We next create a binding resource, which uses the selector property to find deployments having a specific label. If a deployment has such a label, it’s essentially saying ‘apply the related managed identity to the VM where my pod is running!’
When we deploy our application, we need to add the special label that the MIC will use to apply the binding we just created. That label is called aadpodidbinding and is added to the labels in the metadata section of the template in our deployment YAML.
The value of the aadpodidbinding must match that of the selector in the binding we created previously. Note that this value does not have to be the name of the managed identity (although that’s as good a value to use as any), it can be any string value. The important part is that they match.
Let’s create the appropriate YAML for our test application, including the critical aadpodidbinding label, and deploy the application into our AKS cluster.
At this point we can check which pods are running. We will see the pods created by AAD Pod Identity for both the MIC and NMI services, as well as our own pod for the SecretFetcher application.
Here is one way to get the status of the pods running in our cluster:
While we can get this information from kubectl easily enough, I highly recommend using the very useful k9s tool. I run this tool in a separate pane in my terminal so that all changes I make to my cluster can be seen immediately. The tool allows drilling in to individual containers to get logs, spawning a remote shell, killing running pods and so on - all in a simple to use, terminal-based interface.
If everything has been configured properly (and if you followed the steps above carefully, it should be), we can now check our logs and see that we are able to successfully access KeyVault using managed identity:
Success! We have started from scratch and properly configured our Azure environment so that we can successfully deploy and run a containerized application in AKS and use Managed Identity to seamlessly connect to our Key Vault.
It might be instructive to see what happens when AAD Pod Identity is not deployed. Let’s stop our existing application:
kubectlscaledeployments/secretfetcher--replicas=0
…and then uninstall AAD Pod Identity and restart our application:
Inspecting the logs for our application should now show that it’s failing miserably.
kubectllogs-l"app=secretfetcher"--tail100SecretFetcherstartedat11/29/202003:23:18UTC!Microsoft.Azure.Services.AppAuthentication.AzureServiceTokenProviderException:Parameters:ConnectionString:[Noconnectionstringspecified],Resource:https://vault.azure.net,Authority:https://login.windows.net/f57bf9a8-a074-4a10-a754-1b05e4f6e8d9.ExceptionMessage:Triedthefollowing3methodstogetanaccesstoken,butnoneofthemworked.Parameters:ConnectionString:[Noconnectionstringspecified],Resource:https://vault.azure.net,Authority:https://login.windows.net/f57bf9a8-a074-4a10-a754-1b05e4f6e8d9.ExceptionMessage:TriedtogettokenusingManagedServiceIdentity.Accesstokencouldnotbeacquired.Receivedanon-retryableerror.MSIResponseCode:BadRequest,Response:{"error":"invalid_request","error_description":"Identity not found"}Parameters:ConnectionString:[Noconnectionstringspecified],Resource:https://vault.azure.net,Authority:https://login.windows.net/f57bf9a8-a074-4a10-a754-1b05e4f6e8d9.ExceptionMessage:TriedtogettokenusingVisualStudio.Accesstokencouldnotbeacquired.EnvironmentvariableLOCALAPPDATAnotset.Parameters:ConnectionString:[Noconnectionstringspecified],Resource:https://vault.azure.net,Authority:https://login.windows.net/f57bf9a8-a074-4a10-a754-1b05e4f6e8d9.ExceptionMessage:TriedtogettokenusingAzureCLI.Accesstokencouldnotbeacquired.
Re-installing AAD Pod Identity should immediately fix the problem. Note that we don’t need to re-deploy the identity and identity binding resources, as those were never removed from the cluster.
If you are running k9s, you should see the application flip from the red ‘failed’ state to successfully running fairly quickly after re-installing AAD Pod Identity.
Cleaning up
We are all done with this walkthrough, so we can clean up all of the resources we created and get back to a clean state in our subscription. This will ensure we don’t pay for resources that we will not be using going forward.
Note that we do not need to explicitly delete the resource group used by the AKS cluster for its own resources; deleting the cluster itself will automatically clean that up.
After deleting our resource group, some resources such as our KeyVault instance may be left in a ‘soft deleted’ state.
These can be cleaned up via:
azkeyvaultpurge--nameenv:KEYVAULT_NAME
Conclusion
Moving one step at a time from a clean starting state, we built up all of the necessary infrastructure and pieces to achieve our end goal.
In the end, getting this end-to-end scenario working was not really all that difficult. We simply needed to understand all of the pieces in play and how they fit together. In particular, we needed to understand the importance of assigning the Virtual Machine Contributor and Managed Identity Operator roles to the identity associated with our AKS cluster before installing AAD Pod Identity. We also needed to create the correct identity binding in the cluster so that the components of AAD Pod Identity can apply the correct managed identity to our application.
I certainly learned quite a bit going through this process. I hope you found it instructive too.
]]>A C# programmer examines Rust - Part 22020-03-15T13:02:00+00:002020-03-15T13:02:00+00:00/rust,/c%23,/programming/2020/03/15/StartingRustPart2
In part one we started an initial exploration of the Rust programming language, using a small programming problem as a starting point. The problem was:
Given a string which contains comma-separated values, transform it into a list of Globally Unique Identifiers (GUIDs) if and only if every value is a valid GUID. Ignore whitespace and newlines.
The following Rust function was given as a candidate solution, which proved to capably solve the problem while retaining execellent runtime performance:
This is not necessarily the most optimal way to solve this problem, but it is succinct and correct and good enough for our initial purposes.
Is it obvious, though, how it works?
Let’s unpack it.
fnextract_ids(input:&str)...
We have a function that takes as input an &str, which is Rust’s way of saying a ‘reference to a string slice.’
References, ownership and borrows
If you have never programmed Rust, it would be very useful to read up on ownership. This is one of the fundamental concepts in Rust and one of the things that makes the language novel and interesting. Coming from a garbage collected language like C#, the strict ownership rules in Rust might seem onerous, and even bizarre. The rewards for following these rules, however, are great: memory safety without performance overhead.
I’m not going to attempt to explain all of the details of Rust’s ownership system in this blog post, but we can summarize the salient points:
Creating a reference to some memory location is known as ‘borrowing’ that memory location.
References (borrows) of a given location are immutable by default.
You can have as many immutable borrows of a location in memory as you like.
You can have exactly one mutable borrow of a memory location at any given time.
You cannot create a mutable borrow while there are existing immutable borrows.
Accessing a memory location without borrowing it implies transferring ownership of that location. This is called ‘moving’ ownership.
There are exceptions for types that can be cheaply copied. This include primitive types such as integers, where accessing the memory location for the type makes a copy of the bits at the original location. C# programmers will be familiar with that as the difference between ‘value types’ and ‘reference types’ in that language.
Ok, this sounds like a lot of rules to have to keep track of. Once you grasp the rules, however, (and if you don’t, believe me the compiler will let you know) it is not too hard to get comfortable with the system. The results are well worth it.
So: using the & symbol to create a reference means taking a borrow of the memory in question. We use &mut to take a mutable borrow.
The Rust compiler keeps track of all of the memory in use by the program, who owns it, and what borrows of that memory exist. When the owner of a piece of memory goes out of scope (i.e., is no longer used elsewhere in the program), the memory that was owned is freed.
This is how Rust achieves memory safety without a garbage collector: the compiler does all of the work!
(This does mean compile times in Rust can be atrocious, but it’s hard to argue that this inconvenience outweighs the somewhat incredible end result.)
Examining the input type
We can see that our function takes as input a &str, which is an immutable reference (borrow) of a string slice. A string slice is simply a pointer to some UTF8 string and a length, similar to the Span and ReadOnlySpan types in C#.
As there is no null reference concept in Rust (more on that in a bit), we avoid needing to write boilerplate code to validate that we were not passed input that can cause us to crash. This helps keep the code succinct while still being correct.
Incidentally, lack of boilerplate is one of those things that drew me to functional programming (F#) originally, and Rust happily continues that experience. C#, on the other hand, is boilerplate city.
Examining the return type
The return type of our function is Option<Vec<&str>>. What’s this?
Well, we are using generic type parameters here so really what we have is: a Vec<T>, where T is an &str, and an Option<T>, where T is…our Vec<&str>.
Generic type parameters here work the same as in C# code. The type parameter is a placeholder that gets replaced by some concrete type at compile time.
Vec<T> in Rust is analogous to List<T> in C#. It’s a list type that grows as needed to accomodate new items being added to it.
Option types are one solution to the billion dollar mistake, the ability to have null references. They are, for me, one of the best ideas from the world of functional programming languages. The Option type provides an explicit way to encapsulate the idea that an operation either produced a value, or it produced nothing. What’s more, programming languages like Rust require your code to account for both possibilites; if you do not, the code will not compile! For seasoned C# programmers this is a concept that takes a bit of getting used to…imagine a world where you never have to check arguments for null, you never have to worry about accessing a null reference, the null coalescing and null conditional operators don’t exist…
An Option is a form of discriminated union, meaning it can contain exactly one of the possible choices for that union. For Option, we either have Some(T) (meaning, we have produced a value of type T) or None. Those are the two possibilities.
Because the None value is not something that is going to convert to a value of type T, the type system in Rust prevents blindly passing in an Option result to something that expects a T.
If you are thinking having to write code to always test every operation for both the Some(T) and None possibilities is going to be tedious, it’s really not! Rust provides some nice syntactic ways to do pattern matching on Option types that make the code straight-forward.
Here is some sample code where we can see Option in action:
fnmake_a_slice(){lets="Hello!";// Create a slice, starting at index one and going up to,// but not including, index three.letopt=s.get(1..3);ifletSome(slice)=opt{println!("{} - {}",s,slice);}// Try to create an invalid slice that is much too large.letopt=s.get(1..1000);matchopt{Some(slice)=>println!("{} - {}",s,slice),None=>println!("Did not produce a slice!"),}}
This illustrates two possible ways (if let and match) of pattern matching on an Option result and extracting the result, if any.
Declarative coding fun with iterators
We have examined the input and return types for our sample string processing function: we will either produce Some(Vec<&str>) for the case where everything passed in was a valid GUID, or we will produce None.
Now let’s look at the actual computation the function is performing:
If you have used LINQ in C# this probably looks somewhat familiar; iterators in Rust are similar to IEnumerable in C#, where LINQ provides a rich set of operations that can be applied to the sequence. Both are lazily evaluated and both support chaining operations together to express the logic used to produce a final result.
A major difference is that with LINQ you typically pay a performance penalty for this terse style of declarative coding, whereas with Rust you do not!
Let’s compare some significant differences between C# and Rust.
We will start by modifying our example code to simply tokenize our input string and just print the first two tokens after trimming any whitespace.
Both pieces of code provide a very natural, ergonomic way to tokenize a delimited string and get the first couple of entries.
There is a reason, however, that every time I see string.Split() called in C# my eyes narrow with suspicion.
Consider our original example scenario from part one of this series where we were loading a lot of text: 10 million GUIDs, along with a bunch of commas and whitespace characters. On disk it’s about 450MB of data. In C# when we call Split(), how many strings did we just allocate? Well, the method returns a string[], that array had to be allocated and filled with the results of splitting, so we just allocated 10 million additional strings. We then allocate an additional ‘trimmed’ string for each item we iterate, since we are calling string.Trim() to remove the whitespace, which allocates yet another string. At least lazy evaluation saves us from allocating 10 million trimmed strings!
A memorable line from a talk I saw some time back was: the garbage collector isn’t your problem, the garbage is your problem!
In reality, C# makes it very, very easy to allocate on the heap like crazy and, while there are ways to avoid this if you are a particularly careful programmer, most developers go with the path of least resistance. There are a lot of string.Split() calls out there in the real world.
You probably saw this next bit coming. How many new strings does the Rust code allocate?
Zero.
Remember that &str is a reference to a string slice, which is just a pointer to the underlying string and a length. With default immutability having our back, is it really necessary to allocate an entirely new string when splitting? What if we just…adjusted where our slice points to? We could point to the first non-comma character and set the length to end just before the next comma. When we trim the string, can’t we just slide the pointer to the first non-whitespace character and set the length to end just before the next whitespace character? In addition, split() being lazy by default (unlike the C# version) means even if we need to stack allocate some slice instances as we are iterating, we don’t need to create millions of them. We are saving hundreds of megabytes of unnecessary memory allocations, yet we wrote essentially the exact same code.
(Caveat: I haven’t looked into how split is actually implemented in Rust, I’m just passing along what I have learned by observing the behavior through some experimentation with a debugger attached.)
Ok, let’s prove that Rust isn’t allocating strings. Recall that our input consists of a bunch of whitespace and GUIDs and commas. Let’s assume our giant 450MB file starts like this:
We read that entire file in as a string and then we do our splitting and trimming and taking.
Let’s look in the debugger what ‘x’ points to on the first iteration.
lettokens=input.split(',').map(|s|s.trim()).take(2);forxintokens{println!("{}",x);// What is the x slice pointing to?}
0:000> dq x
0000000d`c9f1ef28 000001d6`26adf044 00000000`00000024
...
Here we are using the windbg debugger to examine the actual memory of the variable x. We see a 64-bit address (0x000001d626adf044) and a 64-bit length (0x0000000000000024), which is exactly what we would expect for a string slice. Since our GUIDs are 0x24 (36) characters long, the length is correct.
Clearly, it appears to be pointing into our original string, since we can see the expected whitespace and newlines following this. We can look a little bit behind this string and confirm that the original four spaces are there.
Finally, just to absolutely prove the point, we can show that the address we just dumped out (0x000001d626adf040) should be exactly the same as the address our input string slice variable is pointing to.
I find it extremely encouraging to work through these sorts of small examples and realize just how dedicated the developers of the Rust language (and core libraries) care about efficiency. When they say ‘zero cost abstractions’ are a core part of the language design, they aren’t kidding.
As I think I made clear in my previous post, I am kind of blown away that you can write what feels like very high-level code in Rust, yet get efficiency and performance that is right up there with hand-optimized, native code.
The brilliant use of things like slices in conjunction with lazily evaluated iterators, as we just saw, steers you into doing things in an efficient way, without imposing cognitive overhead or requiring the use of subtle tricks to squeeze out performance. ‘It just works’ is kind of a cliché in programming circles, but at least in this case…Rust makes it true.
Next time, we will finally unravel this line of code from our example program:
.map(|s|Uuid::parse_str(s).ok().map(|_|s))
Initially inscrutable to me, working through it will show it all makes sense when we start transitioning from thinking like a C# programmer to thinking like a Rustacean.
It’s a dark, gloomy February night and I can hear the rain pelting against the windows of my office, behind me. It’s late, but I’ve lost track of time. I am puzzling over some code, kind of hacking away at it, trying to gain clarity. On my second monitor there is a Discord channel running, which I’m trying to follow while experimenting on my own with the code. The book on my desk is open to Chapter 13 and I occasionally refer to it. Something about the problem I’m working on is not quite clicking, but I can feel it…I’m getting close to understanding.
I’ve been dabbling with Rust off and on for about a year, but only in the most ephemeral ways; I’d complete a small code sample from “The Book” every once in a while; I’d play around with some trivial toy code to try and understand simple things, like how to retrieve the actual memory address of a variable so I can go poke around at it in the debugger.
I was curious, quite intrigued, really, but not to the point where I was heavily motivated to dive in and put in the work to actually go deeper.
That changed, however, after I attended the first ever conference on Rust at Microsoft. This was an internal event designed to bring Rust enthusiasts from around the company together; between a series of informative presentations and some great workshops, it was a success that lit a fire to re-kindle my latent interest in the language.
This night, therefore, I was embarking on the start of attempting some actual, real-world programming in Rust. The purpose was purely educational; I had decided to port an existing Command Line Interface (CLI) app, written a few years earlier, to Rust. The app in question was also originally written as a learning project, at the time to teach myself some rudimentary F# programming.
Why Rust?
To say Rust is a fascinating language would be an understatement. It represents something novel: a language with the memory-safety guarantees of garbage-collected languages like C#, with the performance and control of systems programming languages like C. It also incorporates expressive, higher-level abstractions borrowed from a variety of other languages, including OCaml, C++, Haskell, Erlang, Scheme, and more.
Around a year ago, I had no idea what Rust was. I’m sure I had seen references to it, as I read a lot of programming forums and blogs, but with no context I remained unaware of it. It’s like when you learn a new word and start hearing it everywhere; it was always there, but your brain just filtered it out.
Then by chance I stumbled across the video Is It Time to Rewrite the Operating System in Rust?, featuring Bryan Cantrill. I’m a sucker for computing history and this video just had everything to engage my attention: an entertaining speaker, history lessons on systems programming, funny anecdotes and, not least, the intriguing promise of this new programming language called Rust.
So, I got interested…and here we are a year late on a stormy night, cozy in our office and wrestling with Rust.
A small programming problem
The F# program I decided to port to Rust can take several types of input. One possible input is a list of Globally Unique Identifiers (GUIDs), separated by commas. Therefore, we have the following small programming problem to solve:
Given a string which contains comma-separated values, transform it into a list of Globally Unique Identifiers (GUIDs) if and only if every value is a valid GUID. Ignore whitespace and newlines.
This is not a sophisticated problem, but it is rather typical of the sort of pragmatic problem we have to solve all of the time. This was the problem I was working on solving in Rust, as a first-step to porting my F# program over.
To test any candidate solution, I created ten million GUIDs and wrote them to disk, separating them with commas and random whitespace, including newlines. Why so many? Because trivial amounts of data are just so…uninteresting. You find useful insights when you push your data into the millions, such as bad algorithmic choices that are way too slow, or stack overflows because you assumed memory is boundless, or other interesting issues that my former professional-software-tester self still loves to find.
We should test the invalid case as well, since we stipulated we must only produce a list if all values are valid GUIDs. To test this, we make a copy of the first file and down near the bottom of the mass of GUIDs, newlines and spaces, we can do something like this:
Perfect, we now have two files: one that should produce a list of ten million GUIDs, the other that should produce some result indicating the input was not a valid, well-formed bowl of GUID soup.
Solving the problem with imperative coding - C#.
Two popular paradigms when solving a programming problem are imperative, where the code details the specific steps the computer should execute in order to arrive at a solution, and declarative, where the code specifies the desired logic without detailing every specific step.
Let’s first look at solving our small programming problem using an imperative style.
A straight-forward implementation in something like C# might look like the following:
Solving the problem with declarative coding - Rust.
While Rust certainly supports the constructs like loops and if-else conditionals that are often used as the primary tools in imperative programming, the examples I have seen of idiomatic Rust code tend towards the more declarative style favored by functional programming languages.
Here is the same solution, written in Rust using a declarative style:
(Thanks to the folks on the Discord channel who helped me find my way to this particular solution.)
Comparison
Which code sample is better? That depends, of course, on your criteria: better in terms of readability? Better in terms of runtime performance? Better in terms of likelihood to have bugs?
I would argue the Rust code is better in all of those criteria, once you have a minimum fluency in functional programming and Rust syntax.
Programmers love to argue about useless trivia, like what it means for a language to be ‘low-level’ or ‘high-level’. Is C# a low-level programming language? Is Rust?
Well, come on, just look at that Rust code. Does that look like a ‘low-level’ language to you???
The amazing promise of Rust, however, is that you can write declarative code that looks decidedly like it came from a high-level language, yet get the runtime performance of languages like C. Indeed, the code above compiles down to very efficient machine code.
We can look, albeit informally, at the performance characteristics of these two pieces of code in a bit. I’d like to point something else out, which is probably far more important than runtime performance. In most applications, code like the above is not really going to need to process ten million GUIDs. It will be processing a few hundred or maybe a few thousand, and the couple of milliseconds of difference in performance is unlikely to matter.
What does matter? Bugs. Correctness. Confidence in the code.
Now, we’re looking at a rather trivial problem and solution, but look closely at both versions of the code and ask yourself: which is more likely to have bugs? Which has mutable state? Which has possible null dereferences?
The Rust code is entirely immune from entire classes of bugs, which is just…awesome. You can’t pass it input that is invalid and will make the code crash (‘panic’, in Rust lingo) because, for instance, there is no ‘null’ in Rust. The Rust function has no mutable state and no possibility of null references. (Everything is immutable by default in Rust, the exact opposite of C#).
In the C# code, it crashes if ‘input’ happens to be null. Oops. There is no such possibility in the Rust version: the input is guaranteed by the compiler to be valid.
There is no possibility of an off-by-one error in the Rust code, for instance because we messed up some loop variable. The C# compiler, on the other hand, won’t catch that for (int i = 0; i <= tokens.Length; i++) is going to crash at runtime, if we had mistakenly written it that way. In fact, in my original version of the code I wrote for (int i = 0; i <= input.Length; i++>) (using the ‘input’ variable instead of ‘tokens’) and it crashed. Oops.
Now expand this trivial, almost silly little example to code that is thousands or tens of thousands or more lines of code. Which style of coding is going to give you more confidence? I know for me, knowing that certain kinds of bugs are completely impossible is a huge win.
(Don’t even get me started on Rust’s amazing concurrency guarantees…)
Solving the problem with declarative coding - C#.
We can take a stab at re-writing our C# code to use a declarative style, which the language supports via Language Integrated Query (LINQ).
By adding some parameter validation and using a declarative style for mapping the input to normalized tokens and validating the result, it’s better. There is less to go wrong, at least.
There’s a problem, however. The less-error-prone declarative C# version is significantly slower to execute, as we shall see shortly. We paid for that additional safety by introducing runtime inefficiency.
In most languages, higher-level abstractions result in a trade-off: higher runtime costs in terms of execution time or memory usage or both.
Rust is one of those rare exceptions where using higher-level abstractions often does not result in any runtime penalty at all.
Quick performance comparison - building and validating a list of ten million GUIDs
A quick-and-dirty performance comparison, just for fun. This is not a scientific, rigorous benchmark, just a quick measurement of the code snippets above.
(Note that I excluded stats for executing against the ‘invalid’ input file because the performance data was essentially the same.)
Performance comparison
Test
Elapsed Milliseconds
Peak Memory Usage
Memory Usage After Processing
Memory Usage After Gen2 GC
C# - Imperative
5444
3.4GB
3.4GB
2.05GB
C# - Declarative
6785
3.2GB
3.2GB
1.9GB
Rust - Declarative
2851
859MB
464MB
N/A
The .NET code, being garbage collected, has to of course wait for the GC to come around and do it’s thing, so I forced a gen2 GC to get an approximately apples-to-apples comparison of the memory usage after all of the processing was done.
In summary
I’m a Rust beginner, so as I start exploring the language I am bound to get some things terribly wrong, make a lot of mistakes and learn a lot in the process. If you see anything egregiously incorrect, please drop me a note so I can address it in a follow-up post.
This post barely scratched the surface of why I think Rust has an amazing future, both for systems programming and for programming higher up the technology stack, like in the cloud services I work on for a living. Is Rust going to imminently replace C# and the amazing open-source .NET ecosystem? Of course not. Does it have a role in solving hard, real-world performance and scale problems that are hard to achieve within a managed (garbage collected) environment? I think that it obviously does.
We took a very small code sample for a trivial coding problem and used that to explore some interesting properties of Rust. First, we saw how the language gives us a declarative way of coding that makes introducing common classes of bugs impossible. Second, we saw how much more efficient the Rust code is at runtime over a garbage-collected language like C#, both in terms of speed and memory usage.
If you didn’t understand the Rust code at all, I don’t blame you. Rust is not easy to grasp if you haven’t seen it before. The learning curve is high, there are many complex features and the code itself tends to be very ‘symbol dense’ and non-obvious. It’s sort of like an anti-Python. What you gain for all of that complexity, however, is performance, correctness and control down to the lowest levels.
I am hoping to try to ‘unpack’ this intriguing little code sample in a future blog post, to go through and explain what’s going on and how it works, as well as to document what else I have learned as I continue poking around in the Rust landscape.
]]>Software tools I love - Part 52020-01-09T10:30:00+00:002020-01-09T10:30:00+00:00/programming,/blogging/2020/01/09/ToolsICantLiveWithoutPart5
.cat1 {
color:#1e3799;
}
This is part 5 in my series where I document my process for going from a brand new computer to one that has the basic set of tools I want present to feel productive.
Installed the Rust toolchain and Cargo so we can build and install projects written in Rust.
Installed ripgrep to allow fast searching for text in files.
Installed fastmod to perform bulk search and replace / refactorings from the terminal.
Installed Starship to get an awesome looking terminal prompt.
Blogging with GitHub Pages
In today’s post we are going to look at what we need to do to set up our new machine for writing blog posts using GitHub Pages.
Installing a Ruby development environment
I’m not a Ruby programmer, however we will need a Ruby development environment to best take advantage of how GitHub supports acting as a blogging platform.
GitHub pages allows you to write blog posts by simply commiting markdown or HTML files to your GitHub repo at username.github.io. GitHub Pages integrates tightly with the static website generating tool Jekyll. The markdown files you author are converted to static HTML by Jekyll, and then published as blog posts by GitHub Pages when the content is commited and pushed to the remote repo.
While it is not necessary to use Jekyll to generate your GitHub Pages blog, it removes a lot of manual work and is therefore the simplest way to get things done with minimal fuss. You still have complete control over customizing the resulting site, so even if you want to hand-code your own static HTML pages and eschew using markdown, you can.
Jekyll is written using the Ruby programming language, so we will need to start by installing the Ruby toolchain to allow us to run a local Jekyll server. This allows previewing what our blog looks like before publishing it.
For a detailed tutorial on setting up a Jekyll blog, please see this page on github.com, which goes into great detail.
For the purpose of this post, we already have an existing blog on github.io, but we need to get the necessary tools installed on the new computer we have been setting up. In other words, this is the cliff-notes version.
This is a standard Windows setup program, so we simple execute it and wait a few minutes for the installation to complete.
Configuring a Ruby terminal environment
Once the install finishes there will be a ‘Start Command Prompt with Ruby’ shortcut on the Start Menu. However, that will launch the Ruby environment running under the old, ugly and not-very-fun conhost.exe. As early adopters of the new and vastly more beautiful and exciting Windows Terminal, we will set up a separate terminal profile to use for blogging.
Step 1: create a wrapper script to execute the Ruby initialization script and change to a specified folder. We do this by saving the following under %userprofile%\tools\rubyprompt.cmd:
As usual, be sure to generate a unique Guid for the new profile.
Now when we want to write blog posts we can simply open the Windows Terminal profile called ‘Blog’ and it will initialize our environment appropriately.
Customzing our terminal color scheme for blogging
We set the ‘colorScheme’ setting to the popular ‘Campbell’ setting that comes with Windows Terminal, but there are endless possibilities for customizing the color scheme to match our own aesthetic tastes. I like my blogging environment to stand out from my other coding environments, so let’s come up with a different scheme.
We could write out own, but luckily there exists a huge assortment of existing, popular terminal color schemes available on github. These can be found at the iTerm2-Color-Schemes repo. Warning: visiting this site could lead to many hours of wasted productivity as you try out scheme after scheme in your terminal!
Let’s say we like the look of the Belafonte Day color scheme and want to try that out for our blogging terminal. We simply download the json and add it to the ‘schemes’ section of our terminal settings file:
The resulting prompt will end up looking something like this:
Installing Jekyll and Bundler
Ok, we have a Ruby environment installed and we have a nice Windows Terminal profile that we will use for blogging, complete with a new color scheme.
Next we will need to install Jekyll and Bundler. Jekyll, as we have mentioned, is the static site generator that will generate the final HTMl for our blog, and Bundler is a popular Ruby package manager that ensures the correct versions of Ruby packages (called ‘gems’) are installed.
From our Blog terminal that we just configued, we simply run:
geminstalljekyllbundler
Once the install completes we need to run bundler to install any missing gems that we need, as specified in the gemfile for our blog. From the root folder of our blog, which we have already cloned from GitHub, we just run:
bundleinstall
Once the install command finishes, we’re done! Now we can start our local blog server and view our local blog content as we work on new posts, by simply running:
bundleexecjekyllserve
Of course the above assumes you already have a working Jekyll blog. If you have never set up a blog using Jekyll, the documentation has some great tutorials to get you started.
Conclusion
We’ve completed another step on setting up a development workstation from scratch, this time installing the tools needed to enjoy authoring blog posts using GitHub Pages. At this point we are pretty close to having all of the core tools and settings configured to feel productive and happy! However, I think I probably have at least another couple of tools I can’t live without that I will share in a final upcoming post or two.
Happy new year!
]]>Software tools I love - Part 42019-12-19T13:00:00+00:002019-12-19T13:00:00+00:00/programming/2019/12/19/ToolsICantLiveWithoutPart4
.cat1 {
color:#1e3799;
}
This is part 4 in my series where I document my process for going from a brand new computer to one that has the basic set of tools I want present to feel productive.
The Rust programming language is fascinating. I’ve heard about it for a few years but really had no idea what it was all about. Then I happened across the highly entertaining video Is It Time to Rewrite the Operating System in Rust? and my curiosity was strongly piqued. A language that provides both memory-safety and native-code levels of performance? With modern language features like exhaustive pattern matching and iterators? This sounds like the kind of programming language I’ve dreamed about.
In fairness I have yet to do any real programming in Rust, but it’s high on my to-do list. As part of researching the language, however, I came across a few extremely neat tools that happened to be written in Rust.
So even if we aren’t going to be doing a lot of Rust coding imminently, installing tools written in Rust gives us a great excuse to get a Rust programming environment bootstrapped onto the new computer we are setting up.
We use a tool called rustup to get Rust installed. On Windows this is done by downloading and executing the rustup-int.exe program. This takes a few minutes to install, but once finished we should be ready to build our own Rust programs.
Creating a Rust terminal profile
I like to have my different programming environments have their own Windows Terminal profile, so let’s create one for when we are doing Rust programming.
I am going to make use of the devprompt_native.cmd wrapper that we created in a previous post to add the necessary paths to the C compilers and other native code development tools we installed. This will give the flexibility to build C/C++ programs as well as Rust programs from the same terminal window, if necessary.
Now we have a profile we can launch from Windows Terminal:
It looks like this when running:
Let’s verify we can build a Rust program! Rust uses a package manager called Cargo, which is installed as part of the Rust toolchain. In general, we use Cargo to build Rust projects, rather than invoking the Rust compiler (rustc) directly.
We can use Cargo to initialize a new project and build it for us, so let’s do that and ensure everything is working properly:
Again, this will take a few minutes to install, after which we can run the same cargo commands in our Bash prompt to verify everything is working as expected.
mtreit@mtreit3:/mnt/c/Users/mtreit$ cd /mnt/c/src/git
mtreit@mtreit3:/mnt/c/src/git$ cargo new hello_rust_wsl
Created binary (application)`hello_rust_wsl` package
mtreit@mtreit3:/mnt/c/src/git$ cd hello_rust
hello_rust/ hello_rust_wsl/
mtreit@mtreit3:/mnt/c/src/git$ cd hello_rust
hello_rust/ hello_rust_wsl/
mtreit@mtreit3:/mnt/c/src/git$ cd hello_rust_wsl/
mtreit@mtreit3:/mnt/c/src/git/hello_rust_wsl$ ls
Cargo.toml src
mtreit@mtreit3:/mnt/c/src/git/hello_rust_wsl$ cargo run
Compiling hello_rust_wsl v0.1.0 (/mnt/c/src/git/hello_rust_wsl)
error: linker `cc` not found
|
= note: No such file or directory (os error 2)
error: aborting due to previous error
error: could not compile `hello_rust_wsl`.
Oh no! It didn’t work.
However, the error message is pretty clear: we are missing some necessary build tools, such as the expected linker.
We installed (in a previous installment of this series) the Microsoft build tools on Windows, but we did not install the Linux equivalents when we set up our WSL environment. Luckily, this is an easy fix. We just need to install the core gcc tools, which we can do as follows:
sudo apt install build-essential
After the install completes, we can try again:
mtreit@mtreit3:/mnt/c/src/git/hello_rust_wsl$ cargo run
Compiling hello_rust_wsl v0.1.0 (/mnt/c/src/git/hello_rust_wsl)
Finished dev [unoptimized + debuginfo] target(s)in 0.60s
Running `target/debug/hello_rust_wsl`
Hello, world!
Great, we now have the Rust toolchain working on both Windows and WSL.
The joy of ripgrep
I don’t know about you, but I spend a lot of time on the command-line searching for text in files on disk, typically source code files. For more than a decade I always used the rudimentary findstr command that comes with Windows. It did the job, but it was not particularly fast and has a very minimal feature set.
Then I discovered ripgrep. This tools often shows up at the top of lists of “what’s your favorite program written in Rust?” when Rust developers are polled. That’s how I discovered it.
It’s extremely fast, has many useful options and has really nice output formatting. I absolutely love it. I probably run rg -i something in my source tree dozens of times a day. This is one of my must-have tools that I can no longer live without!
Building it from source
Let’s download the source for ripgrep and build it ourselves using the tools we have already installed.
By running cargo install we will both compile the program and install it so it will be available to run from any future terminal windows we open. This is done by installing the tool under ~.cargo\bin, which is in the %path% environment variable.
After the build finishes, we can try it out:
Success! We have cloned and built the ripgrep tool from source and installed it so that we can now search files rapidly from any of our terminal session on Windows.
Installing it with Cargo in WSL
Of course we want ripgrep available in our WSL environment as well; while we could once again build it from source, let’s show another way of acquiring programs from the Rust ecosystem using Cargo.
cargo install can be used to build and install programs from crates.io, the Rust package repository. If we don’t want to create our own clone of the source code, this is one of the simplest ways to get the tools we want installed.
From our bash prompt in Ubuntu running on WSL we can simply run:
cargo install ripgrep
Once again, once the build finishes we have ripgrep installed, this time in our WSL environment. If we open a new bash shell we can try it out:
Fastmod
Another useful tool, similar to ripgrep and also written in Rust, is fastmod, from Facebook. I use this tool all the time to do code refactorings from the command line. It has a nice feature that it will preview changes to make sure your regex matched correctly.
No mystery for how to get it installed:
cargo install fastmod
Here is an example of it in action:
Starship
We have one more tool, yet again written in Rust, that we are going to install. This one is used to give us a really nice terminal prompt.
Customizing your terminal prompt is something of an obsessive hobby among command-line aficionados. Just search for ‘bash prompt customization’ on YouTube and you will find an endless stream of videos demonstrating different customizations.
My own current preference is to use a tool called Starship.
Installing Starship on Windows using Cargo
cargoinstallstarship
If you’re impatient there are faster ways to get these tools installed than building them from source with Cargo; Rust, for all of it’s strengths, is not known for fast compilation times. That said, I like building from source because it often finds libraries and packages I may need to install that will be useful when building other projects where I may want to be modifying the source code. It’s also just kind of fun to know you can build from source and go make changes to the programs if you find a need to.
Installing Starship on Ubuntu / WSL using Cargo
If you try to build Starship from source in the WSL environment we have configured on our new machine so far, it will fail, as there are a few missing dependencies that need to be installed first. However, installing them is straight-forward, so the following should be sufficient to get a really nice looking terminal prompt in bash on WSL:
Once installed, we will want to add the following to our PowerShell $profile script:
Invoke-Expression(&starshipinitpowershell)
This will start the Starship prompt when we launch PowerShell.
For Bash, we need to add this to our .bashrc file:
eval"$(~/.cargo/bin/starship init bash)"
Configuring Starship
There are a lot of configuration options for Starship, which are documented here. Customizations go into the file starship.toml under the ~/.config folder.
I disable git status information because the codebase I work in is too large: git status is sufficiently slow that it causes a noticeable delay when the prompt re-draws. If your codebase is small enough, you may want to leave the git_status option enabled.
The end result is a prompt that looks like this:
Conclusion
We’re getting really close to having our new computer running the tools I use every day for my programming work. We’re not finished yet, however. In an upcoming post we will continue our journey and get a few more ‘must-have’ pieces of software installed and configured.
Benchmarking is one of the great tools of the empiricist programmer. In the world of C# and .NET programming, we have the excellent 
