Ronin Coreutils

A collection of Unix-like command-line utilities implemented from scratch in C.

Ronin Coreutils is a systems-programming project that recreates common Unix command-line utilities using C and POSIX APIs.

The project is built from scratch with a focus on understanding how fundamental Unix tools work internally rather than simply wrapping existing system commands.

---

🚧 Project Status

Active development

The project is currently in its early development stage. Core utilities are being implemented incrementally, tested, and improved over time.

Current implementations include:

• ls
• pwd
• echo
• cat
• head
• tail
• cp
• mkdir
• mc

More utilities will be added as development continues.

The list above represents the current implementation status and is intentionally kept concise. New utilities do not require rewriting the README structure.

---

🎯 Goals

The main goal of Ronin Coreutils is to build a growing collection of practical Unix utilities while gaining deeper experience with systems programming.

Primary goals

• Learn and practice modern C programming
• Understand POSIX APIs
• Work directly with files and directories
• Learn Unix filesystem concepts
• Understand standard streams
• Practice command-line argument handling
• Implement proper error handling
• Learn file descriptors and low-level I/O
• Build utilities that can work together through Unix pipelines
• Eventually achieve broad Unix/POSIX compatibility

---

🧰 Implemented Utilities

The project follows a simple structure where each utility is implemented independently.

Utility	Purpose
ls	List directory contents
pwd	Print the current working directory
echo	Print text to standard output
cat	Read and concatenate files
head	Display the beginning of files
tail	Display the end of files
cp	Copy files
mkdir	Create directories
mc	Custom utility

This table will grow as new utilities are implemented.

---

🗂️ Project Structure

ronin-coreutils/
│
├── src/
│   ├── ls.c
│   ├── pwd.c
│   ├── echo.c
│   ├── cat.c
│   ├── head.c
│   ├── tail.c
│   ├── cp.c
│   ├── mkdir.c
│   └── mc.c
│
├── README.md
├── Makefile
└── LICENSE

Each command is kept as a separate C source file to make the project easy to understand, maintain, and extend.

---

🔨 Building

Clone the repository:

git clone https://github.com/YOUR_USERNAME/ronin-coreutils.git
cd ronin-coreutils

Build the project:

make

Then run the utilities directly:

./ls
./pwd
./echo "Hello World"
./cat file.txt
./head file.txt
./tail file.txt
./cp source.txt destination.txt
./mkdir test

Build commands may evolve as the project's build system becomes more complete.

---

💡 Design Philosophy

Ronin Coreutils follows a few simple principles.

1. Build, don't wrap

Utilities should be implemented using C/POSIX functionality instead of simply executing the corresponding system command.

For example, ls should use filesystem APIs such as:

opendir()
readdir()
closedir()

rather than:

system("ls");

2. Unix philosophy

Each utility should ideally:

• Do one thing well
• Read from standard input when appropriate
• Write to standard output
• Report errors through standard error
• Return meaningful exit codes
• Work naturally with other commands

3. Minimal dependencies

The project aims to rely primarily on:

• C standard library
• POSIX APIs
• Operating-system interfaces

External dependencies should be avoided unless they provide a clear benefit.

4. Learn from implementation

The project is not only about creating replacements for existing commands.

It is also about understanding what happens underneath the command line.

---

🔗 Unix Pipelines

A major long-term objective is to make the utilities behave naturally inside Unix pipelines.

For example:

./cat file.txt | ./head

or, once grep is implemented:

./ls | ./grep ".c"

This requires correct handling of:

stdin
stdout
stderr
exit codes
pipes

Pipeline compatibility will become increasingly important as the project grows.

---

🗺️ Roadmap

The roadmap is intentionally broad rather than tied to a fixed number of utilities.

File & Directory Operations

• ls
• pwd
• cp
• mkdir
• mv
• rm
• rmdir
• touch
• ln
• readlink

Text Processing

• cat
• head
• tail
• grep
• wc
• sort
• uniq
• cut
• tr
• tee

System Utilities

• chmod
• chown
• stat
• df
• du
• date
• sleep
• whoami
• id

Advanced Utilities

• find
• xargs
• env
• which
• basename
• dirname
• realpath

Infrastructure

• Improve Makefile
• Automated tests
• POSIX compatibility tests
• Better argument parsing
• Consistent exit codes
• Memory-safety testing
• Static analysis
• CI
• Documentation / man pages
• Performance benchmarks

The roadmap is not a strict development schedule. Utilities may be added, redesigned, or reorganized as the project evolves.

---

🧪 Testing

Correctness is more important than simply making a command appear to work.

Where practical, Ronin Coreutils can be compared against the corresponding system utility.

Example:

./head file.txt > ronin-output.txt
head file.txt > system-output.txt

diff ronin-output.txt system-output.txt

Future automated tests will cover areas such as:

• Normal input
• Empty files
• Large files
• Missing files
• Invalid arguments
• Permission errors
• Multiple input files
• Standard input
• Pipelines
• Exit codes

---

🧠 What This Project Teaches

Working on Ronin Coreutils provides practical experience with:

• C
• Pointers
• Memory management
• File descriptors
• Filesystem operations
• Directory traversal
• POSIX APIs
• System calls
• Standard streams
• Command-line arguments
• Error handling
• Exit codes
• Processes
• Pipes
• File permissions
• Unix filesystem behavior

---

📈 Development Approach

The project is developed incrementally.

A typical utility goes through:

Idea
  ↓
Basic implementation
  ↓
Compilation
  ↓
Manual testing
  ↓
Error handling
  ↓
Argument handling
  ↓
Compatibility improvements
  ↓
Tests

This means an early implementation may intentionally be simpler than the equivalent GNU utility.

---

⚠️ Compatibility

Ronin Coreutils is not currently a drop-in replacement for GNU Coreutils.

The goal is to progressively improve compatibility with common Unix behavior while keeping the source code understandable.

Behavior, available options, and supported platforms may differ from GNU implementations.

---

🖥️ Platform

The primary target is:

• Linux
• Unix-like systems

POSIX compatibility is a long-term goal.

Platform-specific code may be introduced when necessary, but portability is preferred whenever practical.

---

🤝 Contributing

Contributions, ideas, bug reports, and improvements are welcome.

Adding a new utility

A typical contribution should:

1. Add the utility under src/
2. Follow the project's C coding style
3. Handle errors properly
4. Avoid unnecessary dependencies
5. Add or update tests when appropriate
6. Update the utility list in README.md if needed

Example:

git checkout -b feature/add-grep

After implementation:

git add .
git commit -m "feat: add grep utility"
git push origin feature/add-grep

Then open a Pull Request.

---

📜 License

This project is licensed under the MIT License.

See LICENSE for details.

---

👤 Author

ParsaAzima

C • C++ • Python • Linux • Systems Programming • Cybersecurity

---

⭐ Philosophy

Don't just use Unix tools. Understand them. Build them.

Ronin Coreutils is a journey from using the command line to understanding the software behind it.

Built with C, Linux, and curiosity. 🐧