Robert Krahn

org-ai — Emacs as your personal AI assistant

robert@kra.hn (Robert Krahn) — Sat, 01 Apr 2023 00:00:00 +0000

org-ai is an Emacs extension that provides functionality by integrating various AI models into Emacs. This demo gives an impression:

The project can be found on Github. Currently, features include:

use ChatGPT
- in org-mode with #+begin_ai...#+end_ai blocks
- directly with a prompt anywhere
- on selected text to ask questions or request other actions
- refactor code
generate images and image variations with DALL-E
speech input and output

Setting up Github Copilot in Emacs

robert@kra.hn (Robert Krahn) — Wed, 22 Feb 2023 00:00:00 +0000

Quickstart

Either follow the instructions of zerolfx/copilot.el or use a ready-to-roll config provided at rksm/copilot-emacsd.

This is a short walkthrough describing my current Emacs-Copilot setup. Copilot is primarily advertised as a VSCode utility but actually it works really well in Emacs. Given the ease of adjustments (e.g. when to see completions) I would even argue Emacs might provide a better experience.

Changelog

2023-03-20: zerolfx/copilot.el has been updated, so switching to only referencing it instead of my fork. Thank you Jason H.!

Intro & Disclaimer

Github Copilot is a tool that uses machine learning to generate text completions, primarily meant for source code, even though it works surprisingly well for all kinds of texts. It is a commercial Microsoft product, though it is currently free to use if you have a few public Github repositories that have garnered some stars. It is based on OpenAI’s Codex model which itself is derived from the GPT-3 large language model (LLM). So in some sense it is ChatGPT for your editor.

LLMs that are trained on open (source) data generally, and Copilot in particular, are controversial. Among other things, many people have expressed concerns about the questionable legal grounds that these tools are build on, e.g. there is currently a pending lawsuit focusing on potential violations of open source licenses. So let me say that I’m well aware of the controversy and I would suggest careful use of Copilot, in particular when used in code bases that are not your own.

That said, it can be an astonishingly useful tool. For example, when learning languages or frameworks or dealing with new libraries are APIs, it is surprisingly good at providing guidance that often saves you many trips to the documentation. Moreover, it is really good at detecting certain patterns in your code while also seeing variations and suggesting new code based on that — clever copy/paste on steroids. Also tests are a good area where Copilot can be helpful.

And of course check the generated code. That thing will make mistakes. It is surprisingly good at getting the syntax right (though sometimes it won’t correctly close parentheses) but be aware of logical issues, anti-patterns, or outdated code.

Copilot API & integration

Even though Copilot is primarily a VSCode utility, making it work in Emacs is fairly straightforward. In essence it is not much different than a language server. The VSCode extension is not open source but since it is implemented in JavaScript you can extract the vsix package as a zip file and get hold of the JS files. As far as I know, the copilot.vim plugin was the first non-VSCode integration that used that approach. The worker.js file that is part of the vsix extension can be started as a node.js process that will read JSON-RPC data from stdin. There are a number of commands that are implemented using this format, here is the current full list:

getCompletions
getCompletionsCycling
getPanelCompletions
getVersion
setEditorInfo
checkStatus
signInInitiate
signInConfirm
signOut
notifyShown
notifyAccepted
notifyRejected
telemetry/exception
testing/createContext
testing/alwaysAuth
testing/neverAuth
testing/useTestingToken
testing/setCompletionDocuments
testing/setPanelCompletionDocuments
testing/triggerShowMessageRequest
testing/getDocument
debug/verifyState
debug/verifyCertificate
debug/verifyWorkspaceState

An editor like Emacs or VIM can start the worker in a subprocess and then interact with, sending JSON messages and reading JSON responses back via stdout.

Given that VSCode uses the exact same interface and from everything I’ve tried so far, I think it is safe to assume that using Copilot with Emacs is in no way inferior. On the contrary, as shown below, customizing the way Copilot works is actually more convenient (at list if you know some elisp :). I’m particularly mentioning that because some folks seem to believe that this is not the case. Should I be wrong on this (now or later), please let me know. It’s annoying that not event the Copilot agent isn’t open source (without open source none of this would be possible!) but it is not that complicated to figure out what it does. Which in turn means that other clients can catch up.

Copilot Emacs packages

On Github I have found three Emacs packages that implement Copilot integration:

zerolfx/copilot.el seems by far the most popular one and is the one I’m using below. It provides completions through an overlay, similar to the VSCodes extension.
fkr-0/flight-attendant.el might be inactive, the last commit was a year ago. I have not tried it.
tyler-dodge/eglot-copilot/ seems to be actively developed but has no documentation. It uses eglot for managing the subprocess and counsel for completions.

Setup & Customizations

You can find a fully working config building on zerolfx/copilot.el that can also be run standalone at rksm/copilot-emacsd. In the following I explain some of the customizations.

zerolfx/copilot.el is not on MELPA so you have to install it through straight.el or other means (see the README). I typically add an Emacs package like that as a submodule to my config:

git submodule add https://github.com/zerolfx/copilot.el
git submodule update --init

The packages required for it to work are: s, dash, editorconfig (and I also use company, use-package and Emacs built-in cl package here as I find those very helpful). Install them like this:

(require 'cl)
(let ((pkg-list '(use-package
		          s
		          dash
		          editorconfig
                  company)))
  (package-initialize)
  (when-let ((to-install (map-filter (lambda (pkg _) (not (package-installed-p pkg))) pkg-list)))
    (package-refresh-contents)
    (mapc (lambda (pkg) (package-install pkg)) pkg-list)))

Assuming the above git submodule was cloned into copilot.el/, we can now load that package:

(use-package copilot
  :load-path (lambda () (expand-file-name "copilot.el" user-emacs-directory))
  ;; don't show in mode line
  :diminish)

You can now run M-x copilot-login to authenticate with your Github account (that needs to have a subscription to the Copilot product) followed by M-x global-copilot-mode to activate Copilot everywhere.

Restricting when to show completions

global-copilot-mode will sometimes be a bit too eager, so we disable in some modes completely:

(defun rk/no-copilot-mode ()
  "Helper for `rk/no-copilot-modes'."
  (copilot-mode -1))

(defvar rk/no-copilot-modes '(shell-mode
                              inferior-python-mode
                              eshell-mode
                              term-mode
                              vterm-mode
                              comint-mode
                              compilation-mode
                              debugger-mode
                              dired-mode-hook
                              compilation-mode-hook
                              flutter-mode-hook
                              minibuffer-mode-hook)
  "Modes in which copilot is inconvenient.")

(defun rk/copilot-disable-predicate ()
  "When copilot should not automatically show completions."
  (or rk/copilot-manual-mode
      (member major-mode rk/no-copilot-modes)
      (company--active-p)))

(add-to-list 'copilot-disable-predicates #'rk/copilot-disable-predicate)

Then, it is also convenient to have the overlays not appear automatically but on-demand:

(defvar rk/copilot-manual-mode nil
  "When `t' will only show completions when manually triggered, e.g. via M-C-<return>.")

(defun rk/copilot-change-activation ()
  "Switch between three activation modes:
- automatic: copilot will automatically overlay completions
- manual: you need to press a key (M-C-<return>) to trigger completions
- off: copilot is completely disabled."
  (interactive)
  (if (and copilot-mode rk/copilot-manual-mode)
      (progn
        (message "deactivating copilot")
        (global-copilot-mode -1)
        (setq rk/copilot-manual-mode nil))
    (if copilot-mode
        (progn
          (message "activating copilot manual mode")
          (setq rk/copilot-manual-mode t))
      (message "activating copilot mode")
      (global-copilot-mode))))

(define-key global-map (kbd "M-C-<escape>") #'rk/copilot-change-activation)

M-C-<escape> will now cycle between three states automatic, manual and off.

Customizing keys

Copilot-specific

I like my keybindings to be somewhat consistent and have assigned M-C-... (Alt + Control + some other key) to Copilot related commands:

(defun rk/copilot-complete-or-accept ()
  "Command that either triggers a completion or accepts one if one
is available. Useful if you tend to hammer your keys like I do."
  (interactive)
  (if (copilot--overlay-visible)
      (progn
        (copilot-accept-completion)
        (open-line 1)
        (next-line))
    (copilot-complete)))

(define-key copilot-mode-map (kbd "M-C-<next>") #'copilot-next-completion)
(define-key copilot-mode-map (kbd "M-C-<prior>") #'copilot-previous-completion)
(define-key copilot-mode-map (kbd "M-C-<right>") #'copilot-accept-completion-by-word)
(define-key copilot-mode-map (kbd "M-C-<down>") #'copilot-accept-completion-by-line)
(define-key global-map (kbd "M-C-<return>") #'rk/copilot-complete-or-accept)

Tab key

If you also want to use the <tab> key for completion but still keep the normal functionality on it, do:

(defun rk/copilot-tab ()
  "Tab command that will complet with copilot if a completion is
available. Otherwise will try company, yasnippet or normal
tab-indent."
  (interactive)
  (or (copilot-accept-completion)
      (company-yasnippet-or-completion)
      (indent-for-tab-command)))

(define-key global-map (kbd "<tab>") #'rk/copilot-tab)

Ctrl-g / cancel

I like to cancel commands with C-g. This does not work out of the box with canceling Copilot completions, be we can do:

(defun rk/copilot-quit ()
  "Run `copilot-clear-overlay' or `keyboard-quit'. If copilot is
cleared, make sure the overlay doesn't come back too soon."
  (interactive)
  (condition-case err
      (when copilot--overlay
        (lexical-let ((pre-copilot-disable-predicates copilot-disable-predicates))
          (setq copilot-disable-predicates (list (lambda () t)))
          (copilot-clear-overlay)
          (run-with-idle-timer
           1.0
           nil
           (lambda ()
             (setq copilot-disable-predicates pre-copilot-disable-predicates)))))
    (error handler)))

(advice-add 'keyboard-quit :before #'rk/copilot-quit)

And that should be it!

Thanks to all the awesome Emacs hackers who made all this possible!

Speeding up incremental Rust compilation with dylibs

robert@kra.hn (Robert Krahn) — Fri, 09 Sep 2022 00:00:00 +0000

TL;DR

Creating a dynamic version of a Rust library can improve incremental compilation speed during development quite substantially. cargo add-dynamic automates the setup process.

One of Rust’s biggest downsides is that it tends to be rather slow when compiling programs. A lot of work has been put into improving the situation over the years with noticable impact. In addition, there are a number of good guides out there that explain the impact of various optimization options and tooling choices:

One tip that I have not seen widely mentioned is the use of dynamic libraries that can help decreasing incremental compilation speed quite dramatically. Bevy provides this as a feature flag (see last link above) but this approach can be used for most other dependencies as well.

Incremental compilation matters so much because it directly affects development feedback. This is not just re-running the application but also the wait time for feedback from the compiler and tools such as rust-analyzer. When recompilation is slow, it is not rare to wait seconds for compiler errors to appear — infuriating!

Changelog

2022-09-14: Mentioning diamond-dependency problem
2022-09-10: Added breakdown about time spent, link to reddit, env var for feature

Example with polars

Here is an easy to produce example with polars. Polars is a dataframe library, a Rust (and python) alternative to the popular Python pandas library. I lately have used it a lot for data analysis and exploration, during which fast feedback cycles help a lot.

So to get started, here is the baseline with a simple polars hello world:

# create a new project
cargo new polars-test
cd polars-test

# add polars as dependency
cargo add polars --features csv-file,lazy,list,describe,rows,fmt,strings,temporal

# modify main.rs
cat > src/main.rs << EOM
use polars::prelude::*;

fn main() {
    let df = df!("col 1" => ["a"]).unwrap();
    dbg!(df);
}
EOM

# first full build, this should take a while
cargo build

We create a new project, add polars as dependency and create a dataframe in the main function. Polars offers a ton of (Rust) features, so much so that using it without a number of those does not make much sense. The above is quite typical for what I would typically use for working on csv data. The initial build is expected to take a while (on my computer¹ about 25 seconds).

But now on to incremental changes. We make a small change to the main.rs file and rebuild.

sed -i '' 's/"a"/"b"/' src/main.rs
time cargo build
# real	0m2.896s
# user	0m2.080s
# sys	0m0.237s

Almost 3 seconds, not great. Let’s try the same thing with polars as a dynamic library:

cargo rm polars
cargo install cargo-add-dynamic
cargo add-dynamic polars --features csv-file,lazy,list,describe,rows,fmt,strings,temporal
cargo build

We are using the cargo command cargo-add-dynamic to re-install polars and wrapping it as a dynamic library. Using this command is optional, the setup can be done manually (see below).

And now building incrementally:

sed -i '' 's/"b"/"a"/' src/main.rs
time cargo build
# real	0m0.485s
# user	0m0.391s
# sys	0m0.110s

This is a 5x improvement over the static version! Moreover, half a second is not all that noticable, 3 seconds gets quite annoying quickly. So how does it work?

Wrapping dependencies as dylibs

By default, Rust dependencies will be linked statically with the resulting binary file being build. For production use, this is typically very desirable as this enables a number of optimizations like inlining and makes the resulting binary (mostly) “standalone”, i.e. no (or only some) libraries will need to be found and loaded at runtime.

During development, the Rust compiler will need to do this work as well. This means that for “heavy” dependencies that export a lot of symbols recompilation and linking can be expensive. When forcing a dependency to by dynamic, the compiler will not need to do the same amount of work, however.

We can can capture and then compare build times using the nightly time-passes flag that will output time and memory usage for various compilation steps:

RUSTFLAGS="-Z time-passes" time cargo +nightly build &> time-passes.log

This results in many lines of output, so redirecting this into a file is recommended. The output of both a dynamic and a static recompilation can be diffed but the differences are quite visible directly when looking at the last few lines:

With a static build:

...
time:   2.352; rss:  105MB ->  105MB (   +0MB)	run_linker
time:   2.353; rss:  104MB ->  105MB (   +1MB)	link_binary
time:   2.353; rss:  104MB ->  105MB (   +1MB)	link_crate
time:   2.356; rss:  104MB ->  105MB (   +1MB)	link
time:   2.511; rss:   20MB ->   59MB (  +39MB)	total
    Finished dev [unoptimized + debuginfo] target(s) in 2.64s

With a dynamic build:

...
time:   0.202; rss:  103MB ->  103MB (   +0MB)	run_linker
time:   0.203; rss:  102MB ->  103MB (   +1MB)	link_binary
time:   0.203; rss:  102MB ->  103MB (   +1MB)	link_crate
time:   0.206; rss:  102MB ->  103MB (   +1MB)	link
time:   0.346; rss:   20MB ->   56MB (  +36MB)	total
    Finished dev [unoptimized + debuginfo] target(s) in 0.47s

So the main differences really are just in the linking phase. As was mentioned by u/valarauca14 on reddit

Static linking is relatively complex while run-time dynamic linking is super straight forward.

With Static Linking you need to index the object, respect the “weakness”/“strength” of symbols, resolve conflicts, and potentially rewrite offsets within functions/assembly when gluing things together. Potentially repair debug/data that now conflicts with one-another. Constants maybe merged/dropped. These constants are not necessarily_defined by the developer, they can be ABI specific stuff (like dynamic linking points/stack unwrapping heap reservations, etc.).

This work is rather expensive computationally. Fast linkers like mold don’t support some of these things (or they’ve received the bug report and are working on a solution). While faster linkers like gold have the luxury of newer algorithms/fresh eyes on old problems.

With dynamic-linking. The object file has a literal index to help you determine symbol -> start/end byte offset. This file will be pre-loaded into memory at start. It is a very quick operation, normally just a memcp (to put the function into executable memory) + mov to update the offset so the original program can link to. This also occurs lazily at runtime, so loading & linking is amortized into runtime.

And indeed, as all of the guides linked above recommend, switching to a faster linker such as mold (on Linux) or zld (on macOS) does make a difference. Switching to zld on my machine brings down the static compilation time to around 2 seconds while the dynamic compilation time stays at around 0.5 seconds. So even though a faster linker improves the situation, there is still a notable difference.

crate-type = [“dylib”]

How can a dependency be made dynamic? The Rust compiler supports various methods to link crates together both statically and dynamically. A dependency itself can specify it’s output type in its Cargo.toml using the crate-type setting:

[lib]
crate-type = ["dylib"]

When a crate is only available as dylib, the compiler will be forced to link to it dynamically.

polars-dynamic

Going back to the example above and the cargo add-dynamic polars command. It automated the creation of a sub-package polars-dynamic that wrapped the original library. It has the following content:

`polars-dynamic/Cargo.toml`

[package]
name = "polars-dynamic"
version = "0.1.0"
edition = "2021"

[dependencies]
polars = { version = "0.23.2", features = ["csv-file", "lazy", "list", "describe", "rows", "fmt", "strings", "temporal"] }

[lib]
crate-type = ["dylib"]

`polars-dynamic/src/lib.rs`

pub use polars::*;

`Cargo.toml`

And then instead of depending on directly on polars, the main project can use the local wrapped sub-package:

# ...

[dependencies]
polars = { path = "polars-dynamic", package = "polars-dynamic" }

Limitation: The diamond dependency problem

As was brought up in a github issue, there is an important limitation in this approach. Because of how Rust deals with transitive dependencies during linking, if two dylibs (B and C) depend both on a static dependency (A) and a binary (D) uses B and C then you will see a compile error along the lines of error: cannot satisfy dependencies so A only shows up once.

In particular this comes up when trying to dynamically link against both serde and serde_json. If both of these are wrapped as dylibs as shown above, we end up with a dependency graph such as:

graph TD; bin["binary"]-.->serde_dylib["serde (dylib)"]; bin-.->serde_json_dylib["serde_json (dylib)"]; serde_json_dylib-->serde_json; serde_json-->serde1["serde"]; serde_dylib-->serde2["serde"];

The problem is that the serde (dylib) dependency provides a copy of serde to the binary and serde_json pulls in another copy of serde as well. Even though the versions are the same, Rust cannot deal with this because of global state mentioned in the linked issue above.

The solution is to make serde_json depend on serde dynamically as well so that the same dylib can be linked to serde-dynamic and serde_json.

graph TD; bin["binary"]-.->serde_dylib["serde (dylib)"]; bin-.->serde_json_dylib["serde_json (dylib)"]; serde_json_dylib-->serde_json; serde_json-.->serde_dylib; serde_dylib-->serde;

However, this unfortunately is not straightforward. If serde would specify a crate-type of dylib in addition to rlib, we could use RUSTFLAGS="-C prefer-dynamic" to build it as a dylib and have both our binary as well as serde_json depend on it dynamically. Unfortunately, serde does not specify that crate-type so the only solution that makes this currently work is to clone https://github.com/serde-rs/json and use a modified version of it that points to a dynamic serde lib. Now this is certainly undesirable.

For this specific scenario, a pull request against serde to allow for opt-in dylib builds might be one solution. But generally, this seems like a shortcoming of how dylib builds can be specified: The crate that is to be consumed needs to do it via crate-type. Dependent crates cannot override this. In my opinion this is something that could be added to Rust/Cargo as it looks like a backwards compatible addition. Though there might be complications that I do not consider.

Switching between static and dynamic dependencies

And this is how re-compilation can be improved when depending on “heavy” libraries. You will probably not want to use this for production as this would mean having to ship additional libraries and making sure they can be found at runtime. In addition, a number of optimizations won’t be available.

So switching between a development and production version is advisable. You can do this quite easily with a feature flag as just loading the dynamic library will force dynamic linking:

#![allow(unused_imports)]

#[cfg(feature = "dynamic")]
use polars_dynamic;

use polars::prelude::*;

And Cargo.toml would then specify:

[dependencies]
polars = { version = "0.23.2", features = [...]}
polars-dynamic = { path = "polars-dynamic", optional = true }

[features]
default = []
dynamic = ["dep:polars-dynamic"]

Now cargo build --feature dynamic will make use of the dynamic polars dependency.

Controlling `--feature dynamic` with an environment variable

To make the feature selection automated based on environment variables, a suggestion from Matthias Beyer (thanks!) is to employ a build.rs script such as

fn main() {
    println!("cargo:rerun-if-env-changed=DYNAMIC");
    if std::env::var("DYNAMIC").is_ok() {
        println!("cargo:rustc-cfg=feature=\"dynamic\"");
    }
}

which can then be set like DYNAMIC=1 cargo run or in a .env file or similar.

Using it with hot-reloading

This can be used in combination with hot-reloading Rust code. In particular, having the ability to replace behavior on-the-fly but having to wait for a long time on the compilation process makes little sense. And indeed, several of the hot-reload examples make use of this approach.

MacBooPro M1 (MacBookPro18,3), 32GB RAM ↩︎

Hot Reloading Rust — for Fun and Faster Feedback Cycles

robert@kra.hn (Robert Krahn) — Thu, 04 Aug 2022 00:00:00 +0000

TL;DR

hot-lib-reloader allows to change Rust code on the fly without restarts. It works on Linux, macOS, and Windows. For why, how it works and, how to use it (as well as the limitations of this approach) read the post below.

Hot-reloading a Bevy app

Development with Rust can be a lot of fun and the rich type system in combination with good tooling such as rust-analyzer can provide helpful hints and guidance continuously while writing code.

This, however, does not fully compensate for slower workflows that come from edit-compile-run cycles that require full program restarts plus the time it takes to recompile the entire program. Rust provides incremental compilation support that reduces the time for rebuilds often down to few seconds or for lightweight programs even less. But relying on, for example, macro-heavy code or types that make ample use of generics, compile times can go up quickly. This makes development with Rust quite different from lively environments and dynamic languages that might not just come with less build time but that might even provide feedback at the tip of a key.

Whether or not this impedes the ability to build software depends of course on what is built and on the approach a developer generally takes. For use cases such as games, UIs, or exploratory data analysis, quick feedback can certainly be an advantage — it might even allow you to make experiments that you would not have tried otherwise.

To enable such dynamic workflows when programming Rust, I have long wanted a tool that makes immediate feedback possible and hopefully easy to use. This blog post presents my take on the matter by introducing the hot-lib-reloader crate.

Changelog

2022-08-15: Update for hot-lib-reloader v0.6
2022-08-09: Update for hot-lib-reloader v0.5

Where this idea comes from

None of this is new of course. Lots of languages and tools were created to allow code changes at runtime. “Live programming” in Smalltalk and Lisps is an essential part of those languages and which is enabled by reflection APIs the languages possess as well as by tools that¹. Also Erlang’s hot code swapping plays an important role for the reliability of Erlang programs — upgrading them is not an “exception”, it is well supported out of the box.

“Static” languages have traditionally much less support for the runtime code reload. An important part of it is certainly that optimizations become much harder to achieve when assembly code needs to support being patched up later². But even though modifying code arbitrarily is hard, dynamically loaded libraries are an old idea. Support for those is available in every (popular) operating system and it has been used to implement hot code reloading many times.

For C / C++, this mechanism has been made popular by the Handmade Hero series which presents this approach in detail (1, 2, 3). And also in Rust there have been posts and libraries around this idea (for example Hot Reloading Rust: Windows and Linux, An Example of Hot-Reloading in Rust, Live reloading for Rust, dynamic_reload).

Dynamic library (re-)loading is also what I am using in the approach presented here. The fundamental implementation is quite similar to the work linked above. Where this differs somewhat is in how you can interface with the reloader. By using a macro that can figure out the exposed library functions, it is possible to avoid a lot of boilerplate. In addition I will later show how this can be further customized to play nice in the context of frameworks such as Bevy.

“Hello World” example³

The simplest example will require a binary with some kind of main loop and a library that contains the code to be reloaded. Let’s assume the following project layout where the binary is the root package of a Cargo workspace and the library is a sub-package:

$ tree
.
├── Cargo.toml
└── src
│   └── main.rs
└── lib
    ├── Cargo.toml
    └── src
        └── lib.rs

The root Cargo.toml defines the workspace and the binary. It will depend on the hot-lib-reloader crate that takes care of watching the library and reloading it when it changes:

[workspace]
resolver = "2"
members = ["bin", "lib"]

[package]
name = "bin"
version = "0.1.0"
edition = "2021"

[dependencies]
hot-lib-reloader = "^0.6"
lib = { path = "lib" }

The library should expose functions and state. It should have specify dylib as crate type, meaning it will produce a dynamics library file such as liblib.so (Linux), liblib.dylib (macOS), and lib.dll (Windows). The lib/Cargo.toml:

[package]
name = "lib"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["rlib", "dylib"]

lib/lib.rs is providing a single public and unmangled function do_stuff that accepts some state parameter:

// When using the source_files: ["path/to/lib.rs"] auto discovery
// reloadable functions need to be public and have the #[no_mangle] attribute

pub struct State {
    pub counter: usize,
}

#[no_mangle]
pub fn do_stuff(state: &mut State) {
    state.counter += 1;
    println!("doing stuff in iteration {}", state.counter);
}

And finally src/main.rs where we define a sub-module hot_lib using the hot_module attribute macro:

// The value of `dylib = "..."` should be the library containing the hot-reloadable functions
// It should normally be the crate name of your sub-crate.
#[hot_lib_reloader::hot_module(dylib = "lib")]
mod hot_lib {
    // Reads public no_mangle functions from lib.rs and  generates hot-reloadable
    // wrapper functions with the same signature inside this module.
    hot_functions_from_file!("lib/src/lib.rs");

    // Because we generate functions with the exact same signatures,
    // we need to import types used
    pub use lib::State;
}

fn main() {
    let mut state = hot_lib::State { counter: 0 };
    // Running in a loop so you can modify the code and see the effects
    loop {
        hot_lib::do_stuff(&mut state);
        std::thread::sleep(std::time::Duration::from_secs(1));
    }
}

Above is the part that matters: The hot_lib module embeds a hot-reloadable version of do_stuff(&mut State). It has the same signature as the original defined in lib/lib.rs but it’s implementation will load it from the latest version of the dynamic library. This means we can just use it like the original function but it will be automatically updated when the library file changes! If you want to see the generated code that does all this you can run cargo expand.

OK, now we can actually run the app. Start two cargo commands (this assumes you have cargo-watch installed):

cargo watch -w lib -x 'build -p lib' which will recompile the lib when it changes
cargo run which will start the app with hot-reloading enabled

Now modify the do_stuff function, e.g. by changing the printed text or adding additional statements. You should see the output of the running application change immediately.

How it works

hot-lib-reloader uses the libloading crate which provides a unified and safe(r) interface around functions provided by the operating system to load and unload dynamic libraries (dlopen, dlclose, LoadLibraryEx, etc.). It watches the library file or files you specify using notify. When one of those changes it will mark the library as having a pending change. LibReloader::update will then use libloading to close the previously loaded library instance and load the new version. The module generated with the hot_module attribute macro above is a wrapper around a static instance of LibReloader::update. Actual calls to library functions are then made by looking up a symbol with the matching function name, assuming it resolves to an actual function with the signature assumed, and then calling it.

For various reasons the reloader will not actually load the library file that Rust created but will create a copy and load that. Among other things this prevents from holding a file lock on Windows, allowing the library file to change.

In addition to that, the hot_module macro takes care of some boilerplate. When declaring and using a reloader. A desugared version of the function do_stuff(&mut State) shown above will look like:

pub fn do_stuff(state: &mut State) {
    let lib_loader = __lib_loader();
    let lib_loader = lib_loader.read().expect("lib loader RwLock read failed");
    let sym = unsafe {
        lib_loader
           .get_symbol::<fn(&mut State)>(b"do_stuff\x00")
           .expect("Cannot load library function do_stuff")
    };
    sym(state)
}

In particular, without the macro it is necessary to keep the function signatures between where they are declared and where they are used in sync. To avoid that boilerplate, the macro can automatically implement the correct interface by looking at the exported function in the specified source files. In addition, LibReloader actively watches for file changes and runs lib updates in its own thread.

Caveats and Asterisks

This approach comes unfortunately with several caveats. The runtime of the program that the lib reloader operates in is a compiled Rust application with everything that involves. The memory layout of all types such as structs, enums, call frames, static string slices etc is fixed at compile time. If it diverges between the running application and the (re-)loaded library the effect is undefined. In that case the program will probably segfault but it might keep running with incorrect behavior. Because of that, all use of the reloader should be considered unsafe and I would highly advise against using it in situations where correctness and robustness of your application is required. This means, don’t use it for production environments or anything critical. The approach shown here is meant for development and fast feedback in situations where a crash is OK and nothing is at risk.

Global state

Because of that, what can actually be changed while maintaining the dynamic library re-loadable is limited. You can expose functions with signatures that shouldn’t change or static global variables. If exposing structs and enums, changing their struct fields is undefined behavior. Using generics across the dynamic library border isn’t possible either as generic signatures will always be mangled.

But state can get tricky in other ways as well. If global state is used by parts of a program that get reloaded, the state will no longer be accessible by the new code. This for example can be observed when trying to reload the macroquad / miniquad game frameworks. Those initialize and maintain OpenGL state globally. When trying to call reloaded code that uses the OpenGL context such as emitting render instructions, the program will panic. Even though it would be possible to externalize and transfer this state on reload and using the reloader with those frameworks won’t work, at least when directly accessing OpenGL related behavior. For strategies around this see How to use it then? below.

dlopen/dlclose behavior

Furthermore, as pointed out in this really great blog post from Amos the behavior of dlclose on Linux in combination with how Rust deals with thread local storage can actually prevent a library from properly unloading. Even though the approach presented here will actually allow you to load the changed behavior into your program, memory leaks cannot be prevented. So while you reload on Linux you will leak some (tiny) amount of memory on each library update.

Function signatures

The function names of reloadable functions need to be not mangled, so a #[no_mangle] attribute is mandatory. This in turn means that functions cannot be generic (with the exception of lifetimes). Assuming the rustc version of the code that compiles the binary and library are identical, the functions can be loaded even if not declared with extern "C". This in turn means that passing “normal” Rust types works fine. I do not know enough about how the Rust compiler chooses the memory layout of structs and enums to know if the same (non-generic) struct / enum definition can be laid out differently between compilations when the code remains unchanged. I assume not but if you run into problems making using extern "C" and #[repr(C)] might be worth trying.

Supported platforms

The current version of hot-lib-reloader has been tested successfully on Linux, Windows, and Intel macOS.

How to use it then?

2022-08-15: Also check the usage tips section of the hot-lib-reloader readme.

The above mentioned limitations restrict the possibilities of what changes can be made to running code.

What typically works well is to expose one or a few functions whose signatures remain unchanged. Those can then be called from throughout your application. If you want to split up your code further, using multiple libraries and reloaders at the same time is no problem. The reloaders should regularly check if watched libraries have changed, for that purpose they provide an update method that returns true if the library was indeed reloaded. This gives you control over when reloads should happen and also allows you to run code to e.g. re-initialize state if the library changed.

For example, for developing a game a simple approach would be to expose a update(&mut State) function that modifies the game state and a render(&State) function that takes care of rendering that. Inside the game loop you call the update function of the lib reloader to process code changes and optionally re-initialize the game state.

For frameworks such as Bevy where the main loop is controlled elsewhere, you can normally register callbacks or event handlers that will be invoked. For dealing with Bevy systems in particular, see below.

Use features to toggle hot reload support

Since only few parts of the application need to differ between a hot reloadable and a static version, using Rust features is the recommended way to selectively use hot code reloading and to also produce production code without any dependencies on dynamic library loading.

The reload-feature example shows how you can modify the minimal code example presented above to achieve this.

If necessary, create indirections

In cases like miniquad where global state prevents reloading a library you can fall back to creating an indirection. For example if you want to have a render function that can be changed, you could use a function that decoratively constructs shapes / a scene graph that then gets rendered in the binary with calls that depend on OpenGL.

When you have full control over the main loop

Also, frameworks that follow a more “functional” style such as Bevy can be supported. For Bevy in particular there exists specific support in hot-lib-reloader, see the next section for details.

How to use it with Bevy

Bevy manages the programs main loop by default and allows the user to specify functions (which represent the “systems” in Bevy’s ECS implementation) which are then invoked while the game is running. It turns out this approach allows fits a hot-reloading mechanism really well. The system functions can be seamlessly provided by either a statically linked or dynamically loaded library. All input they need they can specify by function parameters. Bevy’s type-based “dependency injection” mechanism will then make sure to pass the right state to them. In addition, Bevy’s resource system is a good fit to manage the lib reloader instance. A separate system can deal with the update cycle.

You can find a ready-to-use example in the examples section of hot-lib-reloader. I will go through it step by step below.

The project structure can be identical to the example show above. We will rename lib to systems to make our intentions explicit:

$ tree
.
├── Cargo.toml
├── src
│   └── main.rs
└── systems
    ├── Cargo.toml
    └── src
        └── lib.rs

Bevy app binary

src/main.rs then defines a systems_hot module which loads the functions provide by systems/src/lib.rs that would normally be available through the systems module. In particular, systems and systems_hot are 1:1 replaceable when you export the static items from systems, like we do below by adding use systems::*; inside mod systems_hot {/**/}. A reload feature is used to allow switching between static and hot-reload version.

use bevy::prelude::*;

#[cfg(not(feature = "reload"))]
use systems::*;
#[cfg(feature = "reload")]
use systems_hot::*;

#[cfg(feature = "reload")]
#[hot_lib_reloader::hot_module(dylib = "systems")]
mod systems_hot {
    use bevy::prelude::*;
    use systems::*;
    hot_functions_from_file!("systems/src/lib.rs");
}

We can then define the main function that does not differ from other Bevy apps.

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_startup_system(setup)
        .add_system(player_movement_system)
        .add_system(bevy::window::close_on_esc)
        .run();
}

Bevy systems

The two systems used in the example that are located in systems/src/lib.rs are run-of-the-mill bevy system functions that I’ll abbreviate here to save some room. The only notable piece here is the #[no_mangle] attribute of player_movement_system — and the absence of such an attribute with setup.

pub fn setup(mut commands: Commands) { /*...*/ }

#[no_mangle]
pub fn player_movement_system(
    keyboard_input: Res<Input<KeyCode>>,
    mut query: Query<&mut Transform, With<Player>>,
) { /*...*/ }

Only public functions with #[no_mangle] will be recognized as reloadable functions by the hot_module’s hot_functions_from_file! macro above.

To build both the executable and reloadable systems library you can start two cargo processes. Building the library:

# watch ./systems/, build the library
$ cargo watch -w systems -x 'build -p systems'

Building the executable (for the reason why Windows needs special treatment see this note):

# watch everything but ./systems and run the app
$ cargo watch -i systems -x 'run --features reload'
# Note: on windows use
$ env CARGO_TARGET_DIR=target-bin cargo watch -i systems -x 'run --features reload'

Using cargo watch for the excutable is not strictly necessary but it allows you to quickly change it as well when you make modifications that aren’t compatible with hot-reload.

Hot-reload Template for cargo-generate

To quickly setup new projects that come with the stuff presented here out of the box, you can use a cargo-generate template available at: https://github.com/rksm/rust-hot-reload.

Run cargo generate rksm/rust-hot-reload to setup a new project.

Comments and feedback

I just started to use hot-lib-reloader and so far I am surprised how well it works. It is not bringing Rust on-par with Lisp or Smalltalk but with code that requires lots of twiddling and changes it is enjoyable to use! Let me know what your impressions are either directly or via the discussions of this article on

Also, if you find bugs or run into problems I’m watching the Github issues.

Over and out.

For a detailed look on how Smalltalk achieves this, Assisting System Evolution: A Smalltalk Retrospective is a recommended read. ↩︎
Although with or without built-in support, folks are able to achieve it regardsless. ↩︎
No need to type that up or anything. This and more examples can be found in the hot-lib-reloader example section. ↩︎

A Rust web server / frontend setup like it's 2022 (with axum and yew)

robert@kra.hn (Robert Krahn) — Sun, 03 Apr 2022 00:00:00 +0000

WebAssembly tooling for Rust has made big improvements and has matured tremendously over the previous two years. The build and packaging steps are now simpler thanks to tools like Trunk, as well as being able to write frontend code with various frameworks such as yew or dioxus. Also support for wasm is now supported in quite a few crates, basic ones such as chrono or higher level libraries such as plotters.

Additionally, the available options on the Rust server-side have increased. With projects like tower that provide reusable building blocks for clients / servers, web servers like axum came about that allow to quickly put together web apps without much boilerplate.

In this walkthrough I will describe my current default project setup for web projects that use Rust for frontend and backend. It is suitable for typical single-page web apps that use WASM/JS for rendering and routing. I have used it for dashboards, browser games and such but it should be suitable for any web app that wants to use a Rust server and frontend. I am choosing axum for the server part and yew for the frontend but it should work similarly with other choices. As for the features it will provide:

Running server / frontend in dev mode with automatic reload
Running server / client in production mode with pre-compiled sources
Serving additional files from a dist/ directory
Stub to allow adding more custom server logic

You can find the full code at https://github.com/rksm/axum-yew-setup. You can also use this code as a template to generate a new project using cargo-generate: cargo generate rksm/axum-yew-template.

Changelog

2023-03-13: No more axum-extra SPA router (thanks u/harunahi and u/LiftingBanana)
2023-01-15: Don’t need cargo-edit anymore (thanks u/lucca_huguet)
2023-01-09: Update for yew v0.20 (thanks to reddit user dvmitto for the nudge!)
2022-09-13: Note about strip = "symbols" breaks wasm code
2022-07-11: Trunk now seems to support workspace projects and won’t recompile from scratch when the server code changes. So this guide now uses a workspace setup. Also fix adding the dependencies, there was an issue with specifying the crate features.
2022-04-19: Fixed Trunk command (trunk serve, not trunk dev) and slightly shorter invocation of cargo watch. Thanks @trysetnull!
2022-04-14: Update requirements (Rust wasm target and trunk always-rebuild-from-scratch-issue)
2022-04-08: Fix for the prod.sh script when using SpaRouter

Tools required

This walkthrough relies on the following Rust tooling:

The Rust wasm32 target. You can install it with rustup target add wasm32-unknown-unknown (The target specification “triple” is the architecture, vendor and OS type. “unknown” means don’t assume a runtime).
Trunk, a WASM web application bundler for Rust. Install with cargo install trunk.
cargo-watch for restarting commands on file change with cargo watch .... Install with cargo install cargo-watch.

Project structure

The directory and file structure is simple, we will setup a rust workspace with server and frontend subdirectories that host the server and frontend sub-projects.

flowchart TD; root([web-wasm-project]) server([server]); frontend([frontend]); root --- server; root --- cargo_root("Cargo.toml (workspace)") root --- frontend; subgraph a server --- cargo_1(Cargo.toml) server --- main_1(src/main.rs) end subgraph b frontend --- cargo_2(Cargo.toml) frontend --- trunk_2(Trunk.toml) frontend --- index_2(index.html) frontend --- main_2(src/main.rs) end

We can set this up like that:

mkdir web-wasm-project
cd web-wasm-project
cargo new --bin server --vcs none
cargo new --bin frontend --vcs none
echo -e '[workspace]\nmembers = ["server", "frontend"]' > Cargo.toml
echo -e "target/\ndist/" > .gitignore
git init

Server

First, we add the depencies for the server:

cd server
cargo add \
  axum \
  log \
  tower \
  tracing \
  tracing-subscriber \
  clap --features clap/derive \
  tokio --features tokio/full \
  tower-http --features tower-http/full

We can now add code for starting the axum server and serving a simple text output to get started. Edit server/src/main.rs to match:

use axum::{response::IntoResponse, routing::get, Router};
use clap::Parser;
use std::net::{IpAddr, Ipv6Addr, SocketAddr};
use std::str::FromStr;

// Setup the command line interface with clap.
#[derive(Parser, Debug)]
#[clap(name = "server", about = "A server for our wasm project!")]
struct Opt {
    /// set the listen addr
    #[clap(short = 'a', long = "addr", default_value = "::1")]
    addr: String,

    /// set the listen port
    #[clap(short = 'p', long = "port", default_value = "8080")]
    port: u16,
}

#[tokio::main]
async fn main() {
    let opt = Opt::parse();

    let app = Router::new().route("/", get(hello));

    let sock_addr = SocketAddr::from((
        IpAddr::from_str(opt.addr.as_str()).unwrap_or(IpAddr::V6(Ipv6Addr::LOCALHOST)),
        opt.port,
    ));

    println!("listening on http://{}", sock_addr);

    axum::Server::bind(&sock_addr)
        .serve(app.into_make_service())
        .await
        .expect("Unable to start server");
}

async fn hello() -> impl IntoResponse {
    "hello from server!"
}

The server can be started with cargo run --bin server from the project root directory. You should see the “hello from server!” response at [::1]:8080 and localhost:8080 (if you want to use the IPv4 address).

Adding logging to the server

For an HTTP server it is useful to log requests. Axum and tower already use tracing to provide async-aware structured logging. We can setup tracing-subscriber to log those traces to stdout and also extend the command-line interface to accept setting the log verbosity via cli arguments.

diff --git a/server/src/main.rs b/server/src/main.rs
index 0000000..0000000 100644
--- a/server/src/main.rs
+++ b/server/src/main.rs
@@ -2,11 +2,17 @@ use axum::{response::IntoResponse, routing::get, Router};
 use clap::Parser;
 use std::net::{IpAddr, Ipv6Addr, SocketAddr};
 use std::str::FromStr;
+use tower::ServiceBuilder;
+use tower_http::trace::TraceLayer;
 
 // Setup the command line interface with clap.
 #[derive(Parser, Debug)]
 #[clap(name = "server", about = "A server for our wasm project!")]
 struct Opt {
+    /// set the log level
+    #[clap(short = 'l', long = "log", default_value = "debug")]
+    log_level: String,
+
     /// set the listen addr
     #[clap(short = 'a', long = "addr", default_value = "::1")]
     addr: String,
@@ -20,14 +26,23 @@ struct Opt {
 async fn main() {
     let opt = Opt::parse();
 
-    let app = Router::new().route("/", get(hello));
+    // Setup logging & RUST_LOG from args
+    if std::env::var("RUST_LOG").is_err() {
+        std::env::set_var("RUST_LOG", format!("{},hyper=info,mio=info", opt.log_level))
+    }
+    // enable console logging
+    tracing_subscriber::fmt::init();
+
+    let app = Router::new()
+        .route("/", get(hello))
+        .layer(ServiceBuilder::new().layer(TraceLayer::new_for_http()));
 
     let sock_addr = SocketAddr::from((
         IpAddr::from_str(opt.addr.as_str()).unwrap_or(IpAddr::V6(Ipv6Addr::LOCALHOST)),
         opt.port,
     ));
 
-    println!("listening on http://{}", sock_addr);
+    log::info!("listening on http://{}", sock_addr);
 
     axum::Server::bind(&sock_addr)
         .serve(app.into_make_service())

We will modify the server later to serve static content as well but for now let’s stop it (Ctrl-C) and first setup the frontend.

Frontend

We will use Trunk to bundle and serve (for development) the frontend code. You can install trunk with cargo install trunk. (As of this writing trunk version 0.16 is the most recent version and what was used for testing.)

Let’s first add all the dependencies we (eventually) need:

cd frontend;
cargo add \
  console_error_panic_hook \
  gloo-net \
  log \
  wasm-bindgen-futures \
  wasm-logger \
  yew --features yew/csr \
  yew-router

We are missing frontend/index.html which Trunk will use as the base html template. Create that file and edit it to match:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <link rel="shortcut icon"type="image/x-icon" href="data:image/x-icon;,">
    <title>Yew App</title>
  </head>
  <body>loading...</body>
</html>

Now edit frontend/src/main.rs for rendering a simple yew component:

use yew::prelude::*;
use yew_router::prelude::*;

#[derive(Clone, Routable, PartialEq)]
enum Route {
    #[at("/")]
    Home,
}

fn switch(routes: Route) -> Html {
    match routes {
        Route::Home => html! { <h1>{ "Hello Frontend" }</h1> },
    }
}

#[function_component(App)]
fn app() -> Html {
    html! {
        <BrowserRouter>
            <Switch<Route> render={switch} />
        </BrowserRouter>
    }
}
fn main() {
    wasm_logger::init(wasm_logger::Config::new(log::Level::Trace));
    console_error_panic_hook::set_once();
    yew::Renderer::<App>::new().render();
}

We are already using the yew router to make it easier to extend the app later. Running trunk serve (from the frontend directory) will now start the frontend in dev mode at localhost:8080. Making a change to the frontend code will automatically reload that page. Hot-reload & Rust — finally :)

Connecting frontend and server

Right now, the frontend and server only run individually but are not connected in a way that would allow them to run together in development or production mode. For production mode (serving pre-compiled frontend files without Trunk) to work properly we will need to serve those static files. To also allow a single-page app (SPA) app that uses different URL path in the frontend, we need to fallback to serve index.html for non-existing paths.

Let’s first modify the frontend to compile into a dist/ directory in the project root folder where files can be found by the server. Create a file frontend/Trunk.toml with the content:

[build]
target = "index.html"
dist = "../dist"

We can now modify the server to deliver the pre-compiled files. We make three changes to the server code:

We will allow to configure a static_dir directory that defaults to the dist/ folder in the project root directory. This is where we have configured Trunk to output compiled files in Trunk.toml above.
We will use tower_http::services::ServeDir to actually create a response for requests matching a file path. We will do that by adding a fallback handler to the server-side Router.
We move our “hello” route to /api/hello, we will query that later from the frontend to showcase client-server interaction.

diff --git a/server/src/main.rs b/server/src/main.rs
index 0000000..0000000 100644
@@ -1,8 +1,11 @@
+use axum::body::{boxed, Body};
+use axum::http::{Response, StatusCode};
 use axum::{response::IntoResponse, routing::get, Router};
 use clap::Parser;
 use std::net::{IpAddr, Ipv6Addr, SocketAddr};
 use std::str::FromStr;
-use tower::ServiceBuilder;
+use tower::{ServiceBuilder, ServiceExt};
+use tower_http::services::ServeDir;
 use tower_http::trace::TraceLayer;
 
 // Setup the command line interface with clap.
@@ -20,6 +23,10 @@ struct Opt {
     /// set the listen port
     #[clap(short = 'p', long = "port", default_value = "8080")]
     port: u16,
+
+    /// set the directory where static files are to be found
+    #[clap(long = "static-dir", default_value = "./dist")]
+    static_dir: String,
 }
 
 #[tokio::main]
@@ -34,7 +41,16 @@ async fn main() {
     tracing_subscriber::fmt::init();
 
     let app = Router::new()
-        .route("/", get(hello))
+        .route("/api/hello", get(hello))
+        .fallback_service(get(|req| async move {
+            match ServeDir::new(opt.static_dir).oneshot(req).await {
+                Ok(res) => res.map(boxed),
+                Err(err) => Response::builder()
+                    .status(StatusCode::INTERNAL_SERVER_ERROR)
+                    .body(boxed(Body::from(format!("error: {err}"))))
+                    .expect("error response"),
+            }
+        }))
         .layer(ServiceBuilder::new().layer(TraceLayer::new_for_http()));
 
     let sock_addr = SocketAddr::from((

If you now run trunk build in the frontend/ directory and cargo run --bin server in the root directory, the server should startup again, this time bringing up the yew app at localhost:8080 again, but served statically!

Custom server requests and frontend routing

Let’s query the /api/hello from the frontend.

First we will create a new yew component whose whole purpose it is to make a HTTP request to /api/hello and display it. Add it to frontend/main.rs:

#[function_component(HelloServer)]
fn hello_server() -> Html {
    let data = use_state(|| None);

    // Request `/api/hello` once
    {
        let data = data.clone();
        use_effect(move || {
            if data.is_none() {
                spawn_local(async move {
                    let resp = Request::get("/api/hello").send().await.unwrap();
                    let result = {
                        if !resp.ok() {
                            Err(format!(
                                "Error fetching data {} ({})",
                                resp.status(),
                                resp.status_text()
                            ))
                        } else {
                            resp.text().await.map_err(|err| err.to_string())
                        }
                    };
                    data.set(Some(result));
                });
            }

            || {}
        });
    }

    match data.as_ref() {
        None => {
            html! {
                <div>{"No server response"}</div>
            }
        }
        Some(Ok(data)) => {
            html! {
                <div>{"Got server response: "}{data}</div>
            }
        }
        Some(Err(err)) => {
            html! {
                <div>{"Error requesting data from server: "}{err}</div>
            }
        }
    }
}

In addition we will also setup an additional frontend route to render the new component at localhost:8080/hello-server:

diff --git a/frontend/src/main.rs b/frontend/src/main.rs
index 0000000..0000000 100644
--- a/frontend/src/main.rs
+++ b/frontend/src/main.rs
@@ -1,3 +1,5 @@
+use gloo_net::http::Request;
+use wasm_bindgen_futures::spawn_local;
 use yew::prelude::*;
 use yew_router::prelude::*;
 
@@ -5,11 +7,14 @@ use yew_router::prelude::*;
 enum Route {
     #[at("/")]
     Home,
+    #[at("/hello-server")]
+    HelloServer,
 }
 
 fn switch(routes: &Route) -> Html {
     match routes {
         Route::Home => html! { <h1>{ "Hello Frontend" }</h1> },
+        Route::HelloServer => html! { <HelloServer /> },
     }
 }

Now let’s test it! Start the server on port 8081 and the frontend in dev mode with a proxy for api requests:

cargo run --bin server -- --port 8081
cd frontend; trunk serve --proxy-backend=http://[::1]:8081/api/

When you open your web browser at localhost:8080/hello-server you should now see:

But what happens when we serve the app statically?

cd frontend; trunk build
cargo run --bin server
localhost:8080/hello-server

Oh no.

Making the file server support a SPA app

The reason for that is of course that the server tries to find the path /hello-server in the file system due to the fallback handler as no other server-side route matches it. The client-side routes require index.html to be loaded so that the JavaScript / WASM code can handle the request as we expect in a single-page application. In order to make it work we will need to have our fallback handler not give a 404 response when it cannot find a resource but return the index file:

diff --git a/server/src/main.rs b/server/src/main.rs
index 0000000..0000000 100644
@@ -3,7 +3,9 @@ use axum::http::{Response, StatusCode};
 use axum::{response::IntoResponse, routing::get, Router};
 use clap::Parser;
 use std::net::{IpAddr, Ipv6Addr, SocketAddr};
+use std::path::PathBuf;
 use std::str::FromStr;
+use tokio::fs;
 use tower::{ServiceBuilder, ServiceExt};
 use tower_http::services::ServeDir;
 use tower_http::trace::TraceLayer;
@@ -43,8 +45,28 @@ async fn main() {
     let app = Router::new()
         .route("/api/hello", get(hello))
         .fallback(get(|req| async move {
-            match ServeDir::new(opt.static_dir).oneshot(req).await {
-                Ok(res) => res.map(boxed),
+            match ServeDir::new(&opt.static_dir).oneshot(req).await {
+                Ok(res) => {
+                    let status = res.status();
+                    match status {
+                        StatusCode::NOT_FOUND => {
+                            let index_path = PathBuf::from(&opt.static_dir).join("index.html");
+                            let index_content = match fs::read_to_string(index_path).await {
+                                Err(_) => {
+                                    return Response::builder()
+                                        .status(StatusCode::NOT_FOUND)
+                                        .body(boxed(Body::from("index file not found")))
+                                        .unwrap()
+                                }
+                                Ok(index_content) => index_content,
+                            };
+    
+                            Response::builder()
+                                .status(StatusCode::OK)
+                                .body(boxed(Body::from(index_content)))
+                                .unwrap()
+                        }
+                        _ => res.map(boxed),
+                    }
+                }
                 Err(err) => Response::builder()
                     .status(StatusCode::INTERNAL_SERVER_ERROR)
                     .body(boxed(Body::from(format!("error: {err}"))))

Conveniently running it

For running the dev or static version I prefer putting the necessary cargo commands into scripts. dev.sh runs both Trunk and the server at the same time. The server is started using cargo-watch, a useful utility to detect file changes. In combination with trunk serve this will auto-reload both client and server!

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

(trap 'kill 0' SIGINT; \
 bash -c 'cd frontend; trunk serve --proxy-backend=http://[::1]:8081/api/' & \
 bash -c 'cargo watch -- cargo run --bin server -- --port 8081')

prod.sh will build the frontend and run the server:

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

pushd frontend
trunk build
popd

cargo run --bin server --release -- --port 8080 --static-dir ./dist

And this is it! A complete starter pack for a full Rust web app!

A note about a bug stripping symbols in wasm code

Please note that there is an open rust compiler bug when enabling stripping symbols that breaks wasm code.

As reported by @malaire, a setting like profile.release.strip = true will result in the example above not loading. For the time being, only strip = "debuginfo" is working.

A note on Trunk watch and serve

Should you observe that trunk serve is rebuilding your frontend project from scratch each time you save a file, this can be one of two things:

There is an open issue with the file watcher that won’t debounce file change events. Just recently (2022-04-13) a fix was merged that is currently only on Trunk master. Use cargo install trunk --git https://github.com/thedodd/trunk for installing the most recent version. (Update on 2023-01-09: This seems now to be in the Trunk release version as well.)

On Linux even this did not fix the behavior for me. I needed to specify I separate cargo target dir to untangle rust-analyzer from trunks build directory: Using bash -c 'cd frontend; CARGO_TARGET_DIR=target-trunk trunk serve' in dev.sh fixed that.

What to deploy

If you want to deploy just the server and dist repo to some machine, you will only need to build the frontend and the server binary (cd server; cargo build --release), take server/target/release/server and dist/ and put it into the same directory. If you then start the server with --static-dir ./dist it will run as well.

Configuring Emacs for Rust development

robert@kra.hn (Robert Krahn) — Sun, 07 Feb 2021 00:00:00 +0000

Rust support in Emacs improved a lot during the past two years. This post will walk you through setting up Emacs to allow for:

Navigating the source code (go to to implementation, list references, outline module structure)
Code completion
Code snippets
Highlighting errors and warnings inline
Apply code fixes and refactorings
Automatically import definitions if necessary (such as for Traits)
Code formatting with rustfmt
Building & running other cargo commands

This setup will be based on rust-analyzer, a LSP server that is under very active development and powers the Rust support in VS Code as well.

This post is accompanied by a github repository that you can use as a reference or directly checkout and run Emacs with (see below). I’ve tested the configuration with Emacs 28.2, rust stable 1.66.0 and on macOS 13.1, Ubuntu 22.04 and Windows 10.

For a setup that uses the emacs-racer backend¹ please see David Crook’s guide.

Changelog

Changes made to this guide:

2023-07-23: lsp-rust-analyzer-server-display-inlay-hints was removed, use lsp-inlay-hint-enable instead (thank you Wojciech!)
2023-02-22: Inlay hints work well again (https://github.com/emacs-lsp/lsp-mode/issues/3896)
2023-01-10: Currently inlay hints on rust-analyzer versions newer than 2022-12-19 won’t work
2022-09-13: Use lsp-format-buffer instead of rustic-format-on-save
2022-06-19: Note about potential LSP :: rust-analyzer failed to discover workspace error (thanks Fred Xia!)
2022-03-26: Clarified that rustic derives from rust-mode
2022-03-24: Inlay hints fixed & more inlay hints available
2022-03-14: Note about broken lsp-lens-mode / inlay hints
2021-11-28: Note about rust-playground
2021-11-15: rust-analyzer installation / compatibility note
2021-06-17: fix for buffer-save-without-query
2021-03-06: add lsp-rust-analyzer-server-display-inlay-hints
2021-02-08: Add dap debugging setup

Quickstart

If you have already Rust and Emacs installed (see prerequisites) you can get quickly up and running without modifying any of your existing configuration. The rksm/emacs-rust-config github repo contains a standalone.el file that you can use to start Emacs with:

$ git clone https://github.com/rksm/emacs-rust-config
$ emacs -q --load ./emacs-rust-config/standalone.el

This will start Emacs with an .emacs.d directory set to the location of the checked out repository (and a different elpa directory). This means, it will not use or modify your $HOME/.emacs.d. If you are unsure if you are happy with what is described here, this is an easy way to figure it out.

All dependencies will be installed on first startup, this means the first start will take a few seconds.

On windows you can use a shortcut to start Emacs with those parameters. If you are on macOS and have installed the Emacs.app you will need to start Emacs from the command line with:

/Applications//Emacs.app/Contents/MacOS/Emacs -q --load ./emacs-rust-config/standalone.el

Prerequisites

Before we get to the actual Emacs configuration, please make sure your system is setup with the following.

Rust

Install the rust toolchain with cargo. rustup makes that easy. Install rust stable and make sure that the .cargo/bin directory is in your PATH. rustup will do this by default. rust-analyzer will also need the Rust source code and you can install that with rustup component add rust-src.

rust-analyzer

You need the rust-analyzer server binary. You can install it following the rust analyzer manual, pre-compiled binaries are available. However, since rust-analyzer is so actively developed I usually just clone the github repository and build the binary myself. This makes upgrading (and downgrading should it be necessary) very straightforward.

$ git clone https://github.com/rust-analyzer/rust-analyzer.git -b release
$ cd rust-analyzer
$ cargo xtask install --server # will install rust-analyzer into $HOME/.cargo/bin

I’ve heard that (very) occasionally the most recent version might not work. In that case I can recommend to take a look at the rust-analyzer changelog which contains links to a git commit for each weeks update. In case you run into trouble, build from an earlier version, which will likely succeed.

Please also make sure that your emacs packages are up-to-date, in particular lsp-mode and rustic-mode to ensure that the newest rust-analyzer features are supported.

If you need to run with an older version of rust-analyzer you can look for an older release tag with git tag and then build against it like:

git checkout 2022-12-19
cargo xtask install --server

This should work with older versions of the relevant emacs packages as well.

Emacs

I have tested the setup with Emacs 28.2. On macOS I normally use emacsformacosx.com. On Windows I use the “nearby GNU mirror” link at gnu.org/software/emacs. On Ubuntu adding another apt repository is necessary. Note that the config will likely work with older Emacs versions but Emacs 27 got substantial improvements around JSON parsing which speeds up LSP clients quite a bit.

Note that I use use-package for Emacs package management. It will be auto-installed in the standalone version of this config. Otherwise you can add a snippet like below to your init.el:

(unless (package-installed-p 'use-package)
  (package-refresh-contents)
  (package-install 'use-package))

Rust Emacs Configuration in Detail

The essential modes being used are the following:

rustic
lsp-mode
company
yasnippet
flycheck

Rustic

rustic is an extension of rust-mode which adds a number of useful features (see the its github readme) to it. It is the core of the setup and you can use just it without any other Emacs packages (and without rust-analyzer) if you just want code highlighting, compilation and cargo commands bound to emacs shortcuts, and a few other features.

(use-package rustic
  :ensure
  :bind (:map rustic-mode-map
              ("M-j" . lsp-ui-imenu)
              ("M-?" . lsp-find-references)
              ("C-c C-c l" . flycheck-list-errors)
              ("C-c C-c a" . lsp-execute-code-action)
              ("C-c C-c r" . lsp-rename)
              ("C-c C-c q" . lsp-workspace-restart)
              ("C-c C-c Q" . lsp-workspace-shutdown)
              ("C-c C-c s" . lsp-rust-analyzer-status))
  :config
  ;; uncomment for less flashiness
  ;; (setq lsp-eldoc-hook nil)
  ;; (setq lsp-enable-symbol-highlighting nil)
  ;; (setq lsp-signature-auto-activate nil)

  ;; comment to disable rustfmt on save
  (setq rustic-format-on-save t)
  (add-hook 'rustic-mode-hook 'rk/rustic-mode-hook))

(defun rk/rustic-mode-hook ()
  ;; so that run C-c C-c C-r works without having to confirm, but don't try to
  ;; save rust buffers that are not file visiting. Once
  ;; https://github.com/brotzeit/rustic/issues/253 has been resolved this should
  ;; no longer be necessary.
  (when buffer-file-name
    (setq-local buffer-save-without-query t))
  (add-hook 'before-save-hook 'lsp-format-buffer nil t))

Most of rustics features are bound to the C-c C-c prefix (that is press Control-c twice and then another key):

You can use C-c C-c C-r to run the program via cargo run. You will be asked for parameters and can for example specify --release to run in release mode or --bin other-bin to run the target named “other-bin” (instead of main.rs). To pass parameters to the executable itself use -- --arg1 --arg2.

The shortcut C-c C-c C-c will run the test at point. Very handy to run inline tests and to not always have switch back-and-forth between a terminal and Emacs.

C-c C-p opens a popup buffer that will give you similar access to the commands shown above but will stick around.

Rustic provides even more helpful integration with cargo, e.g. M-x rustic-cargo-add will allow you to add dependencies to your projects Cargo.toml (via cargo-edit that will be installed on demand).

If you would like to share a code snippet with others, M-x rustic-playpen will open your current buffer in https://play.rust-lang.org where you can run the Rust code online and get a shareable link.

Code formatting on save is enabled and will use rustfmt. To disable it set (setq rustic-format-on-save nil). You can still format a buffer on demand using C-c C-c C-o.

lsp-mode and lsp-ui-mode

lsp-mode provides the integration with rust-analyzer. It enables the IDE features such as navigating through source code, highlighting errors via flycheck (see below) and provides the auto-completion source for company (also below).

(use-package lsp-mode
  :ensure
  :commands lsp
  :custom
  ;; what to use when checking on-save. "check" is default, I prefer clippy
  (lsp-rust-analyzer-cargo-watch-command "clippy")
  (lsp-eldoc-render-all t)
  (lsp-idle-delay 0.6)
  ;; enable / disable the hints as you prefer:
  (lsp-inlay-hint-enable t)
  ;; These are optional configurations. See https://emacs-lsp.github.io/lsp-mode/page/lsp-rust-analyzer/#lsp-rust-analyzer-display-chaining-hints for a full list
  (lsp-rust-analyzer-display-lifetime-elision-hints-enable "skip_trivial")
  (lsp-rust-analyzer-display-chaining-hints t)
  (lsp-rust-analyzer-display-lifetime-elision-hints-use-parameter-names nil)
  (lsp-rust-analyzer-display-closure-return-type-hints t)
  (lsp-rust-analyzer-display-parameter-hints nil)
  (lsp-rust-analyzer-display-reborrow-hints nil)
  :config
  (add-hook 'lsp-mode-hook 'lsp-ui-mode))

(use-package lsp-ui
  :ensure
  :commands lsp-ui-mode
  :custom
  (lsp-ui-peek-always-show t)
  (lsp-ui-sideline-show-hover t)
  (lsp-ui-doc-enable nil))

lsp-ui is optional. It provides inline overlays over the symbol at point and enables code fixes at point. If you find it to flashy and prefer not activating it just remove :config (add-hook 'lsp-mode-hook 'lsp-ui-mode).

The config shown above already disables the documentation normally shown inline by lsp-ui. This is too much for my taste as it often covers up source code. If you want to also deactivate the documentation shown in the minibuffer you can add (setq lsp-eldoc-hook nil). To do less when your cursor moves consider (setq lsp-signature-auto-activate nil) and (setq lsp-enable-symbol-highlighting nil).

lsp-mode will try to figure out the project directory that rust-analyzer should use to index the project. When you first open a file inside a new project, you will be asked which directory to import:

The first selection (press i) will use the directory in which a Cargo.toml file was found, potentially the workspace root if the crate you work on is inside a workspace. The second selection (I) will allow you to select the root project directory manually. The last selection (n) will prevent lsp from starting. Sometimes when you follow a reference to a library crate it can be useful to not enable lsp for it as the lsp startup and indexing well take some time for large code bases.

lsp-mode remembers the choice for the project directory so the next time you open a file of a known project you do not need to make that selection again. If you ever want that, you can invoke the lsp-workspace-folders-remove command to interactively remove directories from the list of known projects.

Should you ever see an error such as LSP :: rust-analyzer failed to discover workspace when trying to open a .rs file, try invoking the lsp-workspace-folders-add manually and add the root project directory.

Having setup lsp-mode, you can use M-. to jump to the definition of function, structs, packages etc. when your cursor is over a symbol. M-, to jump back. With M-? you can list all references of a symbol. A little demo:

With M-j you can open up an outline of the current module that allows you to quickly navigate between functions and other definitions.

Code actions

Refactorings are possible using M-x lsp-rename and lsp-execute-code-action. Code actions are basically code transformation and fixes. For example the linter may find a way to express code more idiomatically:

The number of available code actions continuously growth. A full list is available in the rust-analyzer documentation. Favorites include automatically importing functions or fully qualifying symbols. E.g. in a module that does not yet use HashMap, type HashMap and then select the option to Import std::collections::HashMap. Other code actions allow you to add all possible arms in a match expression or converting a #[derive(Trait)] into the code needed for a custom implementation. And many, many more.

If you developing macros, quickly seeing how they expand can be really useful. Use M-x lsp-rust-analyzer-expand-macro or the shortcut C-c C-c e to macroexpand.

Code completion and snippets

lsp-mode directly integrates with company-mode, a completion framework for emacs. It will display a list of possible symbols that could be inserted at the cursor. It is very helpful when working with unknown libraries (or the std lib) and reduces the need for looking up documentation. Rust’s type system is used as a source for the completions and thus what you can insert makes (mostly) sense.

By default the code completion popup will appear after company-idle-delay which is set to 0.5 seconds by default. You can modify that value or disable the auto popup completely by setting company-begin-commands to nil.

(use-package company
  :ensure
  :custom
  (company-idle-delay 0.5) ;; how long to wait until popup
  ;; (company-begin-commands nil) ;; uncomment to disable popup
  :bind
  (:map company-active-map
	      ("C-n". company-select-next)
	      ("C-p". company-select-previous)
	      ("M-<". company-select-first)
	      ("M->". company-select-last)))

(use-package yasnippet
  :ensure
  :config
  (yas-reload-all)
  (add-hook 'prog-mode-hook 'yas-minor-mode)
  (add-hook 'text-mode-hook 'yas-minor-mode))

This will also enable code snippets via yasnippet. I have added the list of my most commonly used snippets to the github repository. Feel free to copy and modify them. They work by typing a certain character sequence and then pressing TAB. For example for<TAB> will expand into a for loop. You can customize what is being pre-filled and the number of stops while expanding and even run custom elisp code. See the yasnippet documentation.

To enable snippet expansion, code completion and indentation when you press the TAB key, we need to customize the command that is running when pressing TAB:

(use-package company
  ;; ... see above ...
  (:map company-mode-map
	("<tab>". tab-indent-or-complete)
	("TAB". tab-indent-or-complete)))

(defun company-yasnippet-or-completion ()
  (interactive)
  (or (do-yas-expand)
      (company-complete-common)))

(defun check-expansion ()
  (save-excursion
    (if (looking-at "\\_>") t
      (backward-char 1)
      (if (looking-at "\\.") t
        (backward-char 1)
        (if (looking-at "::") t nil)))))

(defun do-yas-expand ()
  (let ((yas/fallback-behavior 'return-nil))
    (yas/expand)))

(defun tab-indent-or-complete ()
  (interactive)
  (if (minibufferp)
      (minibuffer-complete)
    (if (or (not yas/minor-mode)
            (null (do-yas-expand)))
        (if (check-expansion)
            (company-complete-common)
          (indent-for-tab-command)))))

My most commonly used snippets are for, log, ifl, match and fn.

Inline errors

That one is easy, rustic does the heavy lifting. We just need to make sure flycheck is being loaded:

(use-package flycheck :ensure)

You can display a list of errors and warnings using M-x flycheck-list-errors or by pressing C-c C-c l.

Inline type hints

Rust-analyzer and lsp-mode are able to show inline type annotations. Normally, those would appear via eldoc when placing the cursor over the defined variable, with the annotations you will always see the inferred types. Use (setq lsp-inlay-hint-enable t) to enable them². To actually insert an inferred type into the source code you can move your cursor over the defined variable and run M-x lsp-execute-code-action or C-c C-c a.

Note that they might not interact well with lsp-ui-sideline-mode. If you prefer the hints but want to disable sideline mode, you can add (lsp-ui-sideline-enable nil) to a rustic-mode-hook.

As of the rust-analyzer and lsp-mode versions of 2022-03-24 there are even more kinds of inline hints available which now include lifetime hints, intermediate types in method chains and more!

Debugging

Emacs integrates with gdb and lldb via the dap-mode package³. In order to setup debugging support for Rust, you will need to do some additional setup and build steps. In particular, you will need to have lldb-mi which is not part of the official llvm distribution that Apple provides via XCode.

I only tested building lldb-mi on macOS. Here is how I got it working:

Install llvm and cmake via homebrew
Checkout the lldb-mi repo
Build the lldb-mi binary
Link to a location in my PATH

$ brew install cmake llvm
$ git clone https://github.com/lldb-tools/lldb-mi
$ mkdir -p lldb-mi/build
$ cd lldb-mi/build
$ cmake ..
$ cmake --build .
$ ln -s $PWD/src/lldb-mi /usr/local/bin/lldb-mi

In order to have Emacs find that executable you will need to make sure exec-path is setup correctly at startup. The full dap-mode config looks like this:

(use-package exec-path-from-shell
  :ensure
  :init (exec-path-from-shell-initialize))

(use-package dap-mode
  :ensure
  :config
  (dap-ui-mode)
  (dap-ui-controls-mode 1)

  (require 'dap-lldb)
  (require 'dap-gdb-lldb)
  ;; installs .extension/vscode
  (dap-gdb-lldb-setup)
  (dap-register-debug-template
   "Rust::LLDB Run Configuration"
   (list :type "lldb"
         :request "launch"
         :name "LLDB::Run"
	 :gdbpath "rust-lldb"
         :target nil
         :cwd nil)))

(dap-gdb-lldb-setup) will install a VS Code extension into user-emacs-dir/.extension/vscode/webfreak.debug. One problem I observed was that this installation is not always successful. Should you end up without a “webfreak.debug” directory you might need to delete the vscode/ folder and run (dap-gdb-lldb-setup) again.

I also needed to run sudo DevToolsSecurity --enable once to allow the debugger access to processes.

Additionally I ran into another issue. When starting the debug target I would see:

Even though lldb-mi was on my path and I could start it from within Emacs. It turns out that the error does not come from lldb-mi but from the path to the target you start with. When you start debugging with M-x dap-debug or via dap-hydra d d, after you select Rust::LLDB Run Configuration make sure that the path to the target executable you want to debug is not a relative path and does not containt ~. If it’s an absolute path it should work.

Example that would fail with above error (note the unexpanded ~/):

I needed to specify the full path /Users/robert/projects/rust/emacs/test-project/target/debug/test-project.

Once it is working it should look like that:

In that example I first activate dab-hydra with C-c C-c d. I then select a Rust debug target (that I build using cargo before) with d d. Before I already set a breakpoint with b p. I then step through and into the code with n and i. Note that you can also use the mouse to set breakpoints and step.

Setting up debugging is still not as smooth as it could be but once it is running it is a joy!

Rust playground

You probably have seen the online Rust playground https://play.rust-lang.org/ that quickly allows you to run and share snippets of Rust code. A somewhat similar project for Emacs is grafov/rust-playground which allows you to quickly create (and remove) Rust scratch projects. By default, the rust-playground command will create Rust project directories at ~/.emacs.d/rust-playground/ and open up main.rs with keybindings to quickly run the project (C-c C-c). This is very handy if you want to quicky test a Rust code snippet or tryout a library. All from the comfort of your own editor!

Additional packages

I will not cover it here but there are a number of other emacs packages that will improve the Emacs developing experience for Rust and other languages vastly. Just some pointers:

projectile: Adds the notion of projects to emacs and a large number of commands that operate on them. E.g. open shell in project, search code in project etc.
helm, selectrum or ivy: We spend a lot of time selecting one or multiple choices from lists. Be it to open files, switch between buffers or run commands (M-x). All of these packages make it easier to select options via keyboard input in emacs and allow to filter large lists. helm is my personal daily driver but selectrum is a good alternative and more light-weight. It is used in the standalone.el version of the associated gitub project.
shackle: The default emacs window behavior is… not optimal. Shackle allows to define rules matching buffer names. My default rules are in this gist.
dired Built-in to Emacs. The last file manager you will need.

Thanks to all the package maintainers!

Last but not least a big Thank You! to all the people developing and maintaining the open source software referenced here. The rust-analyzer project is amazing and has improved the state of Rust Emacs tooling considerably. That of course would not be half as useful without lsp-mode and lsp-ui. rustic simplifies a lot of the otherwise necessary configuration around rust-mode and adds very helpful features. Company and flycheck are my defaults for other language modes anyway. And of course also thanks to all the Emacs maintainers and everyone I forgot who had a hand in all this!

Racer used to be the best option for getting IDE features (code navigation etc) into Emacs. It is a non-LSP solution which is still faster than RLS and rust-analyzer. However, the number of features especially around code completion are not up to par with rust-analyzer anymore. ↩︎
Setting lsp-inlay-hint-enable globally to t will also enable inlay hints in other language modes. If you don’t want that, insert (setq-local lsp-inlay-hint-enable t) into rk/rustic-mode-hook instead. ↩︎
Emacs has also built-in support for gdb via GUD but needs to control the gdb process directly. DAP is more similar to LSP in that it is used to control a debugging process remotely and makes it easier for editors to integrate with. ↩︎

Is Rust a Functional Programming Language?

robert@kra.hn (Robert Krahn) — Wed, 03 Feb 2021 00:00:00 +0000

Update: There was a delightful discussion about functional programming and the nature of Rust at lobste.rs.

Some quotes...

Functional languages take away mutability from the “mutability + aliasing = bugs” equation; Rust takes away the aliasing — or at least, the uncontrolled aliasing. To me, it then makes sense to feel comfortable using mutability (and the advantages it offers), safe in the knowledge that the compiler is helping you avoid bugs. [vfoley]

I guess I don’t really agree with all of this. I agree that Rust gets the nice properties of functional languages at least when it comes to mutation, but if someone read the body of Rust code I have written and came back and said, “it really resembles the code I typically write on Lisp/ML/Haskell,” then I would be really surprised. I rarely write higher order functions. I rarely write recursive functions or folds. I rarely use persistent data structures and instead use mutation without reservation. [burntsushi]

andyc pointed to Notes on a smaller Rust and quoted:

As I said once, pure functional programming is an ingenious trick to show you can code without mutation, but Rust is an even cleverer trick to show you can just have mutation.

expand

The book Programming Rust introduces Rust as...

not really an object-oriented language, although it has some object-oriented characteristics. Rust is not a functional language […] It’s probably best to reserve judgement about what sort of language Rust is, and see what you think once you’ve become comfortable with the language.

Time for judgement has come! In the following I will lay out my view on how Rust’s language features influence programming style. I do agree with the aforementioned quote that Rust is not a single-paradigm language. Yet, the code written in idiomatic and safe Rust shares quite some similarities with code of functional programming languages.

“Functional programming language” is not a clearly defined term. From the various properties that are typically associated with functional programming I only want to focus on one: “Immutability” and referential transparency. Immutability means that data structures can be treated as values - once you have them, they will not change underneath you. If you want to express modification, you can construct a new data structure, maybe reusing (unchanged) parts of existing data. This enables referential transparency: If a function (or method) cannot change anything internally, its output only depends on its input. Given some input the function evaluation and the result it returns can be treated as the same. The function is said to be pure.

Immutability is often regarded as a very positive property:

Pure code is deterministic and considered to be easier to reason about as the number of possible state combinations is limited.
If a function only depends on explicitly defined parameters, testing it is often easier.
Immutable data can be passed to concurrent code without worrying about synchron^izing access.
And it is free of cycles (unless you allow lazily evaluation), making it easier to serialize and deserialize.

Now Rust clearly allows for data to be mutable. Rust also does not provide persistent data structures in its standard library (although there are third-party options) which are typically used to model immutable data efficiently. Yet, Rust’s rules around ownership require full control over what can be changed and when. To the extent that I have been working with Rust, a lot of it feels quite similar to programming Clojure from the point of view of designing programs.

Each piece of data in (safe) Rust has exactly one owner. In the following example the variable val owns the String:

let val = "Hello World".to_string();

Using val we can create references to the string:

let val_ref = &val;
// both val and val_ref can be used to read the string value:
println!("{}", val);
println!("{}", val_ref);

However we cannot modify either val or val_ref:

// cannot borrow `val` as mutable, as it is not declared as mutable
val.push_str(" World");

// error: "cannot borrow `*val_ref` as mutable, as it is behind a `&` reference"
val_ref.push_str(" World");

So in order to change val we need to declare it mut:

let mut val = "Hello".to_string();
val.push_str(" World"); // OK

But now we cannot take a reference at the same time anymore:

let mut val = "Hello".to_string();
// error: cannot borrow `val` as mutable because it is also borrowed as immutable
let val_ref = &val;
val.push_str(" World");

And similarly we can write to the reference if we declare it mut but then we cannot get another reference at the same time:

let mut val = "Hello".to_string();
let val_ref = &val;
// error: cannot borrow `val` as mutable because it is also borrowed as immutable
let val_ref2 = &mut val;

This example demonstrates Rust’s ownership rules: We can get multiple shared (read-only) references to one piece of data but as soon as we indicate to modify the data by declaring either the owning variable or a reference as mut we cannot hold shared references at the same time. mut means first and foremost exclusive access to the underlying data (and only secondarily mutable).

Similarly, functions that want to modify parameters (or self in case of methods) need to indicate that they need exclusive access. This means that the caller can only use this function it has exclusive access to the parameters to be passed as mut:

fn add_world(val_ref: &mut String) {
    val_ref.push_str(" World");
}
// ...
add_world(&mut val);

All this is to say: Mutability in Rust needs to be explicitly declared and the rules around exclusive access are statically enforced. A thing can only change if no one is looking — reducing the number of accidental state combinations and highlighting the parts of the code base that can introduce change clearly. A Rust function that only accepts shared references and owned values (that do not provide interior mutability) and that does not use unsafe code¹, is referentially transparent.

Interior mutability

There are a number of use cases where not being able to modify shared references can become very limiting. For example consider this GTK+3 app:

The implementation for this looks something like this:

let container = gtk::Box::new(gtk::Orientation::Vertical, 2);
// A label that will be modified
let label = gtk::Label::new(Some("Button not yet clicked"));
let button = gtk::Button::with_label("Click me");
// We clone label so we can send it into the closure.
let label_clone = label.clone();
button.connect_clicked(move |_| {
    label_clone.set_label("Button has been clicked!");
});
container.add(&button);
container.add(&label);

As you can see the label is added to the container so that it gets displayed and is bound inside the closure where it gets modified.

Rust uses two mechanisms in combination for that to work: The Rc<RefCell<T>> pattern². First, a reference counted pointer std::rc::Rc that is quite similar to C++’s shared_ptr. Rc takes ownership of another object. Rc implements Clone that will increase the ref count and hand out a new pointer. Those can be passed freely around. Inside of the ref-counted pointer a RefCell can be placed. It will allow to request exclusive access to the data owned. I.e. it will — at runtime! — produce a mut reference to the object wrapped and check that it is indeed not borrowed somewhere else. Should this not be the case, the borrow will fail (and possibly panic if borrow_mut() was used).

For more details about the internals of smart pointers and interior mutability I can highly highly recommend this screen cast by Jon Gjengset that walks you through possible implementations of (among others) Rc and RefCell.

So Rust provides ways³ around the statically enforced access rules that normally restrict modification of data. This provides enough abstractions to even implement an interface to an object-oriented system such as Glib / GTK+. Following that, you might argue that Rust is supporting multiple paradigms, and I will agree. Yet, similar to Clojure that provides “interior mutability”-equivalents like atoms I will point out that overly relying on those features is not considered idiomatic. In Clojure the best practice is to use atoms sparingly. Mostly at the outside of the app, extracting state that is passed into the inner layers of the app that will then transform the state immutably into a new derived version. Atoms then clearly highlight where state changes can be expected. In practice, this then provides a good compromise. In case of stateful bugs, you only have to have a limited amount of possible sources to check and possible combinations of state transitions are still limited to simplify reasoning.

The Rc<RefCell<T>> pattern is also not all that ergonomic. Yes, you can define type aliases like Glib does, Rust still makes it easier to not have nested, cyclic relationships between objects. To say it with book Programming Rust again (from the section “Taking Arms Against a Sea of Objects”):

When everything depends on everything else like this, it’s hard to test, evolve, or even think about any component in isolation. One fascinating thing about Rust is that the ownership model puts a speed bump on the highway to hell. […] It works unreasonably well: not only can Rust force you to understand why your program is thread-safe, it can even require some amount of high-level architectural design.

And this is exactly the point I would like to convey with this article and the reason why I’m personally so fascinated with Rust: The set of features it does (not) provide are forcefully guiding the design of systems you build. This is quite contrary to how a lot of programming languages that attempt to provide a high degree of flexibility work (looking at you, Scala).

And then this is my claim: The ownership model, standard library, emphasize on iterators, and numerous other things do lead to code that is usually most idiomatic when written in a functional style. It will unlikely be completely equivalent to a solution written in Haskell or Clojure. Of course it also depends on the programmer, the problem domain, libraries, and frameworks. But applying best practices and designs from the functional realm are effective in Rust and the positive properties listed above can be built into Rust programs, and, to a degree, are even statically enforced by the compiler. For me, that is a joy!

Unsafe code is marked very visibly by unsafe blocks or function signatures and best practice around it is to require a thorough explanation as to why this code is safe and what the contract around it is. Unsafe code can cast *const into *mut pointers and can thus potentially modify shared references. ↩︎
For the GTK+ example this is only partially true. GTK uses GLib bindings, a wrapper around the C library. GLib implements its own object-oriented abstractions via GObject. The label and other objects from the example are instances of the GObject representation that the glib Rust wrapper provides. It implements the functionality of Rc / RefCell internally but does not use Rust’s stdlib implementation for that. ↩︎
Rc<RefCell<T>> is only for single threaded, Rust statically enforces that you cannot pass it across thread boundaries. Arc<Mutex> is the thread-safe equivalent. ↩︎

Building and deploying Rust utilities

robert@kra.hn (Robert Krahn) — Mon, 01 Feb 2021 00:00:00 +0000

Over the past year I build a number of tools and utilities in Rust. Previously, I would mostly do this in node.js or shell scripts but Rust has some advantages:

More reliable for long running and mostly unobserved applications (“once it runs is runs”), in particular no memory (leak) issues
Needs less resources, upping the utility value of my various Raspberry Pis
Setup and deployment are simple mostly due to the cargo package management and build tool

The last point I’ll describe in more detail. In particular, the project setup around file / directory organization, package tooling and cross-compilation. Rust has comparatively strict (but in my opinion well designed) best practices and “opinionated” defaults. Most of them come simply with the tools you use: cargo run expects binaries to be defined in certain ways for example.

To make this a little more concrete I will use my last holiday project as an example. fritzctrl wraps the API of AVM Fritz devices¹ into a command line utility that allows to schedule turning on and off outlets and controlling thermostats. The code is open source and can be found in a github repository. This project is still quite small (~1000 loc), yet I took care to follow common guidelines when organizing the code base to allow the project to be easily maintained and grown in the future.

Project organization

Apart from github, the fritzctrl command line utility was also added to crates.io which allows installing it by running cargo install fritzctrl (this requires a local rust installation via rustup). This is all that is needed to get the utility installed - cargo will put it into it’s binary location (~/.cargo/bin/) that one can add to PATH. From that point on the utility is ready to use.

While building the tool I started to split up the user interface related code and the code that provides an interface (to the slightly obscure) Fritz API. The latter was published in a separate crate which allows other projects to directly interface with that. The recommended way of organizing a project into multiple crates and libraries / binaries is a cargo feature called workspaces.

Note that organizing a project into a workspace is not absolutely necessary to separate the code. You can easily define one or many binaries simply by putting .rs files into src/bin/. You can even use sub-directories if you want a binary to have sub-modules. But if your binary starts to have extra dependencies that are not required for the library, things get a bit more complicated. See this stackoverflow answer for more details.

Since workspaces are very well supported by cargo and related tooling, it’s advisable to go down that route if in doubt.

In case of my project the structure looks like this: The top-level Cargo.toml just points to the fritzapi and fritzctrl directories. fritzctrl/Cargo.toml references the lib via fritzapi = { path = "../fritzapi", version = "0.3" }. Note that there is also a version number, this will be used when the crate gets published and installed by other users via cargo. The path dependency is what gets when installing the crate locally.

├── Cargo.toml
├── Cargo.lock
├── fritzapi
│   ├── Cargo.toml
│   ├── README.md  <== generated using cargo readme
│   └── src
│       └── ...
└── fritzctrl
    ├── Cargo.toml
    ├── README.md  <== generated using cargo readme
    └── src
        └── ...

The project can be easily build an run from the workspace root directory. cargo run, cargo test, cargo doc etc. all work as expected.

Publishing to crates.io

If you have used a package management system like npm, crates.io will be quite familiar. You’ll first need to login to the crates.io website, which requires a github account. You then need to confirm your email address. Afterwards you can generate a token that when used on the command line with cargo login, allows you to publish and update crates. The cargo publish command can be run inside a project directory and will check and upload your project. However, I would recommend the cargo release plugin which automates some housekeeping tasks around publishing. It’ll bump versions (across all packages when run from a workspace root!), git tag and upload. It’s very handy, I like it a lot.

While we’re talking about cargo plugins: I can also recommend cargo readme which extracts rustdoc comments into markdown format that can be put directly into a README.md file. This will be automatically picked up by crates.io and will be what is visible on the project page such as crates.io/crates/fritzctrl. All of the content there was extracted from fritzctrl/src/main.rs with cd path/to/fritzctrl; cargo readme > README.md.

In order to publish a new version of both fritzctrl and fritzapi I would then commit all changes and switch to the workspace root directory of the project. There I’ll run cargo release --dry-run -vv --no-dev-version patch which provides a preview of the release commands that would be run.

If all looks good just run without the dry-run option and you should be done!

Cross-compiling

A big reason for me to choose rust is the ability to create stand-alone binaries that can simply be copied onto a server, into a docker container or onto a Raspberry Pi without much installation overhead in the deploy environment. Often, compiling on the target device itself is not desirable or possible. Raspberry Pi’s are very capable devices but compiling a lot of code will take ages.

The first step is to figure out what processor and instruction set you need to target. In the following I describe how to cross-compile for Raspberry Pi devices which use ARM processors with AVMv6 (Pi Zero, Pi 1) and ARVv7 (Pi 2 and later) instructions sets. To figure out the CPU / instruction set for linux devices, running cat /proc/cpuinfo or uname -a should give the necessary information. Running the latter on a Raspberry Pi 2 outputs:

Linux rpi-home 5.4.79-v7+ #1373 SMP Mon Nov 23 13:22:33 GMT 2020 armv7l GNU/Linux

In particular, for my project I want to deploy the fritzctl binary in order to run a fritzctrl schedule command to turn my outside lighting on and off at sunrise and sunset.

Raspberry Pi 2 and later

The first thing you need to do is to make sure the stdlib for the target architecture is installed. For the purpose of targeting a Raspberry Pi 2, the ARMv7 target will do as determined above. You can either use the gnu or musl variant, I used

rustup target add armv7-unknown-linux-musleabihf

Note the “hf” here which is normally what you want. It means that floating point operations will use the hardware support provided by the chip as noted in the musl-libc wiki.

This alone didn’t do as dependencies also required to be compiled native using gcc. The gcc of your host system (MacOS in my case) will not be able to output the right format and might even have an incompatible compiler / linker interface. So you’ll likely need to install a gcc toolchain as well. Over at lisa.musl.cc you can download armv7l-linux-musleabihf-cross.tgz which will contain gcc and linker binaries (the binaries from mac.musl.cc did not work for me for some reason). Direct link to the .tgz file.

Then, we’ll need to inform cargo to use a different linker. Create a file .cargo/config.toml and specify the linker, in my case the file looks like

[target.armv7-unknown-linux-musleabihf]
linker = "armv7l-linux-musleabihf-gcc"

Now the last step is to run cargo build using the ARM target and making sure that the different linker can be found:

PATH=/path/to/armv7l-linux-musleabihf-cross/bin:$PATH \
    cargo build --release --target=armv7-unknown-linux-musleabihf

When you run that on MacOS you’ll probably see a MacOS warning like:

You’ll need to open the MacOS Preferences > Security & Privacy and allow the binary to run.

If everything works you should end up with a binary in target/armv7-unknown-linux-musleabihf/release/. You should then be able to copy that binary directly onto the target machine and run it.

$ scp target/armv7-unknown-linux-musleabihf/release/fritzctl rpi:bin/fritzctl
$ ssh rpi
pi@rpi-home:~ $ ./bin/fritzctl
# ...

For other architectures you’ll need to install the appropriate targets such as x86_64-unknown-linux-musl for example. rustup makes this very straightforward. I have some build issues from time to time with crates that have native dependencies. However, more and more crates now run purely on Rust or provide features to use pure rust dependencies.

If you need an http client for example, the reqwest crate will allow to be build using rustls-tls instead of rust-native-tls which might make it easier to compile.

Raspberry Pi Zero W

The rpi0 (similar to the original Raspbarry Pi version 1) uses the ARMv6 instruction set. Running uname -a gives

Linux rpi0 4.19.66+ #1253 Thu Aug 15 11:37:30 BST 2019 armv6l GNU/Linux

This means the above instructions (for ARMv7) will not produce runnable binaries for it. To compile a compatible binary install the arm-unknown-linux-musleabihf rust target:

rustup target add arm-unknown-linux-musleabihf

Next you will need the right toolchain: arm-linux-musleabihf-cross worked for me. Unpack it and modify your projects .cargo/config.toml to read

[target.arm-unknown-linux-musleabihf]
linker = "arm-linux-musleabihf-gcc"

You should now be able to build a “hello-world” program (e.g. created with cargo new) using

PATH=/path/to/arm-linux-musleabihf-cross/bin:$PATH \
    cargo build --release --target=arm-unknown-linux-musleabihf

Try copying it to your Raspberry Pi 0 and run it:

scp ./target/arm-unknown-linux-musleabihf/release/hello-world pi@rpi0:
ssh rpi0 './hello-world'

(replace rpi0 with whatever hostname or ip address your rpi0 is reachable at)

Summary

Rust is fun to work with not just because the language is well designed but also the accompanying tooling is well thought out. Rust and in particular cargo come with a number of “opinionated” defaults such as how projects are organized that (at least if you agree with and follow them) make it quite straightforward to setup and deploy projects. I’ve never been a fan of strict rules around build systems, in the case of Rust I do, however. This might be because those guidelines come in a large part from the learnings of other such systems like node.js / npm and try to enshrine the best practices used there. Additionally, cargo and rustup are excellent and well documented tools (the cargo book is quite helpful). I look forward to build many more systems in the Rust ecosystem.

AVM is a Berlin-based company and mostly known for their routers. In my opinion they make excellent products (I’ve owned several routers and DECT devices so far) that are also fairly hackable. Recommended. ↩︎

Clojure Conj 2019

robert@kra.hn (Robert Krahn) — Fri, 29 Nov 2019 00:00:00 +0000

I just returned from last weeks Clojure/conj in Durham, NC. All the talks seem to be online now. Talks I really liked included Follow the Data, Sherlock Holmes, and Love Letter To Clojure. No big surprises or releases there but what was an overarching impression is that Clojure now really has become a very stable language and ecosystem. Not huge by any means but a fair amount of companies participated and among the conference attendees many more worked professionally with Clojure (and that does not even count in Clojure’s presence in Europe where it seems to find increasing adoption, e.g. at companies like Pitch).

From the companies present at the conj, most notable is properly Nubank which had a number of developers and multiple talks there. They are in the process of really scaling up their business with hundreds of developers in multiple locations, including Berlin.

Clojure’s continued relevance doesn’t seem to simply derive from a single “killer feature”, it’s a mix of properties that make the language useful in todays world. On the one hand it’s Clojure’s approach of being hosted on the JVM and web browsers that enable adoption fairly easily, allow it to run almost anywhere and that opens up a large number of available libraries. Then there are features that are not completely unique to Clojure but can’t really be found in other mainstream languages:

It’s dynamic workflow and the “repl-driven” development style that pretty much every Clojure development tool supports (and which is my personal favorite),
a small language core library that makes working with and transforming data easy by providing a sensible set of core data structure and operations and that focuses on state management and immutability,
various useful additions such as clojure.spec that address real world concerns

So all in all Clojure seems to be pretty healthy and I continue to enjoy working with it!

Org Analyzer

robert@kra.hn (Robert Krahn) — Tue, 13 Aug 2019 00:00:00 +0000

Here is the project link: github.com/rksm/clj-org-analyzer.

I started using Emacs org mode “for real” a little less than two years ago and have been tracking my work related activities ever since using org-clock-in. Since the end of 2017 this has generated quite a bit of data but I have found that actually digging into that is rather hard due to the limited reporting functionality in Emacs.

I do have a few concrete use cases in mind. For example, one of my biggest weaknesses is to reliably estimate the effort for software projects. To get at least a little better at this I want to try learning from the past. To make it easier to get an overview and “slice and dice” my time tracked activities I created org analyzer:

It turns out it is actually pretty fun to explore question such as “what was the biggest project last year”, “what are my core work hours”, “what thing that I thought took a long time was rather quickly done”, etc.

So, yeah, a fun little project that actually took way longer than I thought ;)

Developer Efficiency

robert@kra.hn (Robert Krahn) — Thu, 20 Jun 2019 00:00:00 +0000

Much has been written about the productivity of software developers. The term “10x programmer” has been used and abused. It can be traced back to the paper by Sackman et al. that first described the variations in ability of individuals to program and debug. Even though I’m not writing about individual differences here I’m mentioning this publication for another reason: It set out to compare how well people do when they should debug a problem and have or have not access to a computer: Online and offline debugging¹.

Now using pen and paper every once in a while can be really helpful to facilitate thinking (or to whiteboard with a colleague) but in general the computer itself can guide and support a human programmer in programming and debugging tasks very well. This functionality was either very new (and available to only few programmers) or non-existing in 1968 when the paper above was written. But a lot changed in the decade or so thereafter. Smalltalk and Lisp developers know all about that. And yet, it sometimes seems to me that the rest of the world hasn’t really caught on yet.

Fundamentally computer programs are extremely dynamic processes. Understanding them requires not only to know about the abstractions and their static structure and interdependencies but also how they work together, how control flows, what data and objects are used. Programming then means to nudge both the abstractions as well as their dynamic relationships towards achieving a particular goal, step by step.

Imagine building a web shop and adding the “add item to shopping cart” feature: There is some UI in which items to buy are listed. Clicking on one should modify the state of a users cart and be reflected in the UI as well. Even in this overly simplistic and contrived example we have a couple of static objects and dynamic interactions:

Items to buy
A user
A user’s cart
A user interface rendering all of the above
A user’s interactions (clicks) modifying some or all of the above

Now let’s consider what likely needs to happen:

The UI will likely provide some on-click handling so we need to add an handler that gets triggered when a click on an item occurs
The handler needs to get hold of the user or maybe a user’s cart
The user or the cart needs to expose a method like addItem
The addItem method needs to modify the cart state (maybe add the item as a reference to a list internally) and this needs to be reflected in the rendering logic of the cart, e.g. by rendering the list length as a number label somewhere.

So how could a task like this be done in a programming environment like Smalltalk?

We would start the app and then locate the on-click handler which might be a method or a block (an anonymous function). The first thing we do is to add a breakpoint to it (the statement self halt. in Smalltalk parlance). We then click on an item, a debugger window appears. We have now halted the execution in mid-stride and have access to the item, the click event. Let’s say the item has a reference to the user’s cart. We modify the handler code so that the addItem method gets called /right inside the debugger/, while having direct access (for inspection or code completion) to all the objects involved. Let’s assume the addItem method does not exist but we continue the execution anyway. The debugger will pop open again telling us that the item has no such method but also offering us to create it. We choose the latter action and end up in the debugger being able to fill the body of the addItem method similarly as before with access to all the objects involved.

Compare that to the typical edit-compile-run approach. Consider that the incremental changes map nicely to the “plan” we made before. In particular there was no need for multiple program restarts including getting to a program state we could use for testing the changes. Apart from not having to wait for compilation we were placed right into the control flow with /concrete/ access to all data and objects. This directness and immediacy lowers the abstraction level we have to deal with: Instead of thinking in (abstract) classes we have concrete objects at our fingertips, decreasing the cognitive load we have to deal with. David Buck described this much more beautifully in his post Swimming with the Fish.

Why am I writing about this? Because even though computers are able to guide us in this manner since at least 40 years, the state of the art of development tools has not caught up. Even more, this topic does not even seem to be on the radar of most people working on programming languages, tools and frameworks. If it does than often as reminiscent memories to the “good old days”.

I consider this to be an extremely important issue for a number of reasons. Two of the more important ones: I believe that the average efficiency of software developers working in the industry is only a fraction of what it could be. I find it at least reasonable to think that there could be huge potential cost savings with more efficient tooling.

Much more important than that, though: Dynamic, incremental, and explorative interaction with programs is just a stepping stone for creating computers that really are “bicycles for the mind” — personal assistants that facilitate thinking, learning, and simulating. But how can we build truly flexible assistants for everyone if we can’t even get the tooling for professional developers caught up to decades old insights?

The authors concluded that individual performance differences are too high to answer the original question. ↩︎

Robert Krahn

org-ai — Emacs as your personal AI assistant

Setting up Github Copilot in Emacs

Quickstart

Table of Contents

Changelog

Intro & Disclaimer

Copilot API & integration

Copilot Emacs packages

Setup & Customizations

Restricting when to show completions

Customizing keys

Copilot-specific

Tab key

Ctrl-g / cancel

Speeding up incremental Rust compilation with dylibs

TL;DR

Table of Contents

Changelog

Example with polars

Wrapping dependencies as dylibs

crate-type = [“dylib”]

polars-dynamic

polars-dynamic/Cargo.toml

polars-dynamic/src/lib.rs

Cargo.toml

Limitation: The diamond dependency problem

Switching between static and dynamic dependencies

Controlling --feature dynamic with an environment variable

Using it with hot-reloading

Hot Reloading Rust — for Fun and Faster Feedback Cycles

TL;DR

Table of Contents

Changelog

Where this idea comes from

“Hello World” example3

How it works

Caveats and Asterisks

Global state

dlopen/dlclose behavior

Function signatures

Supported platforms

How to use it then?

Use features to toggle hot reload support

If necessary, create indirections

How to use it with Bevy

Bevy app binary

Bevy systems

Hot-reload Template for cargo-generate

Comments and feedback

A Rust web server / frontend setup like it's 2022 (with axum and yew)

Table of Contents

Changelog

Tools required

Project structure

Server

Adding logging to the server

Frontend

Connecting frontend and server

Custom server requests and frontend routing

Making the file server support a SPA app

Conveniently running it

A note about a bug stripping symbols in wasm code

A note on Trunk watch and serve

What to deploy

Configuring Emacs for Rust development

Table of Contents

Changelog

Quickstart

Prerequisites

Rust

rust-analyzer

Emacs

Rust Emacs Configuration in Detail

Rustic

lsp-mode and lsp-ui-mode

Code navigation

Code actions

Code completion and snippets

Inline errors

`polars-dynamic/Cargo.toml`

`polars-dynamic/src/lib.rs`

`Cargo.toml`

Controlling `--feature dynamic` with an environment variable

“Hello World” example³