= 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 http://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.
[ misc/rake ]
  Rake tasks.

== 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/'.