How raslan07/codecrafters-shell-cpp works
1. Repository purpose
- This is a C++ starter repository for a CodeCrafters “Build Your Own Shell” challenge.
- The intended product is a POSIX-like shell that reads commands, parses them, runs builtins, and launches external programs.
2. Core application boundary
- The only application source file shown is src/main.cpp.
- That file is the primary runtime entry point and is where the shell implementation lives.
- For an architecture diagram, treat main.cpp as the center of the system: input loop, command handling, and process execution all originate there.
3. Build system
- The project uses CMake (CMakeLists.txt) as the build orchestrator.
- CMake is the main boundary between source code and the compiled executable.
- This is a single-binary style project rather than a multi-service system.
4. Dependency management
- The repo includes vcpkg.json and vcpkg-configuration.json, so external C++ dependencies are managed through vcpkg.
- In architecture terms, this means third-party libraries are resolved at build time, not through a runtime package manager or service dependency.
5. Execution wrapper
- your_program.sh is the local run script called by the challenge tooling.
- It serves as the stable command entrypoint for running the compiled shell during development and evaluation.
- The actual executable behavior still comes from the C++ program in src/main.cpp.
6. Codecrafters integration
- The .codecrafters/compile.sh and .codecrafters/run.sh scripts are infrastructure adapters used by the CodeCrafters platform.
- They wrap the local build/run process so the platform can compile and execute the solution consistently.
- These scripts are not application logic; they are part of the test harness boundary.
7. Runtime interaction model
- The shell is expected to be interactive: it reads user input from standard input, emits prompts/output to standard output, and may invoke child processes.
- Important data flow for the eventual implementation: terminal input → parsing/dispatch → builtin handling or external process execution → terminal output.
8. Shell-specific functional subsystems
- Even though the current repo is mostly scaffolding, the target architecture implied by the challenge includes:
- command parser
- builtin command dispatcher
- external command launcher
- REPL loop
- These are logical modules that will likely be implemented inside src/main.cpp or split into additional source files later.
9. What is not present
- There is no evidence of a network layer, database, message queue, or web frontend.
- This is a local CLI application with build/test automation around it, not a distributed system.
10. Practical diagram framing
- A clear diagram would show:
- developer / CodeCrafters test runner at the top
- build scripts and CMake as the build path
- the compiled shell executable in the middle
- stdin/stdout/stderr and spawned child processes as the runtime interfaces
- The repo’s main architectural distinction is between implementation code (src/main.cpp) and evaluation/tooling (.codecrafters/*, your_program.sh, CMake/vcpkg files).
Main entry points: compile.sh Compile script · run.sh Run script · your_program.sh Program script · CMakeLists.txt CMake
Components 15
Tooling
Challenge and local execution adapters around the shell implementation
- Developer · Local developer or CodeCrafters test runner triggering the repo workflow
- Compile script · CodeCrafters wrapper for building the solution
.codecrafters/compile.sh - Run script · CodeCrafters wrapper for running the solution
.codecrafters/run.sh - Program script · Stable local entrypoint used to launch the compiled shell
your_program.sh
Build
CMake and vcpkg boundary that produces the executable
- CMake · Primary build orchestrator for the single-binary C++ project
CMakeLists.txt - vcpkg manifest · Declares third-party C++ dependencies
vcpkg.json - vcpkg config · Configures vcpkg resolution for the build
vcpkg-configuration.json
Runtime
Interactive shell loop and command execution flow
- Shell binary · The built command-line program produced from the C++ source
- Main shell · Primary application code and runtime center of the shell
src/main.cpp - REPL loop · Reads commands and drives the shell session
- Terminal I/O · Standard input, output, and error used by the shell
- Command parser · Turns raw input into executable command structure
- Builtin dispatcher · Handles shell-native commands without spawning a child process
- Process launcher · Resolves and starts external programs
- Child process · External command executed by the shell
Connections 20
- Developer → Compile script: builds · The platform or developer invokes the compilation wrapper
- Developer → Run script: runs · The platform or developer invokes the runtime wrapper
- Developer → Program script: executes · Local workflow entrypoint for the compiled shell
- Compile script → CMake: invokes · Compile wrapper delegates to the CMake build
- Compile script → vcpkg manifest: resolves deps · Build uses the dependency manifest during compilation
- Compile script → vcpkg config: configures deps · Build uses vcpkg configuration for dependency resolution
- CMake → Shell binary: produces · CMake compiles the executable artifact
- vcpkg manifest → Shell binary: links deps · Third-party libraries are made available at build time
- vcpkg config → Shell binary: links deps · vcpkg configuration influences dependency resolution
- Program script → Shell binary: launches · Run script starts the compiled executable
- Run script → Shell binary: launches · CodeCrafters runtime wrapper starts the program
- Shell binary → Main shell: contains · The binary is built from the shell implementation
- Main shell → REPL loop: drives · Main application logic centers on the interactive loop
- REPL loop → Terminal I/O: reads/writes · Loop consumes stdin and emits prompts and results
- REPL loop → Command parser: parses · Each user command is parsed before dispatch
- Command parser → Builtin dispatcher: dispatches · Parsed commands may be handled by builtins
- Command parser → Process launcher: dispatches · Non-builtin commands are sent to external execution
- Builtin dispatcher → Terminal I/O: outputs · Builtins write results back to the terminal
- Process launcher → Child process: spawns · External commands execute in a child process
- Child process → Terminal I/O: streams · Child process uses the shell's standard streams