Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+In this chapter we’ll learn the FFI foundations. We’ll learn what FFI is, how we +use it to interoperate between C and Rust, see common pitfalls and more!
+The exercises for this section are located in exercises/01_intro
The exercise for this section is located in 01_intro/00_README
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Programming language design has taken many different paths over the years. We +have C-like languages that are compiled all the way down to machine code, but we +also have interpreted languages, lazy languages, languages that compile to a +portable bytecode, garbage collected languages, and so much more.
+As software engineers we do not want to duplicate work unnecessarily. So what +happens when work exists in a language other than the one you’re using?
+When developing in - for example - Python, we don’t want to port all the code we +need to Python just to use it. Instead, we rely on infrastructure that lets us +call functions and use types from other programming languages.
+This infrastructure, which bridges different type systems (or lack of type +systems), execution models, and code-organization concepts, is called a Foreign +Function Interface (abbreviated FFI from here on out). Most modern languages +have some way to interoperate with others through FFI. The exact syntax and +options vary by language, but they almost always have one thing in common: they +represent functions as if they were C functions.
+This is called the “C ABI” (C Application Binary Interface) or “C Calling +Convention” and as the name suggests is a convention on how to call functions +(which CPU registers hold what arguments, which register(s) hold return values, +when to spill to the stack, etc.)1. Notice that this is just a convention +that the industry agreed on over time. The C ABI is predictable, simple, and has +been stable for decades and therefore became the de-facto standard for language +interoperability.
+Let’s say for example we have a Rust program that needs to call the time
+function from libc (a C static library)2. We would use the following
+construct:
unsafe extern "C" {
+ fn time(time: *mut time_t) -> time_t
+}Before we dissect the syntax though: you may have already noticed that nowhere
+in this snippet do we ask for libc. Why is that?
This is because object file formats (ELF on Linux, Mach-O on macOS, PE on
+Windows) are all quite old and therefore quite simplistic. They have one global
+namespace called a Symbol Table that all functions (and statics) share. So
+you cannot say “call time from libc”, you can only say “call a function
+named time”.
When a compiler builds a program, all function calls reference the function by
+symbol (“call function named X”). To make this actually executable, we need
+to replace every symbol reference with the actual address of the function. This
+happens after compilation during the linking step, where a separate program
+called the Linker will aggregate all object files that make up your final
+program, lay them out on disk and then resolve these symbol names.
To call time from libc we therefore need Rust to emit a reference to the
+time symbol and make sure the libc file is also passed to the linker.
This solves the problem of what to call, but we still need to figure out how +to call that function: How many parameters does the function accept? What are +the types of these parameters? How many return values does it return? Remember +the symbol references above are plain string names. They do not carry any +information about the function’s argument types or return types so Rustc has no +way of figuring out the types itself.
+This is why we need to tell it about time’s signature through a so-called
+“extern block” (or sometimes an “extern C block”) above. This block declares
+items that are not defined in the current crate. Each item we declare is a
+promise to the compiler: “this is the correct signature of this symbol, trust
+me”. We commonly refer to it as a binding.
Get the signature wrong and your Rust program will pass garbage to the FFI
+function without any way to check this at compile-time. The exact implementation
+won’t be known until link-time, much later than the compiler’s type-checking
+pass. This is why bindings are marked unsafe: you as the programmer have to
+ensure signatures are correct.
This is the foundation of all Foreign Function Interfaces in Rust. In later +exercises we will see how to make this much safer and more ergonomic.
+Head to the exercise, where you’ll write this block for a bm_add function
+implemented in C.
The exercise for this section is located in 01_intro/01_what_is_ffi
Technically, there is no “single” calling convention. Every architecture
+defines its own “C Calling Convention”. For example, the RISC-V C Calling
+Convention is defined
+here and
+lays out the sizes of C primitives and how arguments and return values are
+passed from and to functions. x86 architectures have many different
+calling conventions: the Microsoft x64 calling convention and the System V
+ABI are the most common, but many calling conventions exist to e.g. improve
+calling performance (fastcall, regcall, and more). When we say “the C
+calling convention” we usually mean “the C calling convention commonly used
+on this OS+architecture combination”. ↩
Yes, generally speaking libc is distributed not as a static but as a
+dynamic library which is a completely different way of linking and calling
+functions. We’ll cover this in a later chapter in detail. ↩
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+In the previous exercise you wrote an extern "C" block binding to C code. It
+worked great, but can you imagine yourself doing that for hundreds, maybe
+thousands, of functions and types? Of course not! There’s a subtler problem,
+too. Hand-written bindings will inevitably drift out of sync with the C
+header, especially at scale.
Neither the C nor Rust compiler can detect this because each operate in their
+own small universe called a compilation unit. A compilation unit is the single
+chunk of work that flows through the various stages of the compiler. In C/C++
+this would typically be a .c/.cpp file and in Rust that is typically a single
+crate. The compiler will parse, typecheck, optimize the compilation unit and
+produce an intermediate object file. Once all the compilation units that make
+up your project are built, the intermediate object files are gathered and passed
+to the linker, which produces the final executable or library.
┌─────────────────────┐ ┌─────────────────────┐
+│ Rust source │ │ C source │
+└──────────┬──────────┘ └──────────┬──────────┘
+ │ rustc │ cc
+ ▼ ▼
+┌───────────────────────┐ ┌───────────────────────┐
+│ compile │ │ compile │
+│ (parse → typecheck → │ │ (parse → typecheck → │
+│ optimize → codegen) │ │ optimize → codegen) │
+└──────────┬────────────┘ └──────────┬────────────┘
+ │ object file │ object file
+ └───────────────┬────────────────┘
+ ▼
+ ┌─────────────────────┐
+ │ link │
+ │ (ld / lld) │
+ └──────────┬──────────┘
+ ▼
+ ┌─────────────────────┐
+ │ final binary │
+ └─────────────────────┘
+This model is great for compilation performance because we can process many of +these compilation units in parallel! There is a catch, though: compilation +units must not share information since that would destroy our ability to +process them in parallel! Each compilation must be its own self-contained +universe.
+And even if we had a mechanism to share information between compilation units, +we would need to make that language agnostic so that a C compilation unit and a +Rust compilation unit can interoperate. How would that even work with wildly +different type systems? 1
+So compilers have resorted to manual escape hatches like the extern "C"
+block you wrote. You as the programmer promise to the compiler that a function
+with given name and given signature will exist at link-time and the compiler
+takes your word for it.
The consequences of drift between the two versions can be dire: If C expects
+int but Rust expects float the integer bit patterns are being reinterpreted
+as floats. The result is almost always nonsensical.
It can be worse though: passing too many or too few arguments can result in +either overwriting important information on the stack or reading garbage from +the stack!
+Here is an especially insidious case; the function as we have established is the +following:
+int bm_add(int a, int b);
+but now in the Rust code, we expect it to return 64-bit integers instead of +32-bit integers:
+unsafe extern "C" {
+ fn bm_add(a: c_longlong, b: c_longlong) -> c_longlong;
+}How will this example fail? If you try this yourself you will notice: It +doesn’t! The reason is that modern CPUs pass function arguments in registers and +these registers are always word-sized, meaning 64-bit on 64-bit machines. This +means that internally even 32-bit ints are passed as 64-bit integers instead.
+You can see this in Compiler Explorer here:
+The correct version passes a and b in the
+a0 and a1 registers (the li a0, 1 and li a1, 2 lines do the loading) and
+passes the return value in the a0 register. Those registers are 64-bit
+registers though and so you can see the
+incorrect c_longlong-expecting version
+just works because the registers were 64-bit anyway.
Now, if your 64-bit numbers stay below the 32-bit max value, everything just
+happens to work. But it is very fragile. As you can see here,
+when we compile to 32-bit target instead,
+everything breaks and we end up adding 0 to a instead.
I find this example particularly scary, because for 99% of inputs and deployment +configurations this mistake will be virtually consequence-free. The addition +will continue to work as expected. But as soon as the input is unusual, the +deployment target is different, or you add code that will make the compiler +change the generated code even a bit this will be a bug that takes you weeks to +troubleshoot in the worst case.
+Head to the exercise and play with the different “drifted” C implementations of
+bm_add, see what happens on your machine. Feel free to also play around a bit
+with the Compiler Explorer playgrounds to see how different miscompilations
+manifest in the generated assembly.
The exercise for this section is located in 01_intro/02_drift
Yes the LLVM bitcode embedded by toolchains for LTO (Rust’s
+-Clto=thin -Cembed-bitcode=yes and Clang’s -flto=thin) does carry the
+information to catch problems like this at link-time and it is
+cross-language, but linkers do not generally validate it (the wasm-ld
+linker does, but only for Wasm!). The reasons are manifold but most
+importantly because it would break existing compiler optimizations. You
+could write custom LLVM-bitcode parsing tooling to check this if you
+wanted. ↩
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+bindgenIn the previous exercise you saw how easy it is for manual bindings to go out of
+sync, and the scary silent corruption that can cause. In this chapter we’ll
+introduce a tool to avoid all of this called bindgen. It’s a
+library you call in your Rust build script to automatically generate Rust
+bindings to C code based in C header files. It runs libclang on a C header and
+emits matching Rust declarations: extern blocks, #[repr(C)] structs, integer
+constants. The header remains the single source of truth, with the Rust bindings
+being generated on every build.
You call bindgen from your build script like so:
let bindings = bindgen::Builder::default()
+ .header("c_src/bm_legacy.h")
+ // tell Cargo to re-run when headers change
+ .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
+ .generate()
+ .expect("bindgen failed");
+
+let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
+bindings.write_to_file(out_path.join("bindings.rs")).unwrap();This writes the generated file into the crate’s OUT_DIR (usually
+target/<debug or release>/build/<crate name and hash>/out). Inspecting the
+generated file, you will see something like this:
/* automatically generated by rust-bindgen 0.72.1 */
+
+unsafe extern "C" {
+ pub fn bm_add(a: ::std::os::raw::c_int, b: ::std::os::raw::c_int) -> ::std::os::raw::c_int;
+}You can then pull in this generated file into your crate by using the include!
+macro like so:
mod sys {
+ include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
+}This is great, we’ve gained end-to-end type checking. A change in the C header
+will not silently corrupt our Rust code. But remember these bindings are as
+unsafe as the C code itself. It’s your responsibility to use them correctly.
You would typically wrap them in a safe, idiomatic API. This is the common
+-sys crate pattern: a <crate>-sys crate holds the raw bindings, while the
+<crate> crate on top exposes the safe abstractions.
Replace the hand-written extern block from the previous chapter with bindgen
+in build.rs. Safe wrappers and tests stay identical.
cargo expand -p bm_bindgen shows what bindgen produced. Requires
+cargo-expand.
The exercise for this section is located in 01_intro/03_bindgen
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+cheadergenSo far, we’ve always called C from Rust. Now we flip. Remember that our goal is +to migrate C code to Rust. We’ll eventually need C to call into our new Rust +code!
+To make a Rust function callable from C we’ll need to first annotate it +correctly:
+use std::ffi::c_char;
+
+#[unsafe(no_mangle)]
+pub extern "C" fn bm_strlower(s: *mut c_char) {
+ // ...
+}Much like the FFI function declaration we saw in the first exercise, we instruct
+rustc to use a C-compatible calling convention through extern "C" fn (without
+it, Rust uses its own ABI that of course C knows nothing about).
#[unsafe(no_mangle)] keeps the symbol name verbatim in the compiled object.
+Otherwise Rust would emit a so-called mangled symbol name, a pseudo-random
+identifier that in regular Rust code prevents two equally named types or
+functions from causing “duplicate symbol” linking errors.
In this case we do want the symbol name to be the same plain identifier we gave +it, so the C code linking to us can actually find the function.
+The second piece is the header file that allows the C compiler to understand the
+API. You could write it by hand, but you’d be maintaining two sources of truth.
+cheadergen (the inverse of bindgen) generates C
+headers from Rust code.
cheadergen (created and maintained by fellow Mainmatter engineer Luca
+Palmieri) will read your Rust code and automatically generate a C header for the
+relevant FFI-visible symbols.
Install the CLI by following the instructions here +https://github.com/LukeMathWalker/cheadergen/releases.
+Then you can run the following command in your crate root (e.g. the current +exercise crate):
+cheadergen generate
+and a header will appear:
+/* Generated by cheadergen — do not edit */
+
+void bm_strlower(char *s);
+cheadergen comes with two ways to configure its output. The first is a
+project-wide cheadergen.toml file. Here you can tweak the style of the
+generated headers, include custom preamble text, and more. See the full
+documentation here.
The second configuration option is the #[cheadergen::config(...)] attribute.
+You can apply this attribute to any Rust type. It lets you configure per-type
+options such as renaming fields, skipping exporting, forcing exporting, and
+more. See the full documentation here.
cbindgenIf you’ve been researching Rust FFI tooling, you undoubtedly came across
+cbindgen, a very similar tool maintained by Mozilla, and you may
+ask yourself: “Why did you just introduce me to this custom tool instead?”
Well, we wouldn’t have built a new tool if the existing one fit. cbindgen
+dates back to 2017, when the Rust ecosystem looked very different. To read your
+Rust and emit headers, it had to parse the source itself with a custom
+syn-based parser. At the time, that was the only way, since the compiler
+didn’t expose enough information.
But the technique has real limits. The custom parser doesn’t always agree with
+rustc, it often needs manual steering and fixups, and when it hits something it
+can’t handle it tends to silently skip generating a header rather than tell you
+why. None of this is a knock on cbindgen: it’s what the constraints of the era
+allowed. cheadergen exists because those constraints have since eased, letting
+us build something with better diagnostics and fewer surprises.
You’ll port the bm_strlower function to Rust and call
+cheadergen generate --lang c --output-dir c_test -p cheadergen to generate the
+header automatically.
The exercise for this section is located in 01_intro/04_cheadergen
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+extern "C" And FFI-Safe TypesWe have passed data from C to Rust and from Rust to C in the previous exercises.
+In doing so we have mostly constrained ourselves to pointers or c_-prefixed
+primitives. At this point you may wonder though: “What if I want to pass a
+struct? or a String?”
All primitives (i.e. i8..i64, u8..u64, f32, f64, bool, pointers)
+are always safe to share across an FFI interface since these correspond 1:1 with
+C types. Option<NonNull<T>> deserves special mention because it is also FFI
+safe and guaranteed to have the same representation as *mut T.
Note that C’s int type and Rust’s i32, for example, almost always mean the
+same thing. But because the C standard’s definition of these types is quite
+loose there exist architectures for which this is not true. This is rare enough
+that the Rust team decided Rust’s integer types are FFI-safe. If you want to be
+absolutely sure though, you can use the std::ffi::c_* types such as c_int or
+c_longlong.
repr(C)Much like we need to use the C calling convention to make our Rust functions
+interoperable, we need to use the C struct layout to make our structs
+interoperable. This is because (just like functions) Rust reserves the right to
+change the struct layout at any time (it is “undefined”)1. In order to have a
+stable layout that other languages can understand though we need to mark our
+structs using the repr(C) attribute.
// we know the layout of this struct is always:
+// - `a` - 8 bytes
+// - `b` - 1 byte
+// - 1 byte padding
+// - `c` two bytes
+#[repr(C)]
+struct Foo {
+ a: usize,
+ b: u8,
+ c: u16,
+}
+
+// we DO NOT know the layout of this struct!
+struct Bar {
+ a: usize,
+ b: u8,
+ c: u16,
+}repr(C) also applies to tuple structs where the layout is exactly the same
+except the fields don’t have names.
The repr(..) attribute can also be used on enums:
// This corresponds to named u8 constants, where A = 0, B = 1, C = 2
+#[repr(u8)]
+enum Foo {
+ A,
+ B,
+ C,
+}
+
+// You can of course also assign explicit tags
+#[repr(u8)]
+enum Foo {
+ A = 5,
+ B = 2,
+ C = 8,
+}
+
+// repr(C) also works and uses the "default enum size and sign for the target platform's C ABI"
+#[repr(C)]
+enum Foo {
+ A,
+ B,
+ C,
+}You can use enums with fields even though they don’t have an inherent C +equivalent. Rust defines a stable mapping +here.
+// A definition like this...
+#[repr(u8)]
+enum TwoCases {
+ A(u8, u16),
+ B(u16),
+}
+
+//...is in essence just syntax sugar for this:
+union TwoCasesRepr {
+ A: TwoCasesVariantA,
+ B: TwoCasesVariantB,
+}
+
+#[repr(u8)]
+enum TwoCasesTag {
+ A,
+ B,
+}
+
+#[repr(C)]
+struct TwoCasesVariantA(TwoCasesTag, u8, u16);
+
+#[repr(C)]
+struct TwoCasesVariantB(TwoCasesTag, u16);So essentially an enum with fields decomposes to a tag enum and a union of its +fields.
+repr(transparent)repr(transparent) doesn’t appear as often but warrants special mention. It is
+an attribute that can only be used on types with a single sized field. It
+guarantees that the layout of the outer type will be exactly the same as that of
+the inner type.
// Foo is guaranteed to have the same representation as `*const u8`!
+#[repr(transparent)]
+struct Foo(*const u8);
+
+// because this is concerned with _sized_ fields (fields that have a size)
+// fields that have no size such as PhantomData can still be used!
+#[repr(transparent)]
+struct Foo<T>(*const u8, PhantomData<T>);repr(transparent) comes in handy if you need to cast pointers or transmute
+between types.
This list is long, but as a general rule of thumb: Any type with generics or
+more complex Rust structs that are not explicitly FFI-safe (such as String)
+cannot be shared.
Generics are not FFI-safe because the compiler will monomorphize a concrete +version of the struct for each type passed into the generic. If we pass the type +across the FFI boundary the C compiler (which does not know about +monomorphization) would not know which version to pick! There exists no ABI that +represents generics.
+Head to the exercise. There you will find an FFI function that attempts to pass +types that are not FFI-safe. Notice the compiler-generated warnings! It is your +job to fix this by using FFI-safe types.
+The exercise for this section is located in 01_intro/05_ffi_safe_types
The compiler does this to be smart and optimize things. For example,
+here is the code snippet you saw above in
+Compiler Explorer again. If you look at the rightmost “Compiler Output” pane
+you will see the actual layout of each struct. You can see that for Bar
+the compiler smartly reordered the fields to remove the interior padding
+byte! ↩
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+By now you’ve written extern "C" functions in both directions, seen bindgen
+generate Rust code and cheadergen generate C headers.
On paper that is everything you need and it’s tempting to just go ahead and +rewrite your project now. Take your C API and translate it one-for-one into +Rust.
+The problem is: often you can’t — and just as often, you shouldn’t. Real-world C +is complicated, idiosyncratic, and (let’s admit it!) full of skeletons. You’re +likely thinking about a Rust rewrite not just to address security problems or +performance issues; rewriting in Rust is a chance to clean up your codebase: +re-establish module boundaries, drop the legacy assumptions, write the module +you wished you had.
+At the same time big-bang rewrites (where you replace the entire codebase at +once) famously never work. Which leaves a problem: you have a clean Rust +codebase, a messy legacy codebase, and a need to keep both working together for +some time1.
+During this transitionary period the FFI layer is where those worlds meet. It +has to bridge unsafe-everything-goes C and the borrow checker — and bridge +your new design and the old one.
+One major misconception many people have is that FFI is about type
+translation. That is correct, of course, but it’s like saying programming is
+about typing words into a computer; it is missing the point. The main job of
+your FFI interface is establishing confidence. In a legacy codebase you
+rarely know with 100% certainty that reality matches your assumptions: some
+caller might actually pass a nullptr, the *const c_char that used to be UTF-8
+might now hold binary data.
The FFI boundary is your chance to turn legacy uncertainty into known-good state +before it crosses into your new system. Uncertainty leaks. Your FFI must be a +vigilant firewall against it.
+To this end we at Mainmatter have identified a number of rules that we nowadays +live by.
+Validate every assumption at the FFI boundary. Null checks, length checks, UTF-8 +checks. Panic or return an error if anything is even slightly off. In web +servers the HTTP handler function is your primary interface to the “chaos world” +of the internet, think of FFI functions the same way: they are your primary +interface to the legacy-C “chaos world”.
+You should also lean on Rust’s type system so “forgot to check” isn’t even an
+option. For example: at Mainmatter, we encourage contributors to use
+Option<NonNull<T>> instead of *mut T as much as possible, for the simple
+reason that a *mut T can be dereferenced directly (*ptr), which triggers UB
+if the pointer is null. You would have to add a manual if ptr.is_null() {}
+check before every pointer dereference. With Option<NonNull<T>> on the other
+hand, the type system forces you to handle the None case explicitly. Even
+the laziest .unwrap() will result in a loud panic instead of potentially
+silent UB.
// `*mut T` silently accepts null. You'll remember to check. Until you don't.
+pub extern "C" fn bm_do_thing(input: *mut Thing) -> BmResult { /* … */
+}
+
+// `Option<NonNull<T>>` encodes null as `None` — the compiler forces the branch.
+pub extern "C" fn bm_do_thing(input: Option<NonNull<Thing>>) -> BmResult {
+ let Some(input) = input else {
+ return BmResult::ErrInvalid;
+ };
+ // `input: NonNull<Thing>`, statically non-null.
+ /* … */
+}Legacy C code has a habit of packing several meanings into one return type.
+POSIX read() is a good example: -1 means error (check errno), 0 means
+end-of-file, anything positive is the byte count. It is very easy to mess this
+up. Rust gives you better tools — bool for yes/no, an enum for branching
+outcomes, an out-parameter for the count. These types usually translate quite
+well into C headers too, so use them!
#[repr(C)]
+pub enum BmReadStatus { Ok, Eof, IoError }
+
+pub extern "C" fn bm_read(/* … */, out_bytes: Option<NonNull<usize>>) -> BmReadStatus;Head to the exercise. We’ll continue with the porting work by taking a look at
+bm_normalize_url, found here exercises/_bm/src/bookmark.c. It will normalize
+a given URL by lowercasing it and writing the normalized string into the
+provided buffer. The exercise already contains our “first draft” Rust
+translation: a naïve transliteration from C to Rust that has a number of issues.
Let’s apply what we learned above and fix the implementation!
+Hint: check the exercises tests to check the expected behaviour of
+bm_normalize_url
The exercise for this section is located in 01_intro/06_validate_and_narrow
The exact amount of time of course varies with the scale of your codebase, +but let me tell you from hard-won experience: measure this in years. C +codebase migrations have a funny habit of taking much, much longer than you +think. As a rule of thumb: take your worst case estimate, double that and +add a year. Really. ↩
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+We previously introduced two “mechanical” rules: always validating your input +and not overloading primitives. Now we will introduce two more rules that are a +bit more conceptual but have proven themselves very useful.
+But don’t let that fool you, the following rules are just as important as the +previous two, if not more so.
+Some invariants you can check at runtime. Many you can’t — who owns this
+pointer, whether the string is copied or borrowed, whether free has run
+before, what each error variant means. Write them all down.1 Rust’s
+# Safety convention (being just a comment) works with extern "C" functions
+too! cheadergen will emit them as C doc comments in the header files:
/// Normalize a URL into the caller's buffer.
+///
+/// # Ownership
+/// `url` and `out` are borrowed for the call; the caller continues to own both.
+///
+/// # Safety
+/// 1. `url`, if non-null, must be a [valid] pointer to a NUL-terminated UTF-8 byte sequence.
+/// 2. `out`, must be a [valid], non-null pointer to a writable buffer of at least `out_len` bytes.
+///
+/// # Errors
+/// - `BmResult::ErrInvalidUrl` if `url` is null or not valid UTF-8.
+/// - `BmResult::ErrBufferTooSmall` if the result wouldn't fit in `out_len` bytes.
+///
+/// [valid]:
+#[no_mangle]
+pub unsafe extern "C" fn bm_normalize_url(
+ url: Option<NonNull<c_char>>,
+ out: Option<NonNull<c_char>>,
+ out_len: usize,
+) -> BmResult {
+ let Some(out) = out else {
+ //...
+ };
+
+ // Safety: caller ensured `out` points to at least `out_len` bytes (2.)
+ unsafe { slice::from_raw_parts_mut(out.as_ptr(), out_len) };
+}Note how we number safety invariants and force every inline safety comment to +either:
+This way we make sure that all invariants are either upheld by the function +itself or correctly documented as a responsibility of the caller.
+At the moment this is checked by discipline and PR reviews but in the future +this may soon find its way into Rust/Clippy proper.2
+Every exposed function is API surface you’ll maintain forever, an unsafe
+contract to keep correct, and a per-call cost the compiler can’t optimise away.
+Cross-language LTO can inline across, at the cost of a real setup burden. The
+cheapest FFI function is the one you didn’t expose. Expose coarse operations —
+bm_thing_update_with(...) over one setter per field — and treat the boundary
+as a small set of verbs, not a mirror of your internal struct.
Head to the exercise where we will update our exercise 06 solution with the new +rule(s) we have learned.
+The exercise for this section is located in 01_intro/07_high_quality_ffi_apis
You may (jadedly) say that no one ever reads comments and you may actually +be correct. BUT, with the rise of LLMs something does actually “read” +them. We’ve found that LLMs unsurprisingly struggle quite a bit with the +nuanced, unspoken invariants of FFI code. Turning as many of these unspoken +invariants into spoken ones helps you get better mileage out of these tools. ↩
+There are a couple of related proposals, all in the “pre-RFC” stage. The +most interesting one being +https://github.com/safer-rust/safety-tags/blob/main/pre-RFC.md ↩
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+++Note: the following chapters are not yet publicly available!
+we’re working hard on publishing the rest when we can. If you want early +access, reach out!
+
From now on we will be porting a “real” C application: the bm bookmark manager
+CLI. We will learn how to approach real-world codebases, structure our approach,
+and debug our code when it breaks.
The exercises for this section are located in exercises/02_intermediate
The exercise for this section is located in 02_intermediate/00_README
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Welcome to the “C to Rust Migration Book”!
+This course will teach you techniques for migration C codebases to Rust.
You’ll learn how to maintain a safe mixed C-Rust codebase, incrementally migrate
+modules, translate common C idioms to Rust and learn the debugging tools to use
+when things inevitably break.
We assume prior knowledge of Rust and some C.
+You’ll build up your knowledge in small, manageable steps. By the end of the +course, you will have solved many exercises, and should be prepared to migrate +even larger C codebases to Rust.
+This course is based on the “learn by doing” principle.
It has been designed to be interactive and hands-on.
Mainmatter developed this course to
+be delivered in a classroom setting, over 4 days: each attendee advances through
+the lessons at their own pace, with an experienced instructor providing
+guidance, answering questions and diving deeper into the topics as needed.
If you’d like to organize a private session for your company, please
+get in touch.
You can also take the course on your own, but we recommend you find a friend or +a mentor to help you along the way should you get stuck.
+ +You can go through the course material [in the browser]([TODO: insert URL]) or +[download it as a PDF file]([TODO: insert URL]), for offline reading.
+On the left side of the screen, you can see that the course is divided into +sections. To verify your understanding, each section is paired with an exercise +that you need to solve.
+You can find the exercises in the
+companion GitHub repository.
Before starting the course, make sure to clone the repository to your local
+machine:
git clone https://github.com/mainmatter/migrating-c-to-rust
+We also recommend you work on a branch, so you can easily track your progress +and pull in updates from the main repository, if needed:
+cd c-to-rust-migration-book
+git checkout -b my-solutions
+All exercises are located in the exercises folder. Each exercise is structured
+as a Rust package. The package contains the exercise itself, instructions on
+what to do (in src/lib.rs), and a test suite to automatically verify your
+solution.
To work through this course, you’ll need:
+rustup is already
+installed on your system, run rustup update (or another appropriate command
+depending on how you installed Rust on your system) to ensure you’re running
+on the latest stable version.rust-analyzer
+extension.To verify your solutions, we’ve also provided a tool to guide you through the
+course: the wr CLI, short for “workshop runner”. Install wr by following the
+instructions on
+its website.
Once you have wr installed, open a new terminal and navigate to the top-level
+folder of the repository. Run the wr command to start the course:
wr
+wr will verify the solution to the current exercise.
Don’t move on to the next section until you’ve solved the exercise for the
+current one.
++We recommend committing your solutions to Git as you progress through the +course, so you can easily track your progress and “restart” from a known point +if needed.
+
Enjoy the course!
+This course was written by Jonas Kruckenberg,
+Engineering Consultant at
+Mainmatter.
Jonas Kruckenberg is a systems engineer and technologist focused on
+next-generation computing infrastructure. He is the lead author of k23, an
+experimental high-reliability operating system. As a TC39 Invited Expert, he
+helps shape the future of web by bringing non-browser perspectives to JavaScript
+language standardization.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Welcome to the “C to Rust Migration Book”!
+This course will teach you techniques for migration C codebases to Rust.
You’ll learn how to maintain a safe mixed C-Rust codebase, incrementally migrate
+modules, translate common C idioms to Rust and learn the debugging tools to use
+when things inevitably break.
We assume prior knowledge of Rust and some C.
+You’ll build up your knowledge in small, manageable steps. By the end of the +course, you will have solved many exercises, and should be prepared to migrate +even larger C codebases to Rust.
+This course is based on the “learn by doing” principle.
It has been designed to be interactive and hands-on.
Mainmatter developed this course to
+be delivered in a classroom setting, over 4 days: each attendee advances through
+the lessons at their own pace, with an experienced instructor providing
+guidance, answering questions and diving deeper into the topics as needed.
If you’d like to organize a private session for your company, please
+get in touch.
You can also take the course on your own, but we recommend you find a friend or +a mentor to help you along the way should you get stuck.
+ +You can go through the course material [in the browser]([TODO: insert URL]) or +[download it as a PDF file]([TODO: insert URL]), for offline reading.
+On the left side of the screen, you can see that the course is divided into +sections. To verify your understanding, each section is paired with an exercise +that you need to solve.
+You can find the exercises in the
+companion GitHub repository.
Before starting the course, make sure to clone the repository to your local
+machine:
git clone https://github.com/mainmatter/migrating-c-to-rust
+We also recommend you work on a branch, so you can easily track your progress +and pull in updates from the main repository, if needed:
+cd c-to-rust-migration-book
+git checkout -b my-solutions
+All exercises are located in the exercises folder. Each exercise is structured
+as a Rust package. The package contains the exercise itself, instructions on
+what to do (in src/lib.rs), and a test suite to automatically verify your
+solution.
To work through this course, you’ll need:
+rustup is already
+installed on your system, run rustup update (or another appropriate command
+depending on how you installed Rust on your system) to ensure you’re running
+on the latest stable version.rust-analyzer
+extension.To verify your solutions, we’ve also provided a tool to guide you through the
+course: the wr CLI, short for “workshop runner”. Install wr by following the
+instructions on
+its website.
Once you have wr installed, open a new terminal and navigate to the top-level
+folder of the repository. Run the wr command to start the course:
wr
+wr will verify the solution to the current exercise.
Don’t move on to the next section until you’ve solved the exercise for the
+current one.
++We recommend committing your solutions to Git as you progress through the +course, so you can easily track your progress and “restart” from a known point +if needed.
+
Enjoy the course!
+This course was written by Jonas Kruckenberg,
+Engineering Consultant at
+Mainmatter.
Jonas Kruckenberg is a systems engineer and technologist focused on
+next-generation computing infrastructure. He is the lead author of k23, an
+experimental high-reliability operating system. As a TC39 Invited Expert, he
+helps shape the future of web by bringing non-browser perspectives to JavaScript
+language standardization.
In this chapter we’ll learn the FFI foundations. We’ll learn what FFI is, how we +use it to interoperate between C and Rust, see common pitfalls and more!
+The exercises for this section are located in exercises/01_intro
The exercise for this section is located in 01_intro/00_README
Programming language design has taken many different paths over the years. We +have C-like languages that are compiled all the way down to machine code, but we +also have interpreted languages, lazy languages, languages that compile to a +portable bytecode, garbage collected languages, and so much more.
+As software engineers we do not want to duplicate work unnecessarily. So what +happens when work exists in a language other than the one you’re using?
+When developing in - for example - Python, we don’t want to port all the code we +need to Python just to use it. Instead, we rely on infrastructure that lets us +call functions and use types from other programming languages.
+This infrastructure, which bridges different type systems (or lack of type +systems), execution models, and code-organization concepts, is called a Foreign +Function Interface (abbreviated FFI from here on out). Most modern languages +have some way to interoperate with others through FFI. The exact syntax and +options vary by language, but they almost always have one thing in common: they +represent functions as if they were C functions.
+This is called the “C ABI” (C Application Binary Interface) or “C Calling +Convention” and as the name suggests is a convention on how to call functions +(which CPU registers hold what arguments, which register(s) hold return values, +when to spill to the stack, etc.)1. Notice that this is just a convention +that the industry agreed on over time. The C ABI is predictable, simple, and has +been stable for decades and therefore became the de-facto standard for language +interoperability.
+Let’s say for example we have a Rust program that needs to call the time
+function from libc (a C static library)2. We would use the following
+construct:
unsafe extern "C" {
+ fn time(time: *mut time_t) -> time_t
+}Before we dissect the syntax though: you may have already noticed that nowhere
+in this snippet do we ask for libc. Why is that?
This is because object file formats (ELF on Linux, Mach-O on macOS, PE on
+Windows) are all quite old and therefore quite simplistic. They have one global
+namespace called a Symbol Table that all functions (and statics) share. So
+you cannot say “call time from libc”, you can only say “call a function
+named time”.
When a compiler builds a program, all function calls reference the function by
+symbol (“call function named X”). To make this actually executable, we need
+to replace every symbol reference with the actual address of the function. This
+happens after compilation during the linking step, where a separate program
+called the Linker will aggregate all object files that make up your final
+program, lay them out on disk and then resolve these symbol names.
To call time from libc we therefore need Rust to emit a reference to the
+time symbol and make sure the libc file is also passed to the linker.
This solves the problem of what to call, but we still need to figure out how +to call that function: How many parameters does the function accept? What are +the types of these parameters? How many return values does it return? Remember +the symbol references above are plain string names. They do not carry any +information about the function’s argument types or return types so Rustc has no +way of figuring out the types itself.
+This is why we need to tell it about time’s signature through a so-called
+“extern block” (or sometimes an “extern C block”) above. This block declares
+items that are not defined in the current crate. Each item we declare is a
+promise to the compiler: “this is the correct signature of this symbol, trust
+me”. We commonly refer to it as a binding.
Get the signature wrong and your Rust program will pass garbage to the FFI
+function without any way to check this at compile-time. The exact implementation
+won’t be known until link-time, much later than the compiler’s type-checking
+pass. This is why bindings are marked unsafe: you as the programmer have to
+ensure signatures are correct.
This is the foundation of all Foreign Function Interfaces in Rust. In later +exercises we will see how to make this much safer and more ergonomic.
+Head to the exercise, where you’ll write this block for a bm_add function
+implemented in C.
The exercise for this section is located in 01_intro/01_what_is_ffi
Technically, there is no “single” calling convention. Every architecture
+defines its own “C Calling Convention”. For example, the RISC-V C Calling
+Convention is defined
+here and
+lays out the sizes of C primitives and how arguments and return values are
+passed from and to functions. x86 architectures have many different
+calling conventions: the Microsoft x64 calling convention and the System V
+ABI are the most common, but many calling conventions exist to e.g. improve
+calling performance (fastcall, regcall, and more). When we say “the C
+calling convention” we usually mean “the C calling convention commonly used
+on this OS+architecture combination”. ↩
Yes, generally speaking libc is distributed not as a static but as a
+dynamic library which is a completely different way of linking and calling
+functions. We’ll cover this in a later chapter in detail. ↩
In the previous exercise you wrote an extern "C" block binding to C code. It
+worked great, but can you imagine yourself doing that for hundreds, maybe
+thousands, of functions and types? Of course not! There’s a subtler problem,
+too. Hand-written bindings will inevitably drift out of sync with the C
+header, especially at scale.
Neither the C nor Rust compiler can detect this because each operate in their
+own small universe called a compilation unit. A compilation unit is the single
+chunk of work that flows through the various stages of the compiler. In C/C++
+this would typically be a .c/.cpp file and in Rust that is typically a single
+crate. The compiler will parse, typecheck, optimize the compilation unit and
+produce an intermediate object file. Once all the compilation units that make
+up your project are built, the intermediate object files are gathered and passed
+to the linker, which produces the final executable or library.
┌─────────────────────┐ ┌─────────────────────┐
+│ Rust source │ │ C source │
+└──────────┬──────────┘ └──────────┬──────────┘
+ │ rustc │ cc
+ ▼ ▼
+┌───────────────────────┐ ┌───────────────────────┐
+│ compile │ │ compile │
+│ (parse → typecheck → │ │ (parse → typecheck → │
+│ optimize → codegen) │ │ optimize → codegen) │
+└──────────┬────────────┘ └──────────┬────────────┘
+ │ object file │ object file
+ └───────────────┬────────────────┘
+ ▼
+ ┌─────────────────────┐
+ │ link │
+ │ (ld / lld) │
+ └──────────┬──────────┘
+ ▼
+ ┌─────────────────────┐
+ │ final binary │
+ └─────────────────────┘
+This model is great for compilation performance because we can process many of +these compilation units in parallel! There is a catch, though: compilation +units must not share information since that would destroy our ability to +process them in parallel! Each compilation must be its own self-contained +universe.
+And even if we had a mechanism to share information between compilation units, +we would need to make that language agnostic so that a C compilation unit and a +Rust compilation unit can interoperate. How would that even work with wildly +different type systems? 1
+So compilers have resorted to manual escape hatches like the extern "C"
+block you wrote. You as the programmer promise to the compiler that a function
+with given name and given signature will exist at link-time and the compiler
+takes your word for it.
The consequences of drift between the two versions can be dire: If C expects
+int but Rust expects float the integer bit patterns are being reinterpreted
+as floats. The result is almost always nonsensical.
It can be worse though: passing too many or too few arguments can result in +either overwriting important information on the stack or reading garbage from +the stack!
+Here is an especially insidious case; the function as we have established is the +following:
+int bm_add(int a, int b);
+but now in the Rust code, we expect it to return 64-bit integers instead of +32-bit integers:
+unsafe extern "C" {
+ fn bm_add(a: c_longlong, b: c_longlong) -> c_longlong;
+}How will this example fail? If you try this yourself you will notice: It +doesn’t! The reason is that modern CPUs pass function arguments in registers and +these registers are always word-sized, meaning 64-bit on 64-bit machines. This +means that internally even 32-bit ints are passed as 64-bit integers instead.
+You can see this in Compiler Explorer here:
+The correct version passes a and b in the
+a0 and a1 registers (the li a0, 1 and li a1, 2 lines do the loading) and
+passes the return value in the a0 register. Those registers are 64-bit
+registers though and so you can see the
+incorrect c_longlong-expecting version
+just works because the registers were 64-bit anyway.
Now, if your 64-bit numbers stay below the 32-bit max value, everything just
+happens to work. But it is very fragile. As you can see here,
+when we compile to 32-bit target instead,
+everything breaks and we end up adding 0 to a instead.
I find this example particularly scary, because for 99% of inputs and deployment +configurations this mistake will be virtually consequence-free. The addition +will continue to work as expected. But as soon as the input is unusual, the +deployment target is different, or you add code that will make the compiler +change the generated code even a bit this will be a bug that takes you weeks to +troubleshoot in the worst case.
+Head to the exercise and play with the different “drifted” C implementations of
+bm_add, see what happens on your machine. Feel free to also play around a bit
+with the Compiler Explorer playgrounds to see how different miscompilations
+manifest in the generated assembly.
The exercise for this section is located in 01_intro/02_drift
Yes the LLVM bitcode embedded by toolchains for LTO (Rust’s
+-Clto=thin -Cembed-bitcode=yes and Clang’s -flto=thin) does carry the
+information to catch problems like this at link-time and it is
+cross-language, but linkers do not generally validate it (the wasm-ld
+linker does, but only for Wasm!). The reasons are manifold but most
+importantly because it would break existing compiler optimizations. You
+could write custom LLVM-bitcode parsing tooling to check this if you
+wanted. ↩
bindgenIn the previous exercise you saw how easy it is for manual bindings to go out of
+sync, and the scary silent corruption that can cause. In this chapter we’ll
+introduce a tool to avoid all of this called bindgen. It’s a
+library you call in your Rust build script to automatically generate Rust
+bindings to C code based in C header files. It runs libclang on a C header and
+emits matching Rust declarations: extern blocks, #[repr(C)] structs, integer
+constants. The header remains the single source of truth, with the Rust bindings
+being generated on every build.
You call bindgen from your build script like so:
let bindings = bindgen::Builder::default()
+ .header("c_src/bm_legacy.h")
+ // tell Cargo to re-run when headers change
+ .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
+ .generate()
+ .expect("bindgen failed");
+
+let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
+bindings.write_to_file(out_path.join("bindings.rs")).unwrap();This writes the generated file into the crate’s OUT_DIR (usually
+target/<debug or release>/build/<crate name and hash>/out). Inspecting the
+generated file, you will see something like this:
/* automatically generated by rust-bindgen 0.72.1 */
+
+unsafe extern "C" {
+ pub fn bm_add(a: ::std::os::raw::c_int, b: ::std::os::raw::c_int) -> ::std::os::raw::c_int;
+}You can then pull in this generated file into your crate by using the include!
+macro like so:
mod sys {
+ include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
+}This is great, we’ve gained end-to-end type checking. A change in the C header
+will not silently corrupt our Rust code. But remember these bindings are as
+unsafe as the C code itself. It’s your responsibility to use them correctly.
You would typically wrap them in a safe, idiomatic API. This is the common
+-sys crate pattern: a <crate>-sys crate holds the raw bindings, while the
+<crate> crate on top exposes the safe abstractions.
Replace the hand-written extern block from the previous chapter with bindgen
+in build.rs. Safe wrappers and tests stay identical.
cargo expand -p bm_bindgen shows what bindgen produced. Requires
+cargo-expand.
The exercise for this section is located in 01_intro/03_bindgen
cheadergenSo far, we’ve always called C from Rust. Now we flip. Remember that our goal is +to migrate C code to Rust. We’ll eventually need C to call into our new Rust +code!
+To make a Rust function callable from C we’ll need to first annotate it +correctly:
+use std::ffi::c_char;
+
+#[unsafe(no_mangle)]
+pub extern "C" fn bm_strlower(s: *mut c_char) {
+ // ...
+}Much like the FFI function declaration we saw in the first exercise, we instruct
+rustc to use a C-compatible calling convention through extern "C" fn (without
+it, Rust uses its own ABI that of course C knows nothing about).
#[unsafe(no_mangle)] keeps the symbol name verbatim in the compiled object.
+Otherwise Rust would emit a so-called mangled symbol name, a pseudo-random
+identifier that in regular Rust code prevents two equally named types or
+functions from causing “duplicate symbol” linking errors.
In this case we do want the symbol name to be the same plain identifier we gave +it, so the C code linking to us can actually find the function.
+The second piece is the header file that allows the C compiler to understand the
+API. You could write it by hand, but you’d be maintaining two sources of truth.
+cheadergen (the inverse of bindgen) generates C
+headers from Rust code.
cheadergen (created and maintained by fellow Mainmatter engineer Luca
+Palmieri) will read your Rust code and automatically generate a C header for the
+relevant FFI-visible symbols.
Install the CLI by following the instructions here +https://github.com/LukeMathWalker/cheadergen/releases.
+Then you can run the following command in your crate root (e.g. the current +exercise crate):
+cheadergen generate
+and a header will appear:
+/* Generated by cheadergen — do not edit */
+
+void bm_strlower(char *s);
+cheadergen comes with two ways to configure its output. The first is a
+project-wide cheadergen.toml file. Here you can tweak the style of the
+generated headers, include custom preamble text, and more. See the full
+documentation here.
The second configuration option is the #[cheadergen::config(...)] attribute.
+You can apply this attribute to any Rust type. It lets you configure per-type
+options such as renaming fields, skipping exporting, forcing exporting, and
+more. See the full documentation here.
cbindgenIf you’ve been researching Rust FFI tooling, you undoubtedly came across
+cbindgen, a very similar tool maintained by Mozilla, and you may
+ask yourself: “Why did you just introduce me to this custom tool instead?”
Well, we wouldn’t have built a new tool if the existing one fit. cbindgen
+dates back to 2017, when the Rust ecosystem looked very different. To read your
+Rust and emit headers, it had to parse the source itself with a custom
+syn-based parser. At the time, that was the only way, since the compiler
+didn’t expose enough information.
But the technique has real limits. The custom parser doesn’t always agree with
+rustc, it often needs manual steering and fixups, and when it hits something it
+can’t handle it tends to silently skip generating a header rather than tell you
+why. None of this is a knock on cbindgen: it’s what the constraints of the era
+allowed. cheadergen exists because those constraints have since eased, letting
+us build something with better diagnostics and fewer surprises.
You’ll port the bm_strlower function to Rust and call
+cheadergen generate --lang c --output-dir c_test -p cheadergen to generate the
+header automatically.
The exercise for this section is located in 01_intro/04_cheadergen
extern "C" And FFI-Safe TypesWe have passed data from C to Rust and from Rust to C in the previous exercises.
+In doing so we have mostly constrained ourselves to pointers or c_-prefixed
+primitives. At this point you may wonder though: “What if I want to pass a
+struct? or a String?”
All primitives (i.e. i8..i64, u8..u64, f32, f64, bool, pointers)
+are always safe to share across an FFI interface since these correspond 1:1 with
+C types. Option<NonNull<T>> deserves special mention because it is also FFI
+safe and guaranteed to have the same representation as *mut T.
Note that C’s int type and Rust’s i32, for example, almost always mean the
+same thing. But because the C standard’s definition of these types is quite
+loose there exist architectures for which this is not true. This is rare enough
+that the Rust team decided Rust’s integer types are FFI-safe. If you want to be
+absolutely sure though, you can use the std::ffi::c_* types such as c_int or
+c_longlong.
repr(C)Much like we need to use the C calling convention to make our Rust functions
+interoperable, we need to use the C struct layout to make our structs
+interoperable. This is because (just like functions) Rust reserves the right to
+change the struct layout at any time (it is “undefined”)1. In order to have a
+stable layout that other languages can understand though we need to mark our
+structs using the repr(C) attribute.
// we know the layout of this struct is always:
+// - `a` - 8 bytes
+// - `b` - 1 byte
+// - 1 byte padding
+// - `c` two bytes
+#[repr(C)]
+struct Foo {
+ a: usize,
+ b: u8,
+ c: u16,
+}
+
+// we DO NOT know the layout of this struct!
+struct Bar {
+ a: usize,
+ b: u8,
+ c: u16,
+}repr(C) also applies to tuple structs where the layout is exactly the same
+except the fields don’t have names.
The repr(..) attribute can also be used on enums:
// This corresponds to named u8 constants, where A = 0, B = 1, C = 2
+#[repr(u8)]
+enum Foo {
+ A,
+ B,
+ C,
+}
+
+// You can of course also assign explicit tags
+#[repr(u8)]
+enum Foo {
+ A = 5,
+ B = 2,
+ C = 8,
+}
+
+// repr(C) also works and uses the "default enum size and sign for the target platform's C ABI"
+#[repr(C)]
+enum Foo {
+ A,
+ B,
+ C,
+}You can use enums with fields even though they don’t have an inherent C +equivalent. Rust defines a stable mapping +here.
+// A definition like this...
+#[repr(u8)]
+enum TwoCases {
+ A(u8, u16),
+ B(u16),
+}
+
+//...is in essence just syntax sugar for this:
+union TwoCasesRepr {
+ A: TwoCasesVariantA,
+ B: TwoCasesVariantB,
+}
+
+#[repr(u8)]
+enum TwoCasesTag {
+ A,
+ B,
+}
+
+#[repr(C)]
+struct TwoCasesVariantA(TwoCasesTag, u8, u16);
+
+#[repr(C)]
+struct TwoCasesVariantB(TwoCasesTag, u16);So essentially an enum with fields decomposes to a tag enum and a union of its +fields.
+repr(transparent)repr(transparent) doesn’t appear as often but warrants special mention. It is
+an attribute that can only be used on types with a single sized field. It
+guarantees that the layout of the outer type will be exactly the same as that of
+the inner type.
// Foo is guaranteed to have the same representation as `*const u8`!
+#[repr(transparent)]
+struct Foo(*const u8);
+
+// because this is concerned with _sized_ fields (fields that have a size)
+// fields that have no size such as PhantomData can still be used!
+#[repr(transparent)]
+struct Foo<T>(*const u8, PhantomData<T>);repr(transparent) comes in handy if you need to cast pointers or transmute
+between types.
This list is long, but as a general rule of thumb: Any type with generics or
+more complex Rust structs that are not explicitly FFI-safe (such as String)
+cannot be shared.
Generics are not FFI-safe because the compiler will monomorphize a concrete +version of the struct for each type passed into the generic. If we pass the type +across the FFI boundary the C compiler (which does not know about +monomorphization) would not know which version to pick! There exists no ABI that +represents generics.
+Head to the exercise. There you will find an FFI function that attempts to pass +types that are not FFI-safe. Notice the compiler-generated warnings! It is your +job to fix this by using FFI-safe types.
+The exercise for this section is located in 01_intro/05_ffi_safe_types
The compiler does this to be smart and optimize things. For example,
+here is the code snippet you saw above in
+Compiler Explorer again. If you look at the rightmost “Compiler Output” pane
+you will see the actual layout of each struct. You can see that for Bar
+the compiler smartly reordered the fields to remove the interior padding
+byte! ↩
By now you’ve written extern "C" functions in both directions, seen bindgen
+generate Rust code and cheadergen generate C headers.
On paper that is everything you need and it’s tempting to just go ahead and +rewrite your project now. Take your C API and translate it one-for-one into +Rust.
+The problem is: often you can’t — and just as often, you shouldn’t. Real-world C +is complicated, idiosyncratic, and (let’s admit it!) full of skeletons. You’re +likely thinking about a Rust rewrite not just to address security problems or +performance issues; rewriting in Rust is a chance to clean up your codebase: +re-establish module boundaries, drop the legacy assumptions, write the module +you wished you had.
+At the same time big-bang rewrites (where you replace the entire codebase at +once) famously never work. Which leaves a problem: you have a clean Rust +codebase, a messy legacy codebase, and a need to keep both working together for +some time1.
+During this transitionary period the FFI layer is where those worlds meet. It +has to bridge unsafe-everything-goes C and the borrow checker — and bridge +your new design and the old one.
+One major misconception many people have is that FFI is about type
+translation. That is correct, of course, but it’s like saying programming is
+about typing words into a computer; it is missing the point. The main job of
+your FFI interface is establishing confidence. In a legacy codebase you
+rarely know with 100% certainty that reality matches your assumptions: some
+caller might actually pass a nullptr, the *const c_char that used to be UTF-8
+might now hold binary data.
The FFI boundary is your chance to turn legacy uncertainty into known-good state +before it crosses into your new system. Uncertainty leaks. Your FFI must be a +vigilant firewall against it.
+To this end we at Mainmatter have identified a number of rules that we nowadays +live by.
+Validate every assumption at the FFI boundary. Null checks, length checks, UTF-8 +checks. Panic or return an error if anything is even slightly off. In web +servers the HTTP handler function is your primary interface to the “chaos world” +of the internet, think of FFI functions the same way: they are your primary +interface to the legacy-C “chaos world”.
+You should also lean on Rust’s type system so “forgot to check” isn’t even an
+option. For example: at Mainmatter, we encourage contributors to use
+Option<NonNull<T>> instead of *mut T as much as possible, for the simple
+reason that a *mut T can be dereferenced directly (*ptr), which triggers UB
+if the pointer is null. You would have to add a manual if ptr.is_null() {}
+check before every pointer dereference. With Option<NonNull<T>> on the other
+hand, the type system forces you to handle the None case explicitly. Even
+the laziest .unwrap() will result in a loud panic instead of potentially
+silent UB.
// `*mut T` silently accepts null. You'll remember to check. Until you don't.
+pub extern "C" fn bm_do_thing(input: *mut Thing) -> BmResult { /* … */
+}
+
+// `Option<NonNull<T>>` encodes null as `None` — the compiler forces the branch.
+pub extern "C" fn bm_do_thing(input: Option<NonNull<Thing>>) -> BmResult {
+ let Some(input) = input else {
+ return BmResult::ErrInvalid;
+ };
+ // `input: NonNull<Thing>`, statically non-null.
+ /* … */
+}Legacy C code has a habit of packing several meanings into one return type.
+POSIX read() is a good example: -1 means error (check errno), 0 means
+end-of-file, anything positive is the byte count. It is very easy to mess this
+up. Rust gives you better tools — bool for yes/no, an enum for branching
+outcomes, an out-parameter for the count. These types usually translate quite
+well into C headers too, so use them!
#[repr(C)]
+pub enum BmReadStatus { Ok, Eof, IoError }
+
+pub extern "C" fn bm_read(/* … */, out_bytes: Option<NonNull<usize>>) -> BmReadStatus;Head to the exercise. We’ll continue with the porting work by taking a look at
+bm_normalize_url, found here exercises/_bm/src/bookmark.c. It will normalize
+a given URL by lowercasing it and writing the normalized string into the
+provided buffer. The exercise already contains our “first draft” Rust
+translation: a naïve transliteration from C to Rust that has a number of issues.
Let’s apply what we learned above and fix the implementation!
+Hint: check the exercises tests to check the expected behaviour of
+bm_normalize_url
The exercise for this section is located in 01_intro/06_validate_and_narrow
The exact amount of time of course varies with the scale of your codebase, +but let me tell you from hard-won experience: measure this in years. C +codebase migrations have a funny habit of taking much, much longer than you +think. As a rule of thumb: take your worst case estimate, double that and +add a year. Really. ↩
+We previously introduced two “mechanical” rules: always validating your input +and not overloading primitives. Now we will introduce two more rules that are a +bit more conceptual but have proven themselves very useful.
+But don’t let that fool you, the following rules are just as important as the +previous two, if not more so.
+Some invariants you can check at runtime. Many you can’t — who owns this
+pointer, whether the string is copied or borrowed, whether free has run
+before, what each error variant means. Write them all down.1 Rust’s
+# Safety convention (being just a comment) works with extern "C" functions
+too! cheadergen will emit them as C doc comments in the header files:
/// Normalize a URL into the caller's buffer.
+///
+/// # Ownership
+/// `url` and `out` are borrowed for the call; the caller continues to own both.
+///
+/// # Safety
+/// 1. `url`, if non-null, must be a [valid] pointer to a NUL-terminated UTF-8 byte sequence.
+/// 2. `out`, must be a [valid], non-null pointer to a writable buffer of at least `out_len` bytes.
+///
+/// # Errors
+/// - `BmResult::ErrInvalidUrl` if `url` is null or not valid UTF-8.
+/// - `BmResult::ErrBufferTooSmall` if the result wouldn't fit in `out_len` bytes.
+///
+/// [valid]:
+#[no_mangle]
+pub unsafe extern "C" fn bm_normalize_url(
+ url: Option<NonNull<c_char>>,
+ out: Option<NonNull<c_char>>,
+ out_len: usize,
+) -> BmResult {
+ let Some(out) = out else {
+ //...
+ };
+
+ // Safety: caller ensured `out` points to at least `out_len` bytes (2.)
+ unsafe { slice::from_raw_parts_mut(out.as_ptr(), out_len) };
+}Note how we number safety invariants and force every inline safety comment to +either:
+This way we make sure that all invariants are either upheld by the function +itself or correctly documented as a responsibility of the caller.
+At the moment this is checked by discipline and PR reviews but in the future +this may soon find its way into Rust/Clippy proper.2
+Every exposed function is API surface you’ll maintain forever, an unsafe
+contract to keep correct, and a per-call cost the compiler can’t optimise away.
+Cross-language LTO can inline across, at the cost of a real setup burden. The
+cheapest FFI function is the one you didn’t expose. Expose coarse operations —
+bm_thing_update_with(...) over one setter per field — and treat the boundary
+as a small set of verbs, not a mirror of your internal struct.
Head to the exercise where we will update our exercise 06 solution with the new +rule(s) we have learned.
+The exercise for this section is located in 01_intro/07_high_quality_ffi_apis
You may (jadedly) say that no one ever reads comments and you may actually +be correct. BUT, with the rise of LLMs something does actually “read” +them. We’ve found that LLMs unsurprisingly struggle quite a bit with the +nuanced, unspoken invariants of FFI code. Turning as many of these unspoken +invariants into spoken ones helps you get better mileage out of these tools. ↩
+There are a couple of related proposals, all in the “pre-RFC” stage. The +most interesting one being +https://github.com/safer-rust/safety-tags/blob/main/pre-RFC.md ↩
+++Note: the following chapters are not yet publicly available!
+we’re working hard on publishing the rest when we can. If you want early +access, reach out!
+
From now on we will be porting a “real” C application: the bm bookmark manager
+CLI. We will learn how to approach real-world codebases, structure our approach,
+and debug our code when it breaks.
The exercises for this section are located in exercises/02_intermediate
The exercise for this section is located in 02_intermediate/00_README
| documentHeight | ${documentHeight.toFixed(1)} |
| windowHeight | ${windowHeight.toFixed(1)} |
| scrollTop | ${scrollTop.toFixed(1)} |
| pixelsAbove | ${pixelsAbove.toFixed(1)} |
| pixelsBelow | ${pixelsBelow.toFixed(1)} |
| bottomAdd | ${bottomAdd.toFixed(1)} |
| adjustedBottomAdd | ${adjustedBottomAdd.toFixed(1)} |
| scrollingDown | ${scrollingDown} |
| threshold | ${threshold.toFixed(1)} |
.
+ const a = event.target.closest('a');
+ const href = a.getAttribute('href');
+ const targetId = href.substring(1);
+ const targetElement = document.getElementById(targetId);
+ if (targetElement) {
+ threshold = targetElement.getBoundingClientRect().bottom;
+ updateCurrentHeader();
+ }
+ });
+ });
+ }
+
+ // Takes the nodes from the given head and copies them over to the
+ // destination, along with some filtering.
+ function filterHeader(source, dest) {
+ const clone = source.cloneNode(true);
+ clone.querySelectorAll('mark').forEach(mark => {
+ mark.replaceWith(...mark.childNodes);
+ });
+ dest.append(...clone.childNodes);
+ }
+
+ // Scans page for headers and adds them to the sidebar.
+ document.addEventListener('DOMContentLoaded', function() {
+ const activeSection = document.querySelector('#mdbook-sidebar .active');
+ if (activeSection === null) {
+ return;
+ }
+
+ const main = document.getElementsByTagName('main')[0];
+ headers = Array.from(main.querySelectorAll('h2, h3, h4, h5, h6'))
+ .filter(h => h.id !== '' && h.children.length && h.children[0].tagName === 'A');
+
+ if (headers.length === 0) {
+ return;
+ }
+
+ // Build a tree of headers in the sidebar.
+
+ const stack = [];
+
+ const firstLevel = parseInt(headers[0].tagName.charAt(1));
+ for (let i = 1; i < firstLevel; i++) {
+ const ol = document.createElement('ol');
+ ol.classList.add('section');
+ if (stack.length > 0) {
+ stack[stack.length - 1].ol.appendChild(ol);
+ }
+ stack.push({level: i + 1, ol: ol});
+ }
+
+ // The level where it will start folding deeply nested headers.
+ const foldLevel = 3;
+
+ for (let i = 0; i < headers.length; i++) {
+ const header = headers[i];
+ const level = parseInt(header.tagName.charAt(1));
+
+ const currentLevel = stack[stack.length - 1].level;
+ if (level > currentLevel) {
+ // Begin nesting to this level.
+ for (let nextLevel = currentLevel + 1; nextLevel <= level; nextLevel++) {
+ const ol = document.createElement('ol');
+ ol.classList.add('section');
+ const last = stack[stack.length - 1];
+ const lastChild = last.ol.lastChild;
+ // Handle the case where jumping more than one nesting
+ // level, which doesn't have a list item to place this new
+ // list inside of.
+ if (lastChild) {
+ lastChild.appendChild(ol);
+ } else {
+ last.ol.appendChild(ol);
+ }
+ stack.push({level: nextLevel, ol: ol});
+ }
+ } else if (level < currentLevel) {
+ while (stack.length > 1 && stack[stack.length - 1].level > level) {
+ stack.pop();
+ }
+ }
+
+ const li = document.createElement('li');
+ li.classList.add('header-item');
+ li.classList.add('expanded');
+ if (level < foldLevel) {
+ li.classList.add('expanded');
+ }
+ const span = document.createElement('span');
+ span.classList.add('chapter-link-wrapper');
+ const a = document.createElement('a');
+ span.appendChild(a);
+ a.href = '#' + header.id;
+ a.classList.add('header-in-summary');
+ filterHeader(header.children[0], a);
+ a.addEventListener('click', headerThresholdClick);
+ const nextHeader = headers[i + 1];
+ if (nextHeader !== undefined) {
+ const nextLevel = parseInt(nextHeader.tagName.charAt(1));
+ if (nextLevel > level && level >= foldLevel) {
+ const toggle = document.createElement('a');
+ toggle.classList.add('chapter-fold-toggle');
+ toggle.classList.add('header-toggle');
+ toggle.addEventListener('click', () => {
+ li.classList.toggle('expanded');
+ });
+ const toggleDiv = document.createElement('div');
+ toggleDiv.textContent = '❱';
+ toggle.appendChild(toggleDiv);
+ span.appendChild(toggle);
+ headerToggles.push(li);
+ }
+ }
+ li.appendChild(span);
+
+ const currentParent = stack[stack.length - 1];
+ currentParent.ol.appendChild(li);
+ }
+
+ const onThisPage = document.createElement('div');
+ onThisPage.classList.add('on-this-page');
+ onThisPage.append(stack[0].ol);
+ const activeItemSpan = activeSection.parentElement;
+ activeItemSpan.after(onThisPage);
+ });
+
+ document.addEventListener('DOMContentLoaded', reloadCurrentHeader);
+ document.addEventListener('scroll', reloadCurrentHeader, { passive: true });
+})();
+
diff --git a/mdbook/c-to-rust-migration-book/toc.html b/mdbook/c-to-rust-migration-book/toc.html
new file mode 100644
index 0000000000..5080822455
--- /dev/null
+++ b/mdbook/c-to-rust-migration-book/toc.html
@@ -0,0 +1,31 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mdbook/c-to-rust-migration-book/tomorrow-night-4c0ae647.css b/mdbook/c-to-rust-migration-book/tomorrow-night-4c0ae647.css
new file mode 100644
index 0000000000..11752b8a8c
--- /dev/null
+++ b/mdbook/c-to-rust-migration-book/tomorrow-night-4c0ae647.css
@@ -0,0 +1,104 @@
+/* Tomorrow Night Theme */
+/* https://github.com/jmblog/color-themes-for-highlightjs */
+/* Original theme - https://github.com/chriskempson/tomorrow-theme */
+/* https://github.com/jmblog/color-themes-for-highlightjs */
+
+/* Tomorrow Comment */
+.hljs-comment {
+ color: #969896;
+}
+
+/* Tomorrow Red */
+.hljs-variable,
+.hljs-attribute,
+.hljs-attr,
+.hljs-tag,
+.hljs-regexp,
+.ruby .hljs-constant,
+.xml .hljs-tag .hljs-title,
+.xml .hljs-pi,
+.xml .hljs-doctype,
+.html .hljs-doctype,
+.css .hljs-id,
+.css .hljs-class,
+.css .hljs-pseudo {
+ color: #cc6666;
+}
+
+/* Tomorrow Orange */
+.hljs-number,
+.hljs-preprocessor,
+.hljs-pragma,
+.hljs-built_in,
+.hljs-literal,
+.hljs-params,
+.hljs-constant {
+ color: #de935f;
+}
+
+/* Tomorrow Yellow */
+.ruby .hljs-class .hljs-title,
+.css .hljs-rule .hljs-attribute {
+ color: #f0c674;
+}
+
+/* Tomorrow Green */
+.hljs-string,
+.hljs-value,
+.hljs-inheritance,
+.hljs-header,
+.hljs-name,
+.ruby .hljs-symbol,
+.xml .hljs-cdata {
+ color: #b5bd68;
+}
+
+/* Tomorrow Aqua */
+.hljs-title,
+.hljs-section,
+.css .hljs-hexcolor {
+ color: #8abeb7;
+}
+
+/* Tomorrow Blue */
+.hljs-function,
+.python .hljs-decorator,
+.python .hljs-title,
+.ruby .hljs-function .hljs-title,
+.ruby .hljs-title .hljs-keyword,
+.perl .hljs-sub,
+.javascript .hljs-title,
+.coffeescript .hljs-title {
+ color: #81a2be;
+}
+
+/* Tomorrow Purple */
+.hljs-keyword,
+.javascript .hljs-function {
+ color: #b294bb;
+}
+
+.hljs {
+ display: block;
+ overflow-x: auto;
+ background: #1d1f21;
+ color: #c5c8c6;
+}
+
+.coffeescript .javascript,
+.javascript .xml,
+.tex .hljs-formula,
+.xml .javascript,
+.xml .vbscript,
+.xml .css,
+.xml .hljs-cdata {
+ opacity: 0.5;
+}
+
+.hljs-addition {
+ color: #718c00;
+}
+
+.hljs-deletion {
+ color: #c82829;
+}
diff --git a/mdbook/c-to-rust-migration-book/welcome.html b/mdbook/c-to-rust-migration-book/welcome.html
new file mode 100644
index 0000000000..e105efabd0
--- /dev/null
+++ b/mdbook/c-to-rust-migration-book/welcome.html
@@ -0,0 +1,315 @@
+
+
+
+
+
+ Welcome - The C to Rust Migration Book
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keyboard shortcuts
+
+ Press ← or → to navigate between chapters
+ Press S or / to search in the book
+ Press ? to show this help
+ Press Esc to hide this help
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Welcome
+Welcome to the “C to Rust Migration Book”!
+This course will teach you techniques for migration C codebases to Rust.
You’ll learn how to maintain a safe mixed C-Rust codebase, incrementally migrate
+modules, translate common C idioms to Rust and learn the debugging tools to use
+when things inevitably break.
+We assume prior knowledge of Rust and some C.
+You’ll build up your knowledge in small, manageable steps. By the end of the
+course, you will have solved many exercises, and should be prepared to migrate
+even larger C codebases to Rust.
+Methodology
+This course is based on the “learn by doing” principle.
It has been designed to be interactive and hands-on.
+Mainmatter developed this course to
+be delivered in a classroom setting, over 4 days: each attendee advances through
+the lessons at their own pace, with an experienced instructor providing
+guidance, answering questions and diving deeper into the topics as needed.
If you’d like to organize a private session for your company, please
+get in touch.
+You can also take the course on your own, but we recommend you find a friend or
+a mentor to help you along the way should you get stuck.
+
+Formats
+You can go through the course material [in the browser]([TODO: insert URL]) or
+[download it as a PDF file]([TODO: insert URL]), for offline reading.
+Structure
+On the left side of the screen, you can see that the course is divided into
+sections. To verify your understanding, each section is paired with an exercise
+that you need to solve.
+You can find the exercises in the
+companion GitHub repository.
Before starting the course, make sure to clone the repository to your local
+machine:
+git clone https://github.com/mainmatter/migrating-c-to-rust
+
+We also recommend you work on a branch, so you can easily track your progress
+and pull in updates from the main repository, if needed:
+cd c-to-rust-migration-book
+git checkout -b my-solutions
+
+All exercises are located in the exercises folder. Each exercise is structured
+as a Rust package. The package contains the exercise itself, instructions on
+what to do (in src/lib.rs), and a test suite to automatically verify your
+solution.
+Tools
+To work through this course, you’ll need:
+
+- Rust. If
rustup is already
+installed on your system, run rustup update (or another appropriate command
+depending on how you installed Rust on your system) to ensure you’re running
+on the latest stable version.
+- (Optional but recommended) An IDE with Rust autocompletion support. We
+recommend one of the following:
+
+- RustRover;
+- Visual Studio Code with the
+
rust-analyzer
+extension.
+
+
+- A C compiler. The one provided by your Operating System will be good enough.
+
+Workshop runner
+To verify your solutions, we’ve also provided a tool to guide you through the
+course: the wr CLI, short for “workshop runner”. Install wr by following the
+instructions on
+its website.
+Once you have wr installed, open a new terminal and navigate to the top-level
+folder of the repository. Run the wr command to start the course:
+wr
+
+wr will verify the solution to the current exercise.
Don’t move on to the next section until you’ve solved the exercise for the
+current one.
+
+We recommend committing your solutions to Git as you progress through the
+course, so you can easily track your progress and “restart” from a known point
+if needed.
+
+Enjoy the course!
+Author
+This course was written by Jonas Kruckenberg,
+Engineering Consultant at
+Mainmatter.
Jonas Kruckenberg is a systems engineer and technologist focused on
+next-generation computing infrastructure. He is the lead author of k23, an
+experimental high-reliability operating system. As a TC39 Invited Expert, he
+helps shape the future of web by bringing non-browser perspectives to JavaScript
+language standardization.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/assets/css/app.scss b/src/assets/css/app.scss
index c2c25abd3a..d0457d454d 100644
--- a/src/assets/css/app.scss
+++ b/src/assets/css/app.scss
@@ -76,6 +76,7 @@
@use "components/grid-event-card";
@use "components/form-with-image";
@use "components/table-of-contents";
+@use "components/c-to-rust-migration-lp";
@use "animations/text-animation";
diff --git a/src/assets/css/components/_footer.scss b/src/assets/css/components/_footer.scss
index 20b449ed26..efd1e9407f 100644
--- a/src/assets/css/components/_footer.scss
+++ b/src/assets/css/components/_footer.scss
@@ -57,11 +57,29 @@
text-transform: lowercase;
}
+.footer--minimal {
+ min-height: 8rem;
+ padding: 2rem 0;
+ background-color: var(--color-black);
+
+ .footer__container {
+ align-items: center;
+ }
+}
+
+.footer--minimal .footer__socials {
+ margin-top: 1.5rem;
+}
+
@media (min-width: $breakpoint-s) {
.footer {
padding: 4.5rem 0 1.75rem;
}
+ .footer--minimal {
+ min-height: 12rem;
+ }
+
.footer__logo {
margin: 0 0 3.25rem;
}
@@ -118,4 +136,10 @@
margin-top: rem-calc(120);
order: 0;
}
+
+ .footer--minimal .footer__secondary,
+ .footer--minimal .footer__socials {
+ flex: 0 1 auto;
+ margin-top: 0;
+ }
}
diff --git a/src/assets/css/components/_icon-caret.scss b/src/assets/css/components/_icon-caret.scss
index 3a1a51a918..87095a9ddf 100644
--- a/src/assets/css/components/_icon-caret.scss
+++ b/src/assets/css/components/_icon-caret.scss
@@ -5,7 +5,8 @@
width: var(--icon-caret-size);
margin: var(--icon-caret-margin);
transform: var(--icon-caret-transform);
- transition: 0;
+ transform-origin: center;
+ transition: transform var(--icon-caret-duration, 0.16s) ease;
will-change: transform;
path {
diff --git a/src/assets/css/components/_nav.scss b/src/assets/css/components/_nav.scss
index 9713e5b5a9..2bd6d9aee7 100644
--- a/src/assets/css/components/_nav.scss
+++ b/src/assets/css/components/_nav.scss
@@ -106,24 +106,121 @@
}
#nav-overflow {
+ --nav-overflow-offset: 1rem;
+ --nav-overflow-width: 18rem;
+
inset: 6rem auto auto calc(50% + 6rem);
+ width: min(var(--nav-overflow-width), calc(100vw - 2rem));
padding: 2rem;
box-shadow: 0 0 10px 2px rgba(0, 0, 0, 0.25);
font-size: 1.25rem;
+ transition:
+ margin 0.3s ease,
+ width 0.3s ease;
+ user-select: none;
+ -webkit-user-select: none;
.nav__item {
color: var(--color-black);
}
}
+.nav__nested {
+ color: inherit;
+ user-select: none;
+ -webkit-user-select: none;
+}
+
+.nav__nested-summary {
+ --icon-caret-size: 1em;
+
+ display: flex;
+ align-items: center;
+ gap: 0.5rem;
+ font-weight: 700;
+ cursor: pointer;
+ list-style: none;
+ transition: color 0.3s ease;
+ user-select: none;
+ -webkit-user-select: none;
+
+ &::-webkit-details-marker {
+ display: none;
+ }
+
+ &:hover {
+ color: var(--color-purple);
+ text-decoration: underline;
+ text-decoration-thickness: var(--nav-underline-weight);
+ text-underline-offset: var(--nav-underline-offset);
+ text-decoration-color: var(--color-purple);
+ }
+}
+
+.nav__nested[open] .nav__nested-summary {
+ --icon-caret-duration: 0.24s;
+ --icon-caret-transform: rotate(-180deg) translate3d(0, -0.25rem, 0);
+}
+
+.nav__nested-list {
+ display: grid;
+ gap: 0.25rem;
+ margin: 0.5rem 0 0;
+ padding: 0 0 0 1rem;
+ list-style: none;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+ @media (min-width: $breakpoint-m) {
+ #nav-overflow {
+ clip-path: inset(-12px -12px calc(100% + 12px) -12px);
+ transition:
+ margin 0.3s ease,
+ width 0.3s ease,
+ clip-path 0.16s ease;
+ }
+
+ #nav-overflow:popover-open {
+ clip-path: inset(-12px);
+ transition-duration: 0.24s;
+ }
+
+ @starting-style {
+ #nav-overflow:popover-open {
+ clip-path: inset(-12px -12px calc(100% + 12px) -12px);
+ }
+ }
+ }
+
+ body[data-js-enabled="true"] {
+ .nav__nested-list {
+ overflow: hidden;
+ opacity: 1;
+ transform: translateY(0);
+ transition:
+ max-height 0.2s ease,
+ opacity 0.2s ease,
+ transform 0.2s ease;
+ }
+
+ .nav__nested[data-expanding] .nav__nested-list {
+ transition-duration: 0.24s;
+ }
+
+ .nav__nested[data-collapsed] .nav__nested-list {
+ opacity: 0;
+ transform: translateY(-0.25rem);
+ transition-duration: 0.16s;
+ }
+ }
+}
+
@supports (anchor-name: --n) and (position-anchor: --n) and (position-area: none) {
#nav-overflow {
position-anchor: --nav-overflow;
inset: unset;
position-area: block-end span-inline-end;
- margin: 1rem 0 0;
- padding: 2rem;
- box-shadow: 0 0 10px 2px rgba(0, 0, 0, 0.25);
+ margin: var(--nav-overflow-offset) 0 0;
}
}
@@ -165,7 +262,8 @@
}
:has(#nav-overflow:popover-open) .nav__expandable {
- --icon-caret-transform: rotate(180deg) translate3d(0, -0.25rem, 0);
+ --icon-caret-duration: 0.24s;
+ --icon-caret-transform: rotate(-180deg) translate3d(0, -0.25rem, 0);
--icon-caret-color: var(--color-aqua);
color: var(--color-aqua);
text-decoration: underline;
@@ -368,6 +466,12 @@
}
}
+@media (min-width: $breakpoint-m) and (max-width: calc($breakpoint-xl - 1px)) {
+ #nav-overflow {
+ --nav-overflow-width: 16rem;
+ }
+}
+
@media (min-width: $breakpoint-xl) {
.nav__item,
.nav__cta {
diff --git a/src/assets/css/components/c-to-rust-migration-lp.scss b/src/assets/css/components/c-to-rust-migration-lp.scss
new file mode 100644
index 0000000000..126c0123b4
--- /dev/null
+++ b/src/assets/css/components/c-to-rust-migration-lp.scss
@@ -0,0 +1,209 @@
+@use "../base/breakpoints" as *;
+
+.c-to-rust-migration-hero {
+ position: relative;
+ overflow: hidden;
+ background-color: var(--color-black);
+ color: var(--color-white);
+ min-height: 10vh;
+
+ .color-hero__text {
+ font-size: 1.4rem;
+ margin-top: 0rem;
+ }
+}
+
+.c-to-rust-migration-hero {
+ .table-of-contents__list {
+ @media (min-width: $breakpoint-m) {
+ flex-direction: row;
+ justify-content: flex-start;
+ flex-wrap: wrap;
+ gap: 1.5rem 2.5rem;
+ .btn-secondary {
+ font-size: 1.36rem;
+ .icon-arrow {
+ --icon-arrow-size: 1.4rem;
+ --icon-arrow-margin: 0 0 0 0.6rem;
+ }
+ }
+ }
+ }
+}
+
+.c-to-rust-migration-logo {
+ position: absolute;
+ z-index: 1;
+ top: 1.5rem;
+ left: 5vw;
+ color: var(--color-white);
+}
+
+.c-to-rust-migration-hero__image-wrapper {
+ position: absolute;
+ top: 0;
+ left: 0;
+ width: 100%;
+ height: 100%;
+}
+
+.c-to-rust-migration-hero__image {
+ position: absolute;
+ top: 50%;
+ right: 0;
+ width: 35%;
+ max-width: 30rem;
+ min-width: 25rem;
+ padding: 1rem;
+ margin-right: 5rem;
+ transform: translateY(-50%);
+
+ @media (max-width: $breakpoint-s) {
+ padding: 0;
+ margin-right: 0;
+ margin-top: 2rem;
+ min-width: 12rem;
+ top: 0.8rem;
+ right: 1rem;
+ transform: none;
+ }
+}
+
+.c-to-rust-migration-hero__container {
+ position: relative;
+ z-index: 1;
+ padding: 30vh 0 15vh;
+}
+
+.c-to-rust-migration-hero__text {
+ font-size: 1.5rem;
+ font-weight: normal;
+}
+
+.c-to-rust-migration {
+ .cta-banner__title {
+ font-size: clamp(2rem, 0rem + 4.1667vw, 3rem);
+ }
+}
+
+.c-to-rust-migration-feature {
+ display: grid;
+ overflow: hidden;
+ background-color: var(--color-purple);
+ color: var(--color-white);
+}
+
+.c-to-rust-migration-feature__content,
+.c-to-rust-migration-eurorust__content {
+ padding: 4rem 6rem;
+}
+
+.c-to-rust-migration-feature__content {
+ display: flex;
+ flex-direction: column;
+ align-items: start;
+ justify-content: center;
+ background-image: url("/assets/images/rust/c-to-rust-migration-book/c-to-rust-books_bg.webp");
+ background-position: right bottom;
+ background-repeat: no-repeat;
+ background-size: auto 100%;
+}
+
+.c-to-rust-migration-feature__eyebrow {
+ font-size: 1rem;
+}
+
+.c-to-rust-migration-feature__image {
+ display: none;
+ min-height: 0;
+ overflow: hidden;
+
+ picture,
+ img {
+ display: block;
+ width: 100%;
+ height: 100%;
+ }
+
+ img {
+ object-fit: cover;
+ object-position: center;
+ }
+}
+
+.c-to-rust-migration .workshop-authors__image-wrapper {
+ width: 8rem;
+}
+
+.c-to-rust-migration .mainmatter-section .btn-secondary {
+ .btn-secondary__text {
+ order: 1;
+ }
+
+ .icon-arrow {
+ order: 2;
+ --icon-arrow-margin: 0 0 0 1.5rem;
+ }
+}
+
+.c-to-rust-migration-eurorust__image {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ padding: 3rem;
+ background-image: url("/assets/images/rust/eurorust-2026-bg.jpg");
+ background-position: center;
+ background-repeat: no-repeat;
+ background-size: cover;
+
+ picture {
+ width: auto;
+ height: auto;
+ max-width: 100%;
+ }
+
+ img {
+ width: auto;
+ height: auto;
+ object-fit: contain;
+ }
+}
+
+.mainmatter-section {
+ background-color: var(--color-white);
+ padding: 4rem 6rem;
+}
+
+.c-to-rust-migration-eurorust {
+ display: grid;
+ overflow: hidden;
+ color: var(--color-white);
+}
+
+.c-to-rust-migration-eurorust__content {
+ display: flex;
+ flex-direction: column;
+ background-color: var(--color-purple);
+ align-items: flex-start;
+ align-self: center;
+ width: 100%;
+}
+
+@media (min-width: $breakpoint-m) {
+ .c-to-rust-migration-feature,
+ .c-to-rust-migration-eurorust {
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ }
+
+ .c-to-rust-migration-feature {
+ height: 24rem;
+ }
+
+ .c-to-rust-migration-feature__image {
+ display: block;
+ }
+
+ .c-to-rust-migration-feature__content {
+ background-image: none;
+ }
+}
diff --git a/src/assets/js/nav.js b/src/assets/js/nav.js
index 7b79928d17..fbfa73c377 100644
--- a/src/assets/js/nav.js
+++ b/src/assets/js/nav.js
@@ -13,6 +13,111 @@ const handleScroll = () => {
}
};
+const navOverflow = document.getElementById("nav-overflow");
+const nestedMenuMotionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+
+const setNestedMenuHeight = nestedMenu => {
+ const nestedList = nestedMenu.querySelector(".nav__nested-list");
+ if (!nestedList) return null;
+
+ nestedList.style.maxHeight = `${nestedList.scrollHeight}px`;
+
+ return nestedList;
+};
+
+const clearNestedMenuAnimation = nestedMenu => {
+ delete nestedMenu.dataset.animating;
+ delete nestedMenu.dataset.expanding;
+};
+
+const onNestedHeightTransitionEnd = (nestedList, callback) => {
+ const handleTransitionEnd = event => {
+ if (event.propertyName !== "max-height") return;
+
+ nestedList.removeEventListener("transitionend", handleTransitionEnd);
+ callback();
+ };
+
+ nestedList.addEventListener("transitionend", handleTransitionEnd);
+};
+
+const openNestedMenu = nestedMenu => {
+ nestedMenu.dataset.animating = "true";
+ nestedMenu.dataset.expanding = "true";
+ nestedMenu.dataset.collapsed = "";
+ nestedMenu.open = true;
+
+ window.requestAnimationFrame(() => {
+ const nestedList = nestedMenu.querySelector(".nav__nested-list");
+ if (!nestedList) return;
+
+ nestedList.style.maxHeight = "0px";
+ nestedList.getBoundingClientRect();
+ delete nestedMenu.dataset.collapsed;
+ nestedList.style.maxHeight = `${nestedList.scrollHeight}px`;
+
+ onNestedHeightTransitionEnd(nestedList, () => {
+ nestedList.style.removeProperty("max-height");
+ clearNestedMenuAnimation(nestedMenu);
+ });
+ });
+};
+
+const closeNestedMenu = nestedMenu => {
+ const nestedList = setNestedMenuHeight(nestedMenu);
+ if (!nestedList) return;
+
+ nestedMenu.dataset.animating = "true";
+ delete nestedMenu.dataset.expanding;
+
+ nestedList.getBoundingClientRect();
+ nestedMenu.dataset.collapsed = "";
+ nestedList.style.maxHeight = "0px";
+
+ onNestedHeightTransitionEnd(nestedList, () => {
+ nestedMenu.open = false;
+ delete nestedMenu.dataset.collapsed;
+ nestedList.style.removeProperty("max-height");
+ clearNestedMenuAnimation(nestedMenu);
+ });
+};
+
+const resetNestedMenu = nestedMenu => {
+ const nestedList = nestedMenu.querySelector(".nav__nested-list");
+
+ nestedMenu.open = false;
+ delete nestedMenu.dataset.collapsed;
+ clearNestedMenuAnimation(nestedMenu);
+ nestedList?.style.removeProperty("max-height");
+};
+
+const animateNestedMenu = nestedMenu => {
+ if (!nestedMenu || nestedMenu.dataset.animating === "true") return;
+
+ if (nestedMenu.open) {
+ closeNestedMenu(nestedMenu);
+ } else {
+ openNestedMenu(nestedMenu);
+ }
+};
+
+document.querySelectorAll(".nav__nested-summary").forEach(summary => {
+ summary.addEventListener("click", event => {
+ if (nestedMenuMotionQuery.matches) return;
+
+ event.preventDefault();
+ animateNestedMenu(summary.closest(".nav__nested"));
+ });
+});
+
+navOverflow?.addEventListener("toggle", ({ newState }) => {
+ if (newState !== "closed") return;
+
+ navOverflow.querySelectorAll(".nav__nested[open]").forEach(nestedMenu => {
+ resetNestedMenu(nestedMenu);
+ });
+});
+
// Run once immediately to handle reloads mid-page
handleScroll();
diff --git a/src/c-to-rust-migration-lp.njk b/src/c-to-rust-migration-lp.njk
new file mode 100644
index 0000000000..59d17a0d31
--- /dev/null
+++ b/src/c-to-rust-migration-lp.njk
@@ -0,0 +1,185 @@
+---
+layout: base
+title: "The C to Rust Migration Book"
+description: "Learn how to migrate production C codebases to safe, idiomatic Rust one module at a time."
+permalink: /c-to-rust-migration-book/
+hideNav: true
+minimalFooter: true
+og:
+ image: /assets/images/rust/c-to-rust-migration-book/og-image.jpg
+---
+
+{% from "btn-primary.njk" import btnPrimary %}
+{% from "btn-secondary.njk" import btnSecondary %}
+{% from "strategy-list.njk" import strategyList %}
+{% from "author-socials.njk" import authorSocials %}
+{% from "color-hero.njk" import colorHero %}
+
+{%
+ set toc = {
+ 'Overview': '#overview',
+ 'The Course': '#course',
+ 'Table of contents': '#toc',
+ 'About the Author': '#author',
+ 'About Mainmatter': '#mainmatter'
+ }
+%}
+
+
+ {% include 'svg/logo.njk' %}
+ Mainmatter
+
+
+{%
+ set 'heroContent' = {
+ "title": "The C to Rust Migration Book",
+ "image": "/assets/images/hero/c-to-rust-lp.jpg",
+ "text": "By Mainmatter",
+ "alt": "A close up view of a machine with gears",
+ "loading": "eager",
+ "class": "c-to-rust-migration-hero",
+ "toc": toc
+ }
+%}
+{{ colorHero('purple', heroContent) }}
+
+
+
+ Migrate from C to Rust without breaking the world
+
+ Securing and modernizing software is a top priority today. Tech debt and memory-safety bugs
+ remain the largest sources of vulnerabilities, which is why teams increasingly turn to Rust
+ for its reliability and memory safety. But rewrites are hard, scary, and carry a lot of risk.
+ Mainmatter assembled our experience from helping clients successfully modernize some of the
+ worlds most important software into this book.
+
+
+ Whether you rewrite a self-contained library from scratch or incrementally migrate a large,
+ complex codebase that keeps changing, this book teaches you the techniques to succeed. You
+ will learn how to maintain a safe mixed C-Rust codebase, design and structure clean APIs, and
+ translate common C idioms into idiomatic Rust.
+
+
+
+
+
+ The C to Rust Migration Book
+ {{
+ btnPrimary({
+ "label": "Start the course",
+ "url": "/c-to-rust-migration-book/course/"
+ }, "white", "mt-2")
+ }}
+
+
+ {% image "/assets/images/rust/c-to-rust-migration-book/c-to-rust-books.webp", "C to Rust migration books", "(min-width: 62em) 45vw, 90vw", "lazy", "c-to-rust-migration-feature__media", [760, 1440, 1920] %}
+
+
+
+
+
+ This workshop is built around our philosophy
+ of self-paced exercises. Each concept is paired with an exercise you solve in a real Rust
+ package, with a test suite that checks your solution.
+
+
+ It assumes prior knowledge of Rust and some C. No prior FFI experience required. That's what
+ the course teaches.
+
+ By the end you'll be ready to introduce Rust into a C codebase in a productive way.
+
+
+ {% include "global/c-to-rust-newsletter-cta.njk" %}
+
+ {%
+ set topics = [{
+ "title": "Foreign Function Interfaces",
+ "text": "The fundamentals of FFI: how C and Rust communicate at the binary level through the C ABI, symbol tables, and the linker. You'll write your first extern \"C\" blocks by hand and see what you're promising the compiler when you declare a binding, and what goes wrong when the signature doesn't match."
+ },{
+ "title": "Types and Data Across the Boundary",
+ "text": "How to move primitive values, strings, structs, and collections across the language boundary while keeping ownership clear. You'll use bindgen to generate Rust bindings from C headers, and cheadergen, Mainmatter's tool for the reverse direction, to generate C headers from your Rust code, and configure both for non-trivial types."
+ },{
+ "title": "FFI-Safe Types",
+ "text": "Raw pointers and untyped primitives are a major source of bugs at the FFI boundary. You'll learn safer alternatives: NonNull, Option, newtype wrappers, and enum discriminants that carry meaning instead of bare values, and how to design types that make invalid states unrepresentable even when talking to C code that has no type safety of its own."
+ },{
+ "title": "FFI validation",
+ "text": "Every FFI function is a trust boundary. C callers can pass null pointers, out-of-range values, or invalid UTF-8, and Rust can't catch that at compile time. You'll build the discipline of validating and narrowing inputs at the boundary, so invalid data from C never reaches safe Rust or your business logic."
+ },{
+ "title": "Error Handling and API Design",
+ "text": "Rust's Result and ? stop at extern \"C\". You'll convert Rust error types into C-compatible results with error-code enums and out-parameters, and surface failure information without leaking Rust internals. You'll also learn to expose coarse operations rather than per-field setters and keep your API surface small."
+ },{
+ "title": "Production-Quality FFI",
+ "text": "You'll document FFI functions with Rust's /// # Safety convention and numbered invariants, so every unsafe contract is explicit and surfaces as C doc comments in the generated headers via cheadergen. We cover build integration, automated checks, and treating your FFI surface as an API you'll maintain forever."
+ }]
+ %}
+ {{ strategyList('course-topic', 'Table of contents', topics) }}
+
+ {% set mentor = 'JonasKruckenberg' | findBySlug %}
+ {% set mentorBio = "Jonas Kruckenberg is an engineer at Mainmatter and creator of the k23 operating system. He has helped people to build fast, secure, cross-platform desktop apps through his work on Tauri and is deeply involved in open-source, local-first, and humane software. Outside of code, he sings in classical ensembles and enjoys hiking." %}
+
+
+
+
+ Facing Rust challenges and need a helping hand?
+
+ Mainmatter is an engineering consultancy specializing in Rust. We offer
+ engineering services, training, and mentorship to companies that aim to migrate from C to
+ Rust or introduce Rust into an existing codebase.
+
+
+ We can help with
+ complex C-to-Rust migrations, reliability issues, training, and skill gaps.
+
+ {%
+ set link = {
+ "label": "Contact us",
+ "url": "/contact/?utm_source=C+Rust+Book"
+ }
+ %}
+ {{ btnSecondary(link, "mt-2") }}
+
+
+
+
+
+ {% image "/assets/images/rust/eurorust-2026.png", "EuroRust 2026 logo", "36rem", "lazy", "", [760, 1440] %}
+
+
+ Community
+ EuroRust 2026
+
+ EuroRust is a two-day conference for all things Rust, plus two more days of side activities,
+ workshops, and hackathons. Join us in October in Barcelona.
+
+ {{
+ btnPrimary({
+ "label": "Get your ticket",
+ "url": "https://eurorust.eu"
+ }, "white", "mt-2")
+ }}
+
+
+
diff --git a/src/components/cta-banner.njk b/src/components/cta-banner.njk
index cb9355f37d..bc466aa577 100644
--- a/src/components/cta-banner.njk
+++ b/src/components/cta-banner.njk
@@ -51,7 +51,7 @@
diff --git a/src/components/global/c-to-rust-newsletter-cta.njk b/src/components/global/c-to-rust-newsletter-cta.njk
new file mode 100644
index 0000000000..188269969f
--- /dev/null
+++ b/src/components/global/c-to-rust-newsletter-cta.njk
@@ -0,0 +1,12 @@
+{% from "cta-banner.njk" import ctaBanner %}
+{%
+ set content = {
+ "id": "newsletter",
+ "title": "Sign up for updates",
+ "text": "New chapters are on the way. Subscribe to our newsletter to be the first to find out.",
+ "newsletterSignupAction": "//mainmatter.us13.list-manage.com/subscribe?u=50bd3378ab1da4988aa174d0b&id=44c25eef8c",
+ "newsletterSignup": true,
+ "buttonText": "Sign up"
+ }
+%}
+{{ ctaBanner('purple', 'medium', content) }}
diff --git a/src/components/global/footer.njk b/src/components/global/footer.njk
index 5fefc918be..a1561fe257 100644
--- a/src/components/global/footer.njk
+++ b/src/components/global/footer.njk
@@ -1,27 +1,29 @@
{% from "social-list.njk" import socialList %}
-