misc: Document and automate development environment setup (#176)

Adds `DEVELOPMENT.md` with local PC development environment setup
instructions.

Adds a `justfile` with (incomplete set of) commands for various relevant
activities.

Rewires the brains of the spell check logic so we do not need to babysit
the dictionary - you can simply yolo it and `just spellcheck` will
preprocess the dictionary before giving it to the nitpicky
`cargo-spellcheck` utility. We are now required to use `just spellcheck`
instead of `cargo spellcheck`.

Adds execution of all standalone examples into the `testing` check in
the GitHub workflows.

Fixes #173, #174

Justfile commands:

```text
    build PROFILE='dev'
    careful FILTER=""         # Run unit and integration tests with extra standard libbrary debug assertions enabled.
    check PROFILE='dev'
    clippy PROFILE='dev'
    coverage-measure
    coverage-report
    deny
    docs
    examples PROFILE='dev'    # Run all stand-alone example binaries to ensure they complete with exit code 0.
    format
    format-check
    hack
    install-tools             # Installs the complete set of Rust toolchains and other tools for local PC development.
    miri FILTER=""            # Run unit and integration tests under Miri.
    miri-example EXAMPLE_NAME # Run an example binary under Miri.
    readme                    # Update README.md files for all packges.
    readme-check              # Check that README.md files for all packges are up to date.
    spellcheck                # Check the spelling of the workspace contents.
    test FILTER=""            # Runs unit and integration tests.
    test-docs FILTER=""       # Runs inline examples in documentation comments (doctests).
    test-more FILTER=""       # Same as 'test' but also run one iteration of benchmarks.
    udeps                     # Detect unused dependencies.
```

---------

Co-authored-by: martintmk <103487740+martintmk@users.noreply.github.com>
Co-authored-by: martintomka <martintomka@microsoft.com>

Author: sandersaares

.github/actions/setup/action.yml

@@ -10,7 +10,7 @@ inputs:
     required: false
     default: 'false'
   rust-toolchain:
-    description: Rust toolchain to install. Can be a version (e.g., "stable", "1.70"), multiple (e.g., "stable,nightly"), or environment variable names from constants.toml (e.g., "RUST_MSRV" or "RUST_LATEST,RUST_NIGHTLY"). Leave empty to skip Rust installation.
+    description: Rust toolchain to install. Can be a version (e.g., "stable", "1.70"), multiple (e.g., "stable,nightly"), or environment variable names from constants.env (e.g., "RUST_MSRV" or "RUST_LATEST,RUST_NIGHTLY"). Leave empty to skip Rust installation.
     required: false
     default: ''
   rust-components:
@@ -34,9 +34,9 @@ runs:
       run: |
         echo "CARGO_TERM_COLOR=always" >> "$GITHUB_ENV"
 
-        constants_path="${{ github.workspace }}/constants.toml"
+        constants_path="${{ github.workspace }}/constants.env"
         while IFS= read -r line; do
-          if [[ "$line" =~ ^([A-Z0-9_]+)[[:space:]]*=[[:space:]]*\"([^\"]+)\" ]]; then
+          if [[ "$line" =~ ^([A-Z0-9_]+)=([^[:space:]]+) ]]; then
             echo "${BASH_REMATCH[1]}=${BASH_REMATCH[2]}" >> "$GITHUB_ENV"
           fi
         done < "$constants_path"
@@ -70,6 +70,10 @@ runs:
               name=$(echo "${BASH_REMATCH[1]}" | tr 'A-Z_' 'a-z-')
               val="${!tool}"
               [[ -n "$val" ]] && tool="cargo-$name@$val"
+            elif [[ "$tool" =~ ^([A-Z0-9_]+)_VERSION$ ]]; then
+              name=$(echo "${BASH_REMATCH[1]}" | tr 'A-Z_' 'a-z-')
+              val="${!tool}"
+              [[ -n "$val" ]] && tool="$name@$val"
             elif [[ "$tool" =~ ^(.+)@([A-Z0-9_]+)$ ]]; then
               val="${!BASH_REMATCH[2]}"
               [[ -n "$val" ]] && tool="${BASH_REMATCH[1]}@$val"

.github/license-check/config.json

@@ -34,7 +34,10 @@
     {
         "include": [
             "**/*.toml",
-            "**/*.ps1"
+            "**/*.ps1",
+            "**/*.env",
+            "justfile",
+            "**/*.just"
         ],
         "exclude": [
             "target"

.github/workflows/main.yml

@@ -26,7 +26,7 @@ jobs:
         with:
           enable-sccache: true
           rust-toolchain: RUST_MSRV, RUST_NIGHTLY
-          cargo-tools: CARGO_NEXTEST_VERSION, CARGO_HACK_VERSION
+          cargo-tools: CARGO_NEXTEST_VERSION, CARGO_HACK_VERSION, JUST_VERSION
 
       # execute
       - name: Build
@@ -42,6 +42,8 @@ jobs:
       - name: Doc Tests
         if: success() || failure()
         run: cargo test --doc --verbose --workspace --all-features
+      - name: Examples
+        run: just examples
 
   static-analysis:
     runs-on: ${{ matrix.os }}
@@ -95,53 +97,10 @@ jobs:
         uses: ./.github/actions/setup
         with:
           rust-toolchain: RUST_LATEST
-          cargo-tools: CARGO_SPELLCHECK_VERSION
+          cargo-tools: CARGO_SPELLCHECK_VERSION, JUST_VERSION
 
-      # execute
-      - name: Validate Dictionary
-        run: |
-          FILE=".spelling"
-
-          # Verify the first line is an integer
-          first_line=$(head -n 1 "$FILE")
-          if ! [[ "$first_line" =~ ^[0-9]+$ ]]; then
-            echo "Error: The first line of $FILE must be an integer, but got: '$first_line'"
-            exit 1
-          fi
-          expected_count="$first_line"
-
-          # Check that the number of lines matches the integer
-          actual_count=$(sed '1d' "$FILE" | wc -l | xargs)
-          if [ "$expected_count" -ne "$actual_count" ]; then
-            echo "Error: The number of lines ($actual_count) does not match $expected_count."
-            exit 1
-          fi
-
-          # Verify words are sorted and contain no duplicates
-          # Use LC_ALL=en_US.UTF8 for consistent sorting across environments
-          (
-            sed '1d' $FILE | LC_ALL=en_US.UTF8 sort -uc
-          ) || {
-            echo "Error: Dictionary is not in sorted order or contains duplicates."
-            echo "Expected order:"
-            LC_ALL=en_US.UTF8 sort -u <(sed '1d' $FILE)
-            exit 1
-          }
-
-          echo "Dictionary format is valid ($expected_count words)"
       - name: Check Spelling
-        run: |
-          if ! cargo spellcheck --cfg spellcheck.toml --code 1
-          then
-              echo ''
-              echo ''
-              echo 'If this is a Rust method/type/variable name, then you should'
-              echo 'enclose it in backticks like this: `MyRustType`.'
-              echo ''
-              echo 'If this is a real word, then you can add it to .spelling'
-              echo '(add the word in sorted order and update the count on line 1)'
-              exit 1
-          fi
+        run: just spellcheck
 
   semver:
     if: github.event_name == 'pull_request'

.spelling

@@ -1,4 +1,3 @@
-299
 →
 0.X.Y
 100k
@@ -16,6 +15,7 @@ Ani
 api
 APIs
 appender
+Cargo.toml
 args
 AspNet
 async
@@ -37,7 +37,6 @@ btree_map
 buildable
 bytesbuf
 callee
-Cargo.toml
 C-BITFLAG
 C-CONV
 C-CONV-SPECIFIC
@@ -298,4 +297,4 @@ workflows
 workspace
 w.r.t.
 Xamarin
-xxH3
+xxH3

DEVELOPMENT.md

@@ -0,0 +1,113 @@
+# Development environment setup
+
+The standard development environment is a Windows PC, with Windows Subsystem for Linux (WSL) used for Linux development.
+After following this guide, you will be able to execute all the local PC development tooling associated with this repository.
+
+> 💡 Development on a Linux or Mac system is also possible, though the setup process is not documented here.
+
+To run all repository tooling locally, you will need the following prerequisites:
+
+* [Latest version of LLVM](https://github.com/llvm/llvm-project/releases)
+  * Select: ☑️ Add LLVM to the system PATH for the current user
+* [Visual Studio Build Tools for C++](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with components:
+  * Workload: Desktop development with C++
+* [Latest version of Visual Studio Code](https://code.visualstudio.com/Download) with extensions:
+  * C/C++ (ms-vscode.cpptools)
+  * rust-analyzer (rust-lang.rust-analyzer)
+  * WSL (ms-vscode-remote.remote-wsl)
+
+> 💡 Using an IDE other than Visual Studio Code is possible, though the setup process is not documented here.
+
+* [Latest version of Git](https://git-scm.com/downloads/win) with components:
+  * Git LFS (Large File Storage)
+* [Latest version of PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows)
+
+For detailed configuration of the above, use your own judgement - the defaults should work but customization is also generally fine.
+
+This guide assumes a clean Windows PC in other regards.
+
+# Windows environment setup
+
+1. If you had to install any of the above prerequisites, restart your PC to ensure a complete installation.
+1. Install Rust using [Rustup](https://rustup.rs/), with all default settings.
+1. Execute `cargo install just --locked` to install the Just utility (unless already installed).
+
+After installing the Rust toolchain, we setup repository-specific tooling:
+
+1. In a directory of your choosing, clone the `oxidizer` repo: `git clone https://github.com/microsoft/oxidizer.git`.
+
+> 💡 Even though the Windows and Linux development environments are largely independent, they will both use the same working directory (created by the above `git clone` command). This allows you to build and test your changes immediately on both operating systems.
+
+2. Switch to the `oxidizer` directory: `cd oxidizer`.
+2. Execute `git config --local include.path ./.gitconfig` to attach the repo-specific Git configuration.
+2. Execute `just install-tools` to install all necessary Rust toolchain versions and development tooling.
+2. Open `.vscode/settings.template.jsonc` and save a copy as `.vscode/settings.json` to apply repo-specific settings for Visual Studio Code. Part of this file should be the same for everyone but the rest you can customize - refer to inline comments.
+
+## Validate Windows environment
+
+1. Execute `just build` to build the workspace. Verify that the build is successful.
+1. Execute `just test` to execute all tests in the workspace. Verify that all tests pass.
+1. Validate that debugging works by opening `crates/tick/examples/basic.rs` and pressing the `Debug` link that appears above `main()`. This should successfully launch the example app under the debugger.
+
+# Linux (WSL) environment setup
+
+The Linux distribution we use for development is **Ubuntu 24.04**, running as a WSL virtual machine.
+
+1. Install [Ubuntu 24.04.1 LTS](https://apps.microsoft.com/detail/9NZ3KLHXDJP5?hl=en-us&gl=US&ocid=pdpshare) from the Microsoft Store.
+1. Open an Ubuntu terminal (e.g. from the Microsoft Store page, from the Start menu or in Windows Terminal).
+    * If you get an error about a required feature not being installed, try first restarting the PC to complete the feature installation.
+1. You will be asked to create a user account the first time you run Ubuntu. This is a local account unique to the Linux VM and is not related to your account on the host machine.
+
+All commands that follow are to be executed in the Ubuntu terminal.
+
+Next, we upgrade, install and configure development prerequisites:
+
+1. Execute `sudo apt update && sudo apt dist-upgrade -y` to upgrade everything that is already installed.
+1. Execute `sudo apt install -y curl clang llvm libclang-dev gdb perl python3 python3-pip git git-lfs build-essential cmake pkg-config libssl-dev` to ensure that essential packages are installed.
+1. [Install PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/install-ubuntu?view=powershell-7.5#installation-via-package-repository-the-package-repository).
+1. Execute `git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"` to set the correct Git authentication flow.
+1. Execute `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` and install Rust with all default settings.
+1. Reopen the terminal to apply changes.
+1. Execute `cargo install just --locked` to install the Just utility (unless already installed).
+
+Next, we setup repository-specific tooling on Linux:
+
+1. Switch to the `oxidizer` directory you previously cloned on Windows, using a `/mnt/c` style path to access the Windows filesystem: `cd /mnt/c/Users/username/Desktop/oxidizer` (adjusting the path to match your chosen location).
+1. Execute `just install-tools` to install all necessary Rust toolchain versions and development tooling.
+
+## Optimize Linux build performance
+
+> ⚠️ This chapter may conflict with other repos in the same WSL instance. Skip or undo if you experience problems.
+
+After installing the Rust toolchains, we setup the build target directory for fast build times:
+
+1. Execute `mkdir ~/target` to create a directory for Linux build outputs. While the repo directory itself is shared between Windows and Linux, we will use a dedicated directory for build outputs on Linux to improve Linux build performance.
+1. Execute `nano ~/.bashrc` to open a text editor on this file.
+1. Add `export CARGO_TARGET_DIR=~/target` near the end of the file.
+1. Save & exit.
+1. Reopen the terminal to apply changes.
+
+## Validate Linux (WSL) environment
+
+1. Execute `just build` to build the workspace. Verify that the build is successful.
+1. Execute `just test` to execute all tests in the workspace. Verify that all tests pass.
+
+## Setup Visual Studio Code integration
+
+Visual Studio Code is also our standard Linux IDE and requires some additional setup to work with the Linux workspace.
+
+> ⚠️ While the IDE runs on the Windows desktop, all tooling runs in the Linux VM, including Visual Studio Code extensions. The below steps will instruct you to install the minimum set of required Visual Studio Code extensions for the Linux environment.
+
+1. In an Ubuntu terminal, in the `oxidizer` directory, execute `code .` to open the project in Visual Studio Code.
+1. Open the Extensions panel in Visual Studio Code.
+1. Install following extensions by selecting "Install in WSL" for each:
+    * C/C++ (ms-vscode.cpptools)
+    * rust-analyzer (rust-lang.rust-analyzer)
+1. Close Visual Studio Code and open it again via `code .` to complete extension setup.
+
+Validate the setup by executing the following tasks from the task palette (F1):
+
+1. `Tasks: Run Build Task`
+1. `Tasks: Run Test Task`
+
+Validate that debugging works by opening `crates/tick/examples/basic.rs` and pressing the `Debug` link that appears above `main()`. This should successfully launch the example app under the debugger.

README.md

@@ -46,6 +46,9 @@ These are the crates built out of this repo:
 The following sections explain the overall engineering process we use
 in this repo.
 
+To set up a local PC environment capable of exercising all the tooling used by this repo's development processes,
+you can follow the guide in [DEVELOPMENT.md](./DEVELOPMENT.md).
+
 ### Adding New Crates
 
 Adding a new crate to this repo is done by running the `scripts\add-crate.ps1` script.

constants.env

@@ -0,0 +1,36 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+# Shared constants for GitHub workflows and repository automation.
+
+# Rust toolchain versions
+
+# used for testing, ensures the MSRV promise is kept; must match Cargo.toml [workspace.package].rust-version
+RUST_MSRV=1.88
+# used for static analysis & mutation testing; must match rust-toolchain.toml
+RUST_LATEST=1.92
+# used for coverage and extended analysis; update on a regular basis
+RUST_NIGHTLY=nightly-2025-12-29
+# used for external type exposure checks; update alongside updates to cargo-check-external-types
+RUST_NIGHTLY_EXTERNAL_TYPES=nightly-2025-10-18
+
+# Cargo tools
+CARGO_CAREFUL_VERSION=0.4.9
+CARGO_CHECK_EXTERNAL_TYPES_VERSION=0.4.0
+CARGO_DENY_VERSION=0.18.9
+CARGO_DOC2README_VERSION=0.6.3
+CARGO_ENSURE_NO_CYCLIC_DEPS_VERSION=0.2.0
+CARGO_ENSURE_NO_DEFAULT_FEATURES_VERSION=1.0.0
+CARGO_HACK_VERSION=0.6.39
+CARGO_LLVM_COV_VERSION=0.6.21
+CARGO_MUTANTS_VERSION=26.0.0
+CARGO_NEXTEST_VERSION=0.9.115
+CARGO_SEMVER_CHECKS_VERSION=0.45.0
+CARGO_SORT_VERSION=2.0.2
+CARGO_SPELLCHECK_VERSION=0.15.1
+CARGO_UDEPS_VERSION=0.1.60
+CARGO_WORKSPACES_VERSION=0.4.2
+
+# Other tools
+JUST_VERSION=1.46.0
+SCCACHE_VERSION=v0.12.0

constants.toml

@@ -0,0 +1,24 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+# Required by [script]
+set unstable
+
+set windows-shell := ["pwsh.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-Command"]
+set script-interpreter := ["pwsh"]
+
+# Constants shared by Just commands and GitHub workflows.
+set dotenv-path := "./constants.env"
+set dotenv-required := true
+
+package := ""
+target_package := if package == "" { "--workspace" } else { "-p " + package }
+
+_default:
+    @just --list
+
+import 'justfiles/basic.just'
+import 'justfiles/coverage.just'
+import 'justfiles/format.just'
+import 'justfiles/setup.just'
+import 'justfiles/spelling.just'