🐚 Rust Shell

A POSIX-compliant shell implementation written in Rust, built as part of the CodeCrafters Shell Challenge. This shell provides a command-line interface with support for built-in commands, external program execution, pipelines, I/O redirection, and interactive features.

📋 About

This project is a fully functional command-line shell implementation built from scratch in Rust. It demonstrates core systems programming concepts including process management, file descriptor manipulation, signal handling, and interactive terminal control.

Why This Project?

Building a shell from the ground up provides deep insights into:

• Process Management - How operating systems spawn and manage processes
• I/O Redirection - Understanding file descriptors, pipes, and streams
• Command Parsing - Tokenization, pipeline detection, and argument handling
• Interactive Interfaces - Terminal control, history, and autocompletion
• System Integration - PATH resolution, environment variables, and working directory management

Key Highlights

• Modular Design - Clean separation of concerns with dedicated modules for parsing, execution, and utilities
• Type Safety - Leverages Rust's type system for safe memory management and error handling
• Interactive Experience - Rich command-line editing with tab completion and history navigation
• POSIX Compliance - Follows standard shell behavior for compatibility with existing tools

What is POSIX Compliance?

POSIX (Portable Operating System Interface) is a family of standards that define how Unix-like operating systems should behave. A POSIX-compliant shell means:

• Standard Command Syntax - Commands follow the same syntax and behavior as standard Unix shells (bash, sh, zsh)
• Compatible Behavior - Works with existing Unix/Linux tools and scripts
• Standard Features - Implements core shell features like:
  • Command pipelines (|)
  • I/O redirection (>, >>, <, 2>, 2>>)
  • Built-in commands (cd, pwd, echo, etc.)
  • Environment variable handling
  • PATH resolution for executables

This shell implements POSIX-compliant features, meaning scripts and commands written for standard Unix shells will work similarly here.

✨ Features

Built-in Commands

• cd - Change directory with support for absolute/relative paths and ~ (home directory)
• pwd - Print current working directory
• echo - Print arguments to stdout
• type - Check if a command is a builtin or external executable
• exit - Exit the shell (with optional history saving via HISTFILE)
• history - Display command history with support for:
  • history - Show all history
  • history <n> - Show last n commands
  • history -r <file> - Load history from file
  • history -w <file> - Write history to file
  • history -a <file> - Append history to file

Advanced Features

• Command Pipelines - Chain multiple commands using | operator
• I/O Redirection - Support for >, >>, <, 2>, 2>>
• Tab Completion - Autocomplete for:
  • Built-in commands (echo, exit, etc.)
  • External executables in PATH
  • Multiple matches handling (bell on first TAB, list on second TAB)
• Command History - Navigate previous commands with arrow keys
• PATH Resolution - Execute external programs from PATH directories
• History Persistence - Automatic history loading/saving via HISTFILE environment variable

🚀 Installation

Prerequisites

• Rust 1.91 or later
• Cargo (Rust package manager)

Build

cargo build --release

Run

./your_program.sh

Or directly:

cargo run

📖 Usage Examples

Basic Commands

$ pwd
/home/user/projects

$ echo "Hello, World!"
Hello, World!

$ cd ~/Documents
$ pwd
/home/user/Documents

Command Pipelines

$ cat file.txt | wc -l
42

$ echo "hello" | tr '[:lower:]' '[:upper:]'
HELLO

I/O Redirection

$ echo "Hello" > output.txt
$ cat output.txt
Hello

$ echo "World" >> output.txt
$ cat output.txt
Hello
World

$ wc -l < input.txt
10

History Management

$ history
    1  echo hello
    2  pwd
    3  history

$ history -r ~/.shell_history
$ history -w ~/.shell_history

Tab Completion

$ ec<TAB>        # Completes to "echo "
$ /usr/bin/ls<TAB><TAB>  # Shows all matches starting with "ls"

🏗️ Project Structure

src/
├── main.rs              # Entry point and main REPL loop
└── shell/
    ├── mod.rs          # Module declarations
    ├── builtin.rs      # Built-in command handlers
    ├── completer.rs    # Tab completion logic
    ├── constants.rs    # Shell constants
    ├── external.rs     # External command execution
    ├── io_utils.rs     # I/O utilities and ShellReader
    ├── parser.rs       # Command and pipeline parsing
    ├── path.rs         # PATH resolution utilities
    ├── pipeline.rs     # Pipeline execution logic
    ├── redirection.rs  # I/O redirection handling
    └── utils.rs        # Utility functions

🛠️ Technologies

• Rust - Systems programming language
• rustyline - Rich command-line editing with history and completion
• shlex - Shell-like tokenization for command parsing
• libc - Low-level system calls

📝 Architecture

The shell follows a modular architecture:

1. Input Layer (io_utils.rs) - Handles user input via rustyline with history and completion
2. Parser Layer (parser.rs) - Parses commands, pipelines, and redirections
3. Execution Layer:
   • builtin.rs - Executes built-in commands
   • external.rs - Executes external programs
   • pipeline.rs - Handles command pipelines
4. Utilities:
   • path.rs - Resolves executables in PATH
   • redirection.rs - Manages I/O redirection
   • completer.rs - Provides tab completion

🧪 Testing

This project is part of the CodeCrafters Shell Challenge. Tests are run automatically when you push to the repository.

📄 License

This project is part of the CodeCrafters educational challenge series.

🙏 Acknowledgments

• Built as part of the CodeCrafters Shell Challenge
• Inspired by POSIX shell specifications