Developers information

Required software

The tests need the following software installed:

  • All the usual Phusion Passenger dependencies.
  • Ruby on Rails 1.2.x
  • Ruby on Rails 2.0.x
  • Ruby on Rails 2.2.x
  • Ruby on Rails 2.3.x
  • Ruby on Rails 3.0.x
  • rspec >= 1.1.2
  • mime-types >= 1.15
  • sqlite3-ruby

The following software is optional:

  • RCov, for code coverage
  • RDoc, for generating HTML Ruby API documentation
  • Doxygen, for generating HTML C++ API documentation
  • dot (part of Graphviz), for generating diagrams in HTML API documentation
  • The font "Bitstream Vera Sans", used in the class diagrams. See www.gnome.org/fonts
  • AsciiDoc >= 8.2.5, for converting various doc/*.txt documents to HTML

Compiling Phusion Passenger

Run the following command to compile everything:

 rake

Directory structure

The most important directories are:

lib/phusion_passenger
The source code for the spawn server, which is written in Ruby.
ext/phusion_passenger
Native extensions for Ruby, used by the spawn server.
ext/apache2
Apache 2-specific source code.
ext/nginx
Nginx-specific source code.
ext/common
Source code shared by the Apache and Nginx modules.
bin
Executables.
doc
Various documentation.
test
Unit tests and integration tests.
test/support
Support/utility code, used in the tests.
test/stub
Stub code, used in the tests.

Less important directories:

ext/boost
A stripped-down and customized version of the Boost C++ library (www.boost.org).
ext/oxt
The "OS eXtensions for boosT" library, which provides various important functionality necessary for writing robust server software. It provides things like support for interruptable system calls and portable backtraces for C++. Boost was modified to make use of the functionality provided by OXT.
benchmark
Benchmark tools.
debian
Debian packaging files.
man
Man pages.
misc
Miscellaneous tools.
build
Rake tasks used by the build system.

Tests

Run all tests:

 rake test

Run only the unit tests for the C++ components:

 rake test:cxx

Run just the unit tests for the Ruby spawn server:

 rake test:ruby

Run just the integration tests:

 rake test:integration            # All integration tests.
 rake test:integration:apache2    # Just integration tests for Apache 2.
 rake test:integration:nginx      # Just integration tests for Nginx.

Notes:

  • Some tests, such as the ones that test privilege lowering, require root privileges. Those will only be run if Rake is run as root.
  • Some tests will be run against multiple Rails versions in order to test compatibility. This can take a long time. If you want to test against only a single Rails version, then set the environment variable ONLY_RAILS_VERSION to one of the subdirectory names in test/stub/rails_apps, e.g. ‘export ONLY_RAILS_VERSION=2.3‘

Documentation

Various developer documents can be found in ‘doc/*.html’.

The Ruby part‘s API reference is located in ‘doc/rdoc/’. The C++ part‘s API reference is located in ‘doc/cxxapi/’.