More updates to docs (#41)

.devcontainer/Dockerfile

@@ -1,44 +1,51 @@
 FROM ubuntu:latest
 
-ARG DEFAULT_USER=devel
-
+ARG USERNAME=devel
+ARG USER_UID=1000
+ARG USER_GID=$USER_UID
+
+# Install basic utilities and prerequisites.
+#   bsdmainutils - provides hexdump, used by integration tests
+#   neovim - for convenience and modern editing
 RUN apt-get update -y && \
     apt-get install -y \
+        bsdmainutils \
         build-essential \
         curl \
         git \
         language-pack-en \
         neovim \
         sed \
         sudo \
-        wget \
-        zsh
+        wget
+
+# Install gh cli
+# Reference: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+RUN mkdir -p -m 755 /etc/apt/keyrings && \
+    wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null && \
+    chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg && \
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null && \
+    apt-get update -y && \
+    apt-get install -y gh
 
 # Add a non-root user that we'll do our best to use for development.
-RUN useradd -m devel && \
+RUN userdel ubuntu && \
+    groupadd --gid $USER_GID $USERNAME && \
+    useradd --uid $USER_UID --gid $USER_GID -m $USERNAME && \
     echo "devel ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
 
 # Switch to user.
-USER ${DEFAULT_USER}
+USER devel
 
 # Set up path to include rust components.
-ENV PATH="${PATH}:/home/${DEFAULT_USER}/.cargo/bin"
-WORKDIR /tmp
+ENV PATH="${PATH}:/home/devel/.cargo/bin"
 
 # Copy scripts to temp dir.
 WORKDIR /tmp
 
-# Install rust and plugins
-COPY install-rust-and-friends.sh .
-RUN ./install-rust-and-friends.sh
-
-# Install assorted development utilities
-COPY install-dev-tools.sh .
-RUN ./install-dev-tools.sh
-
-# Bring modern conveniences to shell.
-COPY make-shell-comfortable.sh .
-RUN ./make-shell-comfortable.sh
+# Install rust toolchain and cargo tools.
+COPY install-rust-tools.sh .
+RUN ./install-rust-tools.sh
 
 # Switch back to home dir for normal usage.
-WORKDIR /home/${DEFAULT_USER}
+WORKDIR /home/devel

.devcontainer/devcontainer.json

@@ -11,5 +11,6 @@
         }
     },
     "features": {},
-    "remoteUser": "devel"
+    "remoteUser": "devel",
+    "updateRemoteUserUID": true
 }

.devcontainer/install-rust-and-friends.sh → .devcontainer/install-rust-tools.sh

@@ -2,13 +2,15 @@
 set -euo pipefail
 
 # Install rustup and needed components
+# Reference: https://rustup.rs/
 curl https://sh.rustup.rs -sSf | sh -s -- -y
 rustup component add llvm-tools-preview
 
 # Install cargo binstall
+# Reference: https://github.com/cargo-bins/cargo-binstall
 curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
 
-# Install cargo tools
+# Install cargo tools using binstall
 cargo binstall --no-confirm cargo-audit
 cargo binstall --no-confirm cargo-deny
 # cargo binstall --no-confirm cargo-flamegraph

.vscode/settings.json

@@ -3,10 +3,10 @@
     "files.exclude": {
         "target/": true
     },
-    "terminal.integrated.defaultProfile.linux": "zsh",
+    "terminal.integrated.defaultProfile.linux": "bash",
     "terminal.integrated.profiles.linux": {
-        "zsh": {
-            "path": "/bin/zsh"
+        "bash": {
+            "path": "/bin/bash"
         }
     },
     "rust-analyzer.check.command": "clippy",

README.md

@@ -5,11 +5,13 @@
 
 ## About
 
-`brush` (**B**orn **RU**sty **SH**ell) is a shell implementation with aspirations of compatibility with the [POSIX Shell specification](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html) as well as with [bash](https://www.gnu.org/software/bash/).
+`brush` (**B**orn **RU**sty **SH**ell) is a shell implementation with aspirations of compatibility with the [POSIX Shell specification](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html) and [bash](https://www.gnu.org/software/bash/).
 
-It's generally functional for interactive use and can execute many scripts, but it's still very much a work in progress. We do not recommend using this in production scenarios; until it's more stable, there's risk that using this implementation in place of your stable shell will result in unexpected behavior (e.g., this shell taking an `else` branch of a conditional when your `sh` may have otherwise taken the `then` branch).
+It's generally functional for interactive use and can execute many scripts but still a work in progress. We do not recommend using this in production scenarios; until it's more stable, there's risk that using this implementation in place of your stable shell may result in unexpected behavior.
 
-This project was primarily borne out of curiosity and a desire to learn. If it proves to be sufficiently interesting and/or useful, then that's a bonus :). Contributions are certainly welcome. For more guidance, please consult [CONTRIBUTING.md](CONTRIBUTING.md).
+This project was primarily borne out of curiosity and a desire to learn. If it proves to be interesting or useful, then that's a bonus :).
+
+Contributions and feedback of all kinds are welcome! For more guidance, please consult our [contribution guidelines](CONTRIBUTING.md). For more technical details, please consult the [documentation](docs/README.md) in this repo.
 
 ### License
 
@@ -36,6 +38,8 @@ There's certainly more gaps; with time we'll find a way to represent the gaps in
 
 This project is primarily tested by comparing its behavior with other existing shells, leveraging the latter as test oracles. The integration tests implemented in this repo include [300+ test cases](cli/tests/cases) run on both this shell and an oracle, comparing standard output and exit codes.
 
+For more details, please consult the [reference documentation on integration testing](docs/reference/integration-testing.md).
+
 ## Links: other shell implementations
 
 This is certainly not the first attempt to implement a feature-rich POSIX-ish shell in a non-C/C++ implementation language. Some examples include:

cli/tests/cases/builtins/shopt.yaml

@@ -1,10 +1,12 @@
 name: "Builtins: shopt"
 cases:
   - name: "shopt defaults"
+    skip: true
     stdin: |
       shopt | sort | grep -v extglob
 
   - name: "shopt interactive defaults"
+    skip: true
     args: ["-i"]
     ignore_stderr: true
     stdin: |

docs/README.md

@@ -0,0 +1,13 @@
+# brush documentation
+
+The docs are grouped into:
+
+* [How-to guides](how-to/README.md)
+* [Tutorials](tutorials/README.md)
+* [Reference material](reference/README.md)
+
+If you're just getting started building this project, you should consult the [How to Build](how-to/build.md) guide.
+
+---
+
+> _Note: The structure of our docs is inspired by the [Diátaxis](https://diataxis.fr/) approach; we've found over time that best helps readers find the material most relevant to them, as well as provides a rough shape for where to place the right docs._

docs/how-to/README.md

@@ -0,0 +1,5 @@
+# How-to guides
+
+* [How to build](build.md)
+* [How to run tests](run-tests.md)
+* [How to run benchmarks](run-benchmarks.md)

docs/how-to/build.md

@@ -0,0 +1,5 @@
+# How to build and run
+
+1. Install Rust toolchain. We recommend using [rustup](https://rustup.rs/).
+1. Build `brush`: `cargo build`
+1. Run `brush`: `cargo run`

docs/how-to/run-benchmarks.md

@@ -0,0 +1,17 @@
+# How to run benchmarks
+
+To run performance benchmarks:
+
+```bash
+cargo bench --workspace
+```
+
+## Collecting flamegraphs
+
+To collect flamegraphs from performance benchmarks (running for 10 seconds):
+
+```bash
+cargo bench --workspace -- --profile-time 10
+```
+
+The flamegraphs will be created as `.svg` files and placed under `target/criterion/<benchmark_name>/profile`.

docs/how-to/run-tests.md

@@ -0,0 +1,19 @@
+# How to run tests
+
+To run all workspace tests:
+
+```bash
+cargo test --workspace
+```
+
+To run just integration tests:
+
+```bash
+cargo test --test integration_tests
+```
+
+To run a specific integration test case
+
+```bash
+cargo test --test integration_tests -- '<name of test case>'
+```

docs/reference/README.md

@@ -0,0 +1,3 @@
+# Reference
+
+* [Integration testing](integration-testing.md)

docs/tutorials/README.md

@@ -0,0 +1,3 @@
+# Tutorials
+
+_To be written_