Skip to content

README.md

Latest commit

 

History

History
402 lines (309 loc) · 11.5 KB

README.md

File metadata and controls

402 lines (309 loc) · 11.5 KB

🐚 MiniShell

MiniShell Demo

Made with C 42 Project License: MIT Build Status Version

A powerful, feature-rich shell implementation that mimics bash behavior

✨ Built by talented 1337 students with passion and precision ✨

🎯 Project Overview

MiniShell is a comprehensive shell implementation developed as part of the 42 School curriculum. This project recreates the core functionality of bash, providing users with a familiar command-line experience while demonstrating advanced C programming concepts, including parsing, process management, and system calls.

🚀 Key Highlights

  • 🔥 Full bash-like experience with advanced parsing
  • ⚡ Lightning-fast execution with efficient memory management
  • 🛡️ Robust error handling and signal management
  • 🎨 Clean, modular codebase following best practices
  • 📚 Educational value - perfect for learning systems programming

✨ Features

🛠️ Built-in Commands

echo    # Display text with -n option support
cd      # Change directory (supports HOME and relative paths)
pwd     # Print working directory  
export  # Set environment variables
unset   # Remove environment variables
env     # Display environment variables
exit    # Exit shell with custom exit codes

🔗 Advanced Shell Features

# Pipes - Chain commands together
ls -la | grep "test" | wc -l

# Redirections - Manage input/output
echo "Hello World" > output.txt
cat < input.txt >> output.txt

# Here-documents - Multi-line input
cat << EOF
This is a here-document
Multiple lines supported
EOF

# Logical operators - Conditional execution
make && ./minishell || echo "Build failed"

# Wildcard expansion - Pattern matching
ls *.c
echo test_*

💡 Parser Capabilities

  • 🔤 Tokenization - Smart command parsing
  • 🌳 AST Building - Abstract Syntax Tree construction
  • 💲 Variable Expansion - Environment variable substitution
  • 🎯 Quote Handling - Single and double quote support
  • 🔄 Subshells - Parentheses grouping (command)
  • ⚠️ Error Recovery - Intelligent syntax error handling

🎛️ System Integration

  • 📡 Signal Handling - Ctrl+C, Ctrl+D, Ctrl+\ support
  • 🧠 Memory Management - Zero memory leaks
  • 🔄 Process Control - Fork, exec, wait management
  • 📜 History - Command history with readline

🛠️ Installation

Prerequisites

# Required dependencies
sudo apt-get update
sudo apt-get install build-essential readline-dev

Clone & Build

# Clone the repository
git clone https://github.com/Yo-omega/mini-shell.git
cd mini-shell

# Build the project
make

# Optional: Build with debug flags
make normal

Quick Start

# Launch MiniShell
./minishell

# You should see the beautiful prompt
shell $

🎮 Usage Examples

Basic Commands

shell $ echo "Hello, MiniShell!" 
Hello, MiniShell!

shell $ pwd
/home/user/mini-shell

shell $ export GREETING="Welcome to MiniShell"
shell $ echo $GREETING
Welcome to MiniShell

Advanced Piping

shell $ ls -la | grep "\.c$" | wc -l
13

shell $ cat /etc/passwd | head -5 | tail -2
daemon:x:1:1:daemon:/usr/sbin:/usr/sbin/nologin
bin:x:2:2:bin:/bin:/usr/sbin/nologin

File Operations

shell $ echo "MiniShell rocks!" > test.txt
shell $ cat < test.txt
MiniShell rocks!

shell $ ls *.c | head -3 >> filelist.txt
shell $ cat filelist.txt

Here-Documents

shell $ cat << END
> This is line 1
> This is line 2  
> Variables work: $USER
> END
This is line 1
This is line 2
Variables work: username

Logical Operations

shell $ ls non_existent_file || echo "File not found!"
File not found!

shell $ make clean && make && echo "Build successful!"
# Compiles and shows success message

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│                   MiniShell                     │
├─────────────────────────────────────────────────┤
│  Input Reading (readline)                       │
├─────────────────────────────────────────────────┤
│  Tokenization & Parsing                         │
│  ├── Lexical Analysis                           │
│  ├── Syntax Analysis                            │
│  └── AST Building                               │  
├─────────────────────────────────────────────────┤
│  Expansion & Processing                         │
│  ├── Variable Expansion                         │
│  ├── Quote Removal                              │
│  ├── Wildcard Expansion                         │
│  └── Here-document Processing                   │
├─────────────────────────────────────────────────┤
│  Execution Engine                               │
│  ├── Built-in Commands                          │
│  ├── External Commands                          │
│  ├── Pipes & Redirections                       │
│  └── Process Management                         │
├─────────────────────────────────────────────────┤
│  System Interface                               │
│  ├── Environment Management                     │
│  ├── Signal Handling                            │
│  └── Memory Management                          │
└─────────────────────────────────────────────────┘

Key Components

Component Description Files
Parser Tokenization, syntax analysis, AST building parse/
Executor Command execution, process management execute_command.c, exec_tree.c
Builtins Built-in command implementations builtins/
Expansion Variable and wildcard expansion parse/expand/, parse/globbing/
Redirection I/O redirection and pipe handling redirections.c, here_doc.c

🧪 Testing

Interactive Testing

# Launch and test interactively
./minishell

# Test built-ins
shell $ echo -n "No newline"
shell $ cd /tmp && pwd
shell $ export TEST="value" && echo $TEST

# Test parsing edge cases
shell $ echo "test'quote"
shell $ ls | cat | wc -l
shell $ (echo "subshell") && echo "parent"

Batch Testing

# Create test script
cat << 'EOF' > test_script.sh
#!/bin/bash
echo "=== Testing MiniShell ==="
echo "Current directory: $(pwd)"
echo "Environment test:" 
export TEST_VAR="Hello MiniShell"
echo $TEST_VAR
ls | head -3
echo "Tests completed!"
EOF

# Run with MiniShell  
./minishell < test_script.sh

🔧 Development

Project Structure

mini-shell/
├── all/
│   ├── main.c              # Entry point and main loop
│   ├── main.h              # Main header with includes
│   ├── Makefile           # Build configuration
│   ├── builtins/          # Built-in commands
│   │   ├── ft_echo.c
│   │   ├── ft_cd.c
│   │   └── ...
│   ├── parse/             # Parsing engine
│   │   ├── expand/        # Variable expansion
│   │   ├── globbing/      # Wildcard handling
│   │   ├── here_doc/      # Here-document processing
│   │   └── tokenize/      # Tokenization
│   ├── libft/             # Utility library
│   └── ...
└── readline.supp          # Valgrind suppressions

Build Targets

make           # Standard build
make normal    # Build with debug flags  
make clean     # Remove object files
make fclean    # Remove all generated files
make re        # Clean rebuild

Memory Safety

# Check for memory leaks
valgrind --leak-check=full --track-origins=yes ./minishell

# With readline suppression
valgrind --leak-check=full --suppressions=readline.supp ./minishell

🎓 Educational Value

This project is an excellent learning resource for:

Systems Programming Concepts

  • Process creation and management (fork, exec, wait)
  • Inter-process communication (pipes, signals)
  • File descriptor manipulation
  • Memory management in C

Parsing & Language Design

  • Lexical analysis and tokenization
  • Recursive descent parsing
  • Abstract Syntax Tree construction
  • Context-sensitive grammar handling

Unix System Interface

  • Environment variable management
  • Signal handling (SIGINT, SIGQUIT)
  • File system operations
  • Terminal I/O with readline

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Setup

git clone https://github.com/Yo-omega/mini-shell.git
cd mini-shell
make normal    # Build with debug symbols

Contribution Guidelines

  1. 🍴 Fork the repository
  2. 🌟 Create a feature branch (git checkout -b feature/amazing-feature)
  3. 💻 Commit your changes (git commit -m 'Add amazing feature')
  4. 📤 Push to the branch (git push origin feature/amazing-feature)
  5. 🎯 Open a Pull Request

Code Style

  • Follow 42 Norm coding standards
  • Use clear, descriptive variable names
  • Add comments for complex logic
  • Ensure zero memory leaks

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

Author GitHub Role
yel-bouz @Yo-omega Core Developer
maddame @maddame Core Developer

🎉 Built with ❤️ at 1337FIL School

🙏 Acknowledgments

  • 🏫 1337 for providing the learning environment
  • 📚 GNU Bash for inspiration and reference behavior
  • 🛠️ GNU Readline library for line editing capabilities
  • 🌟 Open Source Community for tools and resources

🚀 Ready to explore the power of MiniShell?

git clone https://github.com/Yo-omega/mini-shell.git
cd mini-shell && make && ./minishell

Happy Coding! 🎉

If you found this project helpful, please consider giving it a ⭐ star!