From cc7821dc41ef0badfde937efdd521709455ceec7 Mon Sep 17 00:00:00 2001
From: Alex Shelkovnykov <a@ashelkov.com>
Date: Mon, 27 Nov 2023 12:55:01 -0300
Subject: [PATCH] build, docs: restyle flake and add commands to docs

---
 DEVELOPERS.md  | 26 ++++++++++++++++++++++++++
 rust/flake.nix | 25 ++++++++++++++-----------
 2 files changed, 40 insertions(+), 11 deletions(-)

diff --git a/DEVELOPERS.md b/DEVELOPERS.md
index 7bca10d..dbbe1d1 100644
--- a/DEVELOPERS.md
+++ b/DEVELOPERS.md
@@ -12,6 +12,8 @@ in `rust/` or any subdirectory, and you will be dropped into a BASH shell with t
 
 ## Rust
 
+### Build
+
 To build Ares, start a nix development shell as above. Within the shell, in the `rust/ares` directory, you can run:
 
 ```bash
@@ -22,6 +24,30 @@ to build the Ares executable. This will place the built executable at `target/de
 
 Ares is made to run as an urbit "serf", meaning it is intended to be invoked by a "king" which sends it commands and performs side-effects specified by its output. We use the vere king. Special instructions for building the vere king to invoke Ares are forthcoming.
 
+### Test
+
+The command to run the Ares suite of unit tests is:
+
+```bash
+cargo test --verbose -- --test-threads=1
+```
+
+The tests must be run with `-- --test-threads=1` because Rust does not have any way to specify test setup / teardown functions, nor does it have any way to
+specify ordered test dependencies. Therefore, the only way to ensure that tests that share resources don't clobber each other **and** that tests setup / teardown in the right order is to force all unit tests to be single-threaded.
+
+### Style
+
+Ares uses the default Rust formatting and style. The CI jobs are configured to reject any code which produces linter or style warnings. Therefore, as a final step before uploading code changes to GitHub, it's recommended to run the following commands:
+
+```bash
+cargo fmt
+cargo clippy --all-targets --no-deps -- -D warnings -A clippy::missing_safety_doc
+```
+
+This will auto-format your code and check for linter warnings.
+
+### Watch
+
 To watch rust and check for errors, run
 
 ```bash
diff --git a/rust/flake.nix b/rust/flake.nix
index eb4db34..a95d192 100644
--- a/rust/flake.nix
+++ b/rust/flake.nix
@@ -1,20 +1,25 @@
 {
   inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    nixpkgs.url = "nixpkgs/nixos-unstable";
     fenix = {
       url = "github:nix-community/fenix";
       inputs.nixpkgs.follows = "nixpkgs";
     };
-    flake-utils.url = "github:numtide/flake-utils";
+    flake-utils.url = "flake-utils";
   };
 
   outputs = {self, fenix, flake-utils, nixpkgs}:
-    let supportedSystems = ["x86_64-linux" "x86_64-darwin" "aarch64-darwin"];
-    in flake-utils.lib.eachSystem supportedSystems
-    (system:
-      let pkgs = import nixpkgs { inherit system; overlays = [(import ./nix/overlay.nix)]; };
-          parsedSystem = pkgs.lib.systems.parse.mkSystemFromString system;
-      in { devShells.default = pkgs.mkShell {
+    let
+      supportedSystems = ["x86_64-linux" "x86_64-darwin" "aarch64-darwin"];
+    in flake-utils.lib.eachSystem supportedSystems (system:
+      let
+        pkgs = import nixpkgs {
+          inherit system;
+          overlays = [(import ./nix/overlay.nix)];
+        };
+        parsedSystem = pkgs.lib.systems.parse.mkSystemFromString system;
+      in {
+        devShells.default = pkgs.mkShell {
           LIBCLANG_PATH = "${pkgs.llvmPackages.libclang.lib}/lib";
           buildInputs = [
             (fenix.packages.${system}.complete.withComponents [
@@ -24,14 +29,12 @@
               "rustfmt"
               "rust-src"
             ])
-            pkgs.autoconf-archive
             pkgs.cargo-watch
             pkgs.iconv
-            pkgs.pkg-config
             pkgs.urcrypt
             pkgs.llvmPackages.clang
           ] ++
-          (nixpkgs.lib.lists.optional (parsedSystem.kernel.name != "darwin") pkgs.gdb); # nixpkgs won't build gdb for darwin
+            (nixpkgs.lib.lists.optional (parsedSystem.kernel.name != "darwin") pkgs.gdb); # nixpkgs won't build gdb for darwin
         };
       }
     );