0-shell

A minimalist Unix-like shell implemented in Rust for embedded Linux environments.

---

Overview

0-shell is a lightweight, standalone shell written in Rust that implements a set of builtin Unix-like commands without spawning external shells (bash/sh). The project focuses on minimalism and portability for constrained or embedded Linux targets while demonstrating core shell concepts: command parsing, filesystem operations, and user interaction.

Repository: https://github.com/astaaa48/0-Shell

---

Key Features

• Interactive prompt and command loop
• Built-in implementations for core commands (no external binaries required by the shell itself)
• Graceful handling of EOF (Ctrl+D) and common errors
• Colorized help output
• Small codebase suitable for learning and extension

Implemented builtins (core):
echo, cd, pwd, ls, cat, cp, rm, mv, mkdir, exit, help

Note: The project also includes small external helper binaries under external/ that can be built and copied into external/bin for convenience.

---

Requirements

• Rust toolchain (cargo + rustc)
• GNU Make (for the provided Makefile)
• Linux (development and run tested on Linux)

---

Quickstart — Build & Run

The repository includes a Makefile that automates building the main shell and optional external helper commands.

• Build everything (clean → build main shell → build listed external commands → copy binaries into external/bin):

make build


* **Build + run the shell** with the local `external/bin` prepended in PATH:

```bash
make run

• Run an already-built binary using the Makefile PATH configuration:

make bin

• Clean build artifacts and copied binaries:

make clean

Makefile highlights (can be passed as environment variables):

• SHELL_NAME — name of the main binary (default: zero_shell)
• COMMANDS — external commands to build and copy into external/bin
• BIN_DIR — destination directory for copied binaries (default: external/bin)
• TARGET_DIR — cargo target directory (default: $(CURDIR)/target)
• QUIET=true — run cargo build quietly
• EXTERNAL=true — when set, make run will include the existing PATH in addition to external/bin

Examples:

• Quiet build:

QUIET=true make build

• Run shell but preserve system PATH so external commands (e.g., system tools) remain available:

EXTERNAL=true make run

---

How the Makefile Works

• Runs cargo build for the main package
• Iterates the COMMANDS list (e.g., cat clear cp ls mkdir mv rm) and runs cargo build -p <cmd> to build each external helper crate in external/
• Copies built artifacts from target/debug/ into external/bin/
• The run target sets PATH to include external/bin (or that plus existing PATH when EXTERNAL=true) before launching the shell

This workflow allows the shell to execute helper commands placed under external/bin during interactive sessions.

---

Running the Shell Manually

After building:

• Launch the shell with the local PATH override used by the Makefile:

export PATH="$(pwd)/external/bin:$(PATH)"
external/bin/zero_shell

• Or, directly run the built binary:

target/debug/zero_shell

---

Usage Examples

At the shell prompt ($):

• Change directory:

$ cd /tmp

• Print working directory:

$ pwd

• Print a line:

$ echo "Hello World"

• Get help:

$ help
$ help echo

• Exit:

$ exit
# (or press Ctrl+D)

---

Notes on Implementation

• Each builtin command exposes a pub fn run(args: Vec<String>) -> i32 that returns a POSIX-like exit status (0 success, non-zero failure codes). Look at src/commands/* for examples (cd.rs, echo.rs, pwd.rs, help.rs)
• help uses the colored crate to render a framed help menu
• echo supports prompting to complete unclosed quotes using rustyline for continuation input and returns non-zero on interrupt or EOF
• cd updates OLDPWD and reports error exit codes for failure cases

---

Project Layout

src/            — main shell implementation and builtin command modules
 └─ commands/   — builtin command implementations (cd, echo, pwd, help, exit, ...)
 └─ shell.rs
 └─ parser.rs
 └─ main.rs    — main loop and parsing
external/       — optional small helper crates and final `external/bin` target
Makefile        — build/run automation

---

Troubleshooting

• Cargo build failures:

  • Ensure Rust toolchain is installed (rustup/cargo)
  • Check crate features and Cargo.toml in external/* crates

• Missing binaries in external/bin after make build:

  • Confirm target/debug/<cmd> exists
  • Ensure COMMANDS variable lists the external crates you expect built

• PATH issues when running:

  • Use EXTERNAL=true make run to preserve the system PATH if you need system commands available

• Permission denied launching copied binaries:

  • Ensure external/bin/* are executable:

chmod +x external/bin/*

---

Contributing

• Add or improve builtin commands under src/commands
• Add small utility crates under external/ and add their names to COMMANDS in the Makefile if you want them copied to external/bin automatically
• Open issues or pull requests with clear descriptions and tests where applicable