tree: a3346656ef266cb69da6c572eea29de140330604 [search]
  1. meta/
  2. src/
  3. BUILD.bazel
  4. BUILD.gn
  5. OWNERS
  6. README.md
src/developer/zxsh/README.md

zxsh - Fuchsia Shell

zxsh is a modern, lightweight, POSIX-like command shell implemented in Rust. It is designed specifically for the Fuchsia operating system to serve as a fast, robust, and minimal shell environment, intended to replace the NetBSD-derived dash shell (zircon/third_party/uapp/dash).

Key Features & Architecture

Flat, Relocatable AST

Unlike traditional ASTs which rely on recursive heap-allocated structures (such as Box<Node>), zxsh compiles commands into a flat, relocatable Abstract Syntax Tree (src/parser/ast.rs, src/relative.rs).

  • Relocatable Offset Pointers: The AST is built inside a contiguous byte buffer using 32-bit unsigned offset pointer types (relative::Ptr<T>, relative::Slice<T>, and relative::BStr). Pointer dereferencing is bounds-checked against the containing buffer (relative::Buffer), ensuring memory safety without pointer patching during reallocation.
  • Zerocopy AST Nodes: All AST structures (Command, WordPart, Redirect, CaseItem) implement zerocopy traits (FromBytes, IntoBytes, Immutable, KnownLayout), allowing direct in-place access and serialization.
  • Zero-Copy Subshells & VMO Transport: When spawning a subshell, the parent serializes the AST buffer and the shell environment directly into a Zircon VMO with a fixed 24-byte header (SubshellPayloadHeader in src/subshell.rs) and transfers it via a startup handle (fuchsia_runtime::HandleType::User0). The spawned zxsh subshell process takes the handle on startup and executes the AST in place without reparsing or tree allocations.

Binary Size & Memory Optimizations

Because zxsh runs in early-boot and recovery environments, keeping the binary size small is a primary design goal:

  • Byte-Safe Strings: Standard Rust String and str are largely replaced by BString and BStr types from the bstr crate (src/string.rs). These operate directly on arbitrary [u8] byte slices (complying with Bourne shell path/variable byte semantics) and are compiled without the "unicode" feature to eliminate large Unicode validation tables.
  • Minimal Error Formatting: Standard library OS error loading tables are bypassed in favor of static lookup mappings (src/errors.rs) for Zircon (zx_status_str) and I/O (io_err_str) error codes.
  • Zero-Allocation Custom Sort: Uses a custom in-place 3-way quicksort (src/sort.rs) to avoid compiling the standard library's larger generic sorting routines.
  • Custom Flat Collections: Implements vector-backed FlatMap and FlatSet structures (src/collections.rs) for variables, functions, aliases, and limits, avoiding the overhead and SipHash hashing dependencies of standard HashMap and HashSet.
  • Compiler Optimization: Built with -Copt-level=z (optimize-for-size in BUILD.gn) to minimize binary footprint on BootFS.

Line Editing & Interactive REPL

In interactive mode (src/repl/mod.rs):

  • Line Editor Integration: Uses the pure-Rust line-editor library (//src/lib/line-editor) for history management and interactive line editing.
  • Tab Completion: Provides autocompletion (src/repl/completion.rs) for commands in PATH as well as filesystem paths.
  • Dynamic Prompts: Supports shell prompt expansion for PS1 (default $ ), PS2 (default > ), and PS4 (xtrace prefix, default + ).

Shell Language Capabilities

zxsh implements standard POSIX shell grammar and execution semantics:

  • Commands & Pipelines: Simple commands (cmd arg1 arg2), pipelines (cmd1 | cmd2 | cmd3) with optional status negation (! cmd1 | cmd2), and command blocks ({ cmd; }).
  • Control Flow:
    • Conditionals: if ...; then ...; elif ...; then ...; else ...; fi
    • Loops: while ...; do ...; done, until ...; do ...; done, for var in ...; do ...; done
    • Pattern Matching: case word in [(] pattern) ... ;; esac
    • Chaining: && (logical AND), || (logical OR), ; and newline (sequence), & (asynchronous background execution)
    • Loop Control: break [n], continue [n]
  • Functions: Shell function definitions (fname() { ... }) with local variable scoping (local) and positional argument isolation.
  • Expansions:
    • Parameter / Variable Expansion: $VAR, ${VAR}, ${VAR:-default}, ${VAR:=default}, ${VAR:?error}, ${VAR:+alt}, string length ${#VAR}, suffix removal ${VAR%pattern} / ${VAR%%pattern}, and prefix removal ${VAR#pattern} / ${VAR##pattern}.
    • Special Parameters: $? (exit status), $# (arg count), $$ (PID), $! (last background PID), $* / $@ (all args), $- (current options), $0 (script/shell name), and positional $1..$9, ${10}.
    • Command Substitution: $(command) and legacy backticks `command`.
    • Arithmetic Expansion: $(( expression )) supporting arithmetic (+, -, *, /, %), pre/post-increment and decrement (++, --), bitwise (&, |, ^, ~, <<, >>), comparisons (<, <=, >, >=, ==, !=), logical (&&, ||, !), ternary (? :), assignment (=, +=, -=, etc.), comma (,), decimal, octal (0...), and hexadecimal (0x...) constants, variables, and grouping.
    • Pathname Expansion (Globbing): *, ?, and character classes [...] (including ranges [a-z] and negations [!...] / [^...]).
    • Word Splitting & Quote Removal: Field splitting using $IFS, single quotes '...', double quotes "...", and backslash escapes \.
  • Redirections & Here-Documents:
    • File input < file, output > file (truncation) / >> file (append), and read-write <> file
    • Clobber control >| file (overriding noclobber / set -C)
    • File descriptor duplication >&fd, <&fd and closing >&-, <&-
    • Here-documents << EOF and <<- EOF (with or without parameter expansion; small heredocs are written inline to the pipe, while large heredocs use a streaming worker thread to prevent pipe deadlocks)
    • /dev/null redirection emulation via fdio::create_fd_null
  • Job Control & Signals:
    • Background process management (&, jobs, fg, bg, wait)
    • Signal trap handling via trap (supports EXIT, INT, TERM, HUP, QUIT)
    • Interactive interrupt handling (Ctrl+C cancels line buffer and sets exit status to 130)

Built-in Commands

zxsh supports a rich set of builtins implemented across dedicated modules:

1. Essential POSIX Built-ins

Implemented in src/builtins/essential.rs and src/builtins/mod.rs:

  • cd, chdir, pwd (supports -L logical and -P physical modes)
  • export, readonly, local, unset
  • alias, unalias
  • set, shift, getopts
  • eval, exec, exit, return
  • break, continue
  • jobs, fg, bg, wait
  • trap (signal trap registration and inspection)
  • read (reads line from standard input with -r raw mode and $IFS field splitting)
  • type (identifies command as builtin, function, alias, or external binary)
  • command (executes command bypassing shell functions and aliases)
  • hash (displays or manages cached executable path lookups)
  • ulimit (manages resource limits such as file size, stack, open files, CPU time)
  • umask (displays or updates file mode creation mask in octal or symbolic format)
  • . (source), :, true, false

2. File Utilities

Implemented in src/builtins/file_utils.rs to allow filesystem operations without the overhead of spawning external processes:

  • ls (directory and file listing; supports -l long format)
  • cp (copy files; supports -f)
  • mv (move/rename files; supports -f)
  • rm (remove files and directories; supports -r/-R, -f)
  • mkdir (create directories; supports -p)

3. Text & Formatted Output

  • echo (src/builtins/echo.rs): Prints arguments with escape sequence processing (\n, \t, \c, octal escapes) and -n flag support.
  • printf (src/builtins/printf.rs): POSIX standard formatted output supporting format specifiers (%s, %c, %d, %i, %o, %u, %x, %X, %f, %F, %e, %E, %g, %G, %a, %A, %b, %%), width and precision modifiers (including *), and formatting flags (-, +, space, #, 0).

4. Condition Evaluation

  • test / [ (src/builtins/test.rs): Full POSIX expression evaluation:
    • File tests: -e, -r, -w, -x, -f, -d, -s, -c, -b, -p, -h, -L, -S, -u, -g, -k, -t, -O, -G, -nt, -ot, -ef
    • String tests: -z, -n, =, ==, !=, <, >
    • Integer comparisons: -eq, -ne, -lt, -le, -gt, -ge
    • Logical operators: !, -a, -o, ( ... )

5. Diagnostics & Timing Utilities

  • list (src/builtins/list.rs): Displays numbered lines of a file (list <filename>).
  • msleep (src/builtins/msleep.rs): Sleeps for a specified number of milliseconds (msleep <msecs>).
  • dump (src/builtins/dump.rs): Formats and prints a hexadecimal/ASCII dump of a file (dump <filename>).
  • times (src/builtins/times.rs): Prints accumulated user and system CPU times for the shell and child processes.

6. Fuchsia/Zircon System Control Built-ins

Implemented in src/builtins/fuchsia.rs:

  • dm / power: Connects to fuchsia.hardware.power.statecontrol.Admin to control device power states:
    • dm poweroff / dm shutdown / power off / power shutdown
    • dm reboot / power reboot
    • dm reboot-bootloader (or rb) / power reboot-bootloader (or rb)
    • dm reboot-recovery (or rr) / power reboot-recovery (or rr)
    • dm help / power help
  • k: Connects to fuchsia.kernel.DebugBroker to execute kernel debug commands directly from the shell (e.g. k thread). Forwards poweroff, reboot, and reboot-bootloader commands to dm.

Running zxsh

zxsh supports multiple execution modes (src/main.rs, src/args.rs):

  1. Interactive REPL:
    zxsh
    # or force interactive mode:
    zxsh -i
    
  2. Command Execution:
    zxsh -c "echo 'Hello from zxsh!'"
    # with positional arguments:
    zxsh -c 'echo "$1 $2"' script_name "foo" "bar"
    
  3. Script Execution:
    zxsh /path/to/script.sh [args...]
    
  4. Standard Input Execution:
    zxsh -s [args...]
    # or forced stdin reading:
    zxsh - [args...]
    
  5. Subshell Process (Internal): Spawned internally via startup handle (HandleType::User0) containing a serialized AST and shell environment in a VMO.

Command-Line Options

Supported single-letter flags (set with -, clear with +) and -o / +o options:

FlagOption NameDescription
-aallexportAutomatically export all defined or modified variables
-bnotifyReport background job termination immediately
-CnoclobberPrevent redirection from overwriting existing files
-eerrexitExit immediately if a command exits non-zero
-fnoglobDisable pathname expansion (globbing)
-iinteractiveForce shell to run interactively
-IignoreeofIgnore EOF (Ctrl-D) when reading from stdin
-lloginRun as a login shell
-mmonitorEnable job control
-nnoexecRead commands but do not execute them
-sstdinRead commands from standard input
-unounsetTreat unset variables as an error during expansion
-vverbosePrint shell input lines as they are read
-xxtracePrint commands and arguments as they are executed
-EemacsEnable Emacs line editing mode
-VviEnable Vi line editing mode

Limitations

File Descriptor Inheritance

Unlike POSIX shells on Linux/macOS, zxsh on Fuchsia does not support implicit inheritance of non-standard file descriptors (FDs other than 0, 1, and 2) for external commands.

For example, if you run:

exec 3>file.txt
my_external_command >&3

Or:

my_external_command 3>file.txt

The child process my_external_command will NOT inherit FD 3. It will start with FD 3 closed.

This is a design limitation of the Fuchsia process creation model (fdio_spawn / fuchsia.process.Launcher), which requires explicit transfer of handles and does not support cloning the entire file descriptor table to child processes by default. This behavior matches the Fuchsia port of dash (zircon/third_party/uapp/dash).

Redirections of standard streams (0, 1, 2) are fully supported for all commands.


Testing

zxsh includes a comprehensive test suite covering parser grammar, AST serialization, evaluations, expansions, arithmetic, builtins, and parity testing against dash.

To run the test suite:

fx test zxsh_tests

Unit tests are organized in src/tests/ and cover:

  • Language constructs (AST, tokenization, parsing, pipelines, control flow, redirections, expansions)
  • Evaluation runtime (signals, arithmetic, globbing, state frames, subshells)
  • Parity tests verifying behavioral compatibility with dash for all shell builtins