HACKING

   1 = Unicorn Hacker's Guide
   2
   3 == Polyglot Infrastructure
   4
   5 Like Mongrel, we use Ruby where it makes sense, and Ragel with C where
   6 it helps performance.  All of the code that actually runs your Rack
   7 application is written Ruby, Ragel or C.
   8
   9 As far as tests and documentation goes, we're not afraid to embrace Unix
  10 and use traditional Unix tools where they make sense and get the job
  11 done.
  12
  13 === Tests
  14
  15 Tests are good, but slow tests make development slow, so we make tests
  16 faster (in parallel) with GNU make (instead of Rake) and avoiding
  17 Rubygems.
  18
  19 Since we don't load RubyGems by default, loading Rack properly requires
  20 setting up RUBYLIB to point to where Rack is located.  Not loading
  21 Rubygems drastically lowers the time to run the full test suite.  You
  22 may setup a "local.mk" file in the top-level working directory to setup
  23 your RUBYLIB and any other environment variables.  A "local.mk.sample"
  24 file is provided for reference.
  25
  26 Running the entire test suite with 4 tests in parallel:
  27
  28   make -j4 test
  29
  30 Running just one unit test:
  31
  32   make test/unit/test_http_parser.rb
  33
  34 Running just one test case in a unit test:
  35
  36   make test/unit/test_http_parser.rb--test_parse_simple.n
  37
  38 === HttpServer
  39
  40 We strive to write as little code as possible while still maintaining
  41 readability.  However, readability and flexibility may be sacrificed for
  42 performance in hot code paths.  For Ruby, less code generally means
  43 faster code.
  44
  45 Memory allocation should be minimized as much as practically possible.
  46 Buffers for IO#readpartial are preallocated in the hot paths to avoid
  47 building up garbage.  Hash assignments use frozen strings to avoid the
  48 duplication behind-the-scenes.
  49
  50 We spend as little time as possible inside signal handlers and instead
  51 defer handling them for predictability and robustness.  Most of the
  52 Unix-specific things are in the Unicorn::HttpServer class.  Unix systems
  53 programming experience will come in handy (or be learned) here.
  54
  55 === Documentation
  56
  57 We use RDoc 2.4.x with Darkfish for documentation as much as possible,
  58 if you're on Ruby 1.8 you want to install the latest "rdoc" gem.  Due to
  59 the lack of RDoc-to-manpage converters we know about, we're writing
  60 manpages in Markdown and converting to troff/HTML with Pandoc.
  61
  62 === Ruby/C Compatibility
  63
  64 We target Ruby 1.8.6+, 1.9 and will target Rubinius as it becomes
  65 production-ready.  We need the Ruby implementation to support fork,
  66 exec, pipe, UNIX signals, access to integer file descriptors and
  67 ability to use unlinked files.
  68
  69 All of our C code is OS-independent and should run on compilers
  70 supported by the versions of Ruby we target.
  71
  72 === Ragel Compatibility
  73
  74 We target the latest released version of Ragel and will update our code
  75 to keep up with new releases.  Packaged tarballs and gems include the
  76 generated source code so they will remain usable if compatibility is
  77 broken.
  78
  79 == Contributing
  80
  81 Contributions are welcome in the form of patches, pull requests, code
  82 review, testing, documentation, user support or any other feedback is
  83 welcome.  The mailing list is the central coordination point for all
  84 user and developer feedback and bug reports.
  85
  86 === Submitting Patches
  87
  88 Follow conventions already established in the code and do not exceed 80
  89 characters per line.
  90
  91 Inline patches (from "git format-patch") to the mailing list are
  92 preferred because they allow code review and comments in the reply to
  93 the patch.
  94
  95 We will adhere to mostly the same conventions for patch submissions as
  96 git itself.  See the Documentation/SubmittingPatches document
  97 distributed with git on on patch submission guidelines to follow.  Just
  98 don't email the git mailing list or maintainer with Unicorn patches :)
  99
 100 == Running Development Versions
 101
 102 It is easy to install the contents of your git working directory:
 103
 104 Via RubyGems (RubyGems 1.3.5+ recommended for prerelease versions):
 105
 106   make install-gem
 107
 108 Without RubyGems (via setup.rb):
 109
 110   make install
 111
 112 It is not at all recommended to mix a RubyGems installation with an
 113 installation done without RubyGems, however.