SWAMPy

✎ CARVE FLESH

EDITING: BuildSystem.md

# Build system

Our build system is [Rake](https://github.com/ruby/rake). Its functionality is similar to Make, but its DSL is in Ruby. `passenger-install-apache2-module` and `passenger-install-nginx-module` call Rake to compile things.

## Key Rake targets

- `rake apache2` — compiles the Apache 2 module, and other parts needed by the Apache integration mode (e.g., the Passenger agent binary).
- `rake nginx` — compiles parts needed by the Nginx integration mode (e.g., agent binary). Does *not* compile the Nginx module.
- For test suite targets, see [Running tests](RunningTests.md).

See more with `rake -T`.

## Concurrent compilation

Run `rake -m -j<NUMBER>` for concurrent compilation. `<NUMBER>` should equal the number of CPU cores.

## Environment variables

You can pass environment variables via CLI arguments. These are equivalent:

```bash
rake something FOO=123

export FOO=123 && rake something
```

You can persist environment variables in `config.rb`. This file is automatically loaded by Rake.

```ruby
# config.rb
ENV['FOO'] = '123'
```

## Customization

Customize the build system with environment variables. Boolean options can be set to true, false, 0 or 1.

- `OUTPUT_DIR`: where build output is placed. Default: `buildout/`
- `EXTRA_PRE_CFLAGS` and `EXTRA_CFLAGS`: insert additional flags to C compiler invocations. One for before our own flags, one for after. Does not cover linking invocations.
- `EXTRA_PRE_CXXFLAGS` and `EXTRA_CXXFLAGS`: ditto, but for C++ compiler invocations.
- `EXTRA_PRE_LDFLAGS` and `EXTRA_LDFLAGS`: insert additional flags to C/C++ compiler linking invocations. One for before our own flags, one for after.
- `EXTRA_PRE_C_LDFLAGS` and `EXTRA_C_LDFLAGS`: ditto, but only applies to C compiler linking invocations.
- `EXTRA_PRE_CXX_LDFLAGS` and `EXTRA_CXX_LDFLAGS`: ditto, but only applies to C++ compiler linking invocations.
- `USE_CCACHE=<bool>` (default: false): wrap compiler invocations in ccache. See also [ccache setup instructions](DevEnvironmentSetup.md#build-caching).
- `USE_ASAN=<bool>` (default: false): compile with AddressSanitizer.
- `USE_UBSAN=<bool>` (default: false): compile with UndefinedBehaviorSanitizer.
- `OPTIMIZE=<bool>` (default: false): compile with optimizations.
- `USE_VENDORED_LIBEV=<bool>` (default: true): set to false to compile with system-provided libev instead of our vendored one.
- `USE_VENDORED_LIBUV=<bool>` (default: true): set to false to compile with system-provided libuv instead of our vendored one.

CANCEL

Name	Type	Size	Modified	Actions
↩ ..	DIR	—	—
📁 DesignAspects/	DIR	—	2026-10-30 12:14
📁 images/	DIR	—	2026-10-30 12:14
📁 templates/	DIR	—	2026-10-30 12:14
📄 AiInstructions.md	MD	6.6 KB	2026-10-21 10:21	EDIT
📄 BasicArchitectureOverview.md	MD	2.8 KB	2026-10-21 10:21	EDIT
📄 BuildCaching.md	MD	631 B	2026-10-21 10:21	EDIT
📄 BuildSystem.md	MD	2.4 KB	2026-10-21 10:21	EDIT
📄 CodingTipsAndPitfalls.md	MD	2.9 KB	2026-10-21 10:21	EDIT
📄 CxxMockingStrategy.md	MD	982 B	2026-10-21 10:21	EDIT
📄 DebuggingAndStressTesting.md	MD	5.1 KB	2026-10-21 10:21	EDIT
📄 DevEnvironmentSetup.md	MD	1.4 KB	2026-10-21 10:21	EDIT
📄 DevHandbook.md	MD	3.3 KB	2026-10-21 10:21	EDIT
📄 Packaging.md	MD	12.5 KB	2026-10-21 10:21	EDIT
📄 RunningTests.md	MD	2.7 KB	2026-10-21 10:21	EDIT
📄 SecureTempFileHandling.md	MD	804 B	2026-10-21 10:21	EDIT
📄 WritingCxxTests.md	MD	2.6 KB	2026-10-21 10:21	EDIT