Skip to content

README.md

Latest commit

 

History

History
74 lines (58 loc) · 3.38 KB

README.md

File metadata and controls

74 lines (58 loc) · 3.38 KB

shell

Educational project — built to learn how Unix shells work by implementing one from scratch in Rust.

A Unix shell written in Rust with interactive line editing, job control, piping, I/O redirections, variable expansion, and a set of built-in commands.

Features

Interactive input

  • Raw terminal mode with character-by-character input via termion
  • Cursor navigation and line editing
  • Command history navigation across sessions (persisted via $HISTFILE)

Execution model

  • && chaining — run next command only if the previous succeeded
  • Pipes (|) — connect stdout of one command to stdin of the next
  • Background jobs (&) — fork and run a pipeline in the background; notified on completion
  • SIGCHLD handling via a self-pipe to safely reap child processes from the event loop

I/O redirection

Syntax Effect
cmd > file Redirect stdout to file (truncate)
cmd >> file Append stdout to file
cmd 2> file Redirect stderr to file (truncate)
cmd 2>> file Append stderr to file

Variable expansion

  • Shell variables stored in a session-scoped map (separate from environment variables)
  • $VAR and ${VAR} syntax
  • Falls back to environment variables when a shell variable is not found

Built-in commands

Command Description
cd [dir] Change the working directory. cd, cd ~, and cd "" go to $HOME; ~/path is expanded to the home directory.
pwd Print the current working directory.
echo [args...] Print arguments joined by spaces. \n in the string is interpreted as a newline.
exit Exit the shell, flushing history to $HISTFILE.
type <name> Report whether name is a shell builtin or an external command, and if external, print its full path.
declare VAR=VALUE Set a shell variable. declare VAR sets it to an empty string.
declare -p VAR Print the value of a shell variable in declare -- VAR="VALUE" format.
history [n] List command history with line numbers. Optional n shows only the last n entries.
jobs List background jobs with their job number, status (running), and command. The most recent job is marked +, the previous -.
kill <pid> Send SIGTERM to a process by PID.
kill %<job> Send SIGTERM to a background job by job number (e.g. kill %1).

Requirements

  • Rust (edition 2024)
  • Unix / macOS (relies on libc, fork, waitpid, POSIX signals)

Build & Run

cargo build --release
cargo run

The shell reads $HISTFILE on startup to load history and appends new entries to it on exit.

Project Structure

File Responsibility
src/lib.rs Main event loop, SIGCHLD signal handling, background job reaping
src/command.rs Command parsing (pipes, &&, quoting, escaping) and execution dispatch
src/jobs.rs Background job registry
src/history.rs Command history with persistence
src/variables.rs Shell variable storage and $VAR / ${VAR} expansion
src/redirection.rs I/O redirection parsing (>, >>, 2>, 2>>)
src/execute_output.rs Buffered output for builtin-to-pipe handoff
src/utils.rs Input reading, PATH resolution, error types