23s2s

✏️ Editing: DevHandbook.md

# Passenger development handbook

## Fundamentals

- [Basic architecture overview](BasicArchitectureOverview.md)
- [Development environment setup](DevEnvironmentSetup.md) — Prerequisites for C++, Ruby, Node.js, Apache, and Nginx work; test setup; clangd, ccache, and debugger configuration.
- [Build system](BuildSystem.md) — How it works, how to compile various parts of Passenger. Rake targets for Apache and Nginx integration, output and compiler/linker settings, sanitizers, optimization, and vendored libev/libuv controls. Recommended Rake flags for concurrent building. Instructions for persisting dev-time environment variables (loaded by Rake).
  - [Build caching](BuildCaching.md) — ccache setup.
- [Running tests](RunningTests.md) — Ruby, Node.js, C++/oxt, integration, and packaging test suites; selecting C++ groups or test numbers; debugger and Valgrind support; and root-only tests; safely running test suites directly (bypassing Rake); example test suite outputs.
- [Writing C++ tests](WritingCxxTests.md) — How C++ tests are structured; how our testing framework (forked tut) works; available assertions.
  - [C++ mocking strategy](CxxMockingStrategy.md)

## Best practices

- [Coding tips and common pitfalls](CodingTipsAndPitfalls.md) — C++ object-lifetime and event-loop hazards involving `shared_ptr`, callbacks, exceptions, and thread-interruption-safe RAII destructors.
- [Secure handling of temp files](SecureTempFileHandling.md) — Preventing symlink, file-squatting, and TOCTOU attacks through unpredictable names, atomic reservation, restrictive permissions, `mkstemp()`, and `mkdtemp()`.

## Design decisions & aspects

- [Limited gem dependencies](DesignAspects/LimitedGemDependencies.md) — Runtime Ruby dependency policy for gem and native-package installs, multiple Ruby versions, execution with or without Bundler, OS repository availability, and gemspec versus Gemfile placement.
- [No gem activation during Ruby loader initialization](DesignAspects/NoGemActivationDuringRubyLoaderInitialization.md) — No-activation rule for code called before Bundler by the Ruby loaders, including gemified standard-library code and Ruby/C++ reimplementation strategies.

## Subsystems in C++

- [ConfigKit](../src/cxx_supportlib/ConfigKit/README.md) — Core JSON configuration API covering runtime-introspectable schemas and stores, defaults, nested schemas, validation, normalization, updates, inspection, and secret filtering.
    - [ConfigKit practical usage & design patterns](../src/cxx_supportlib/ConfigKit/IN_PRACTICE.md) — Configurable-component patterns covering config realizations, subclassing and composition, translators, atomic prepare/commit with infallible commit, asynchronous event-loop wrappers, and concurrency serialization.
- [SpawningKit](../src/agent/Core/SpawningKit/README.md) — Reliably starting web application worker/preloader processes: spawn methods (direct/smart), wrappers/start commands, process environment and privilege setup, startup handshakes/readiness checks, timeouts, and detailed spawn-failure diagnostics.
- [Wrapper registry](../src/cxx_supportlib/WrapperRegistry/README.md) — Registry of supported application types and language wrappers: maps app type names/aliases to wrapper loader, interpreter, process title, and startup-file signatures used by application autodetection and spawning.

Sid Gifari From Gifari Industries - BD Cyber Security Team