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 Users of GNU-based systems (such as GNU/Linux) usually have GNU make
  20 installed as "make" instead of "gmake".
  21
  22 Since we don't load RubyGems by default, loading Rack properly requires
  23 setting up RUBYLIB to point to where Rack is located.  Not loading
  24 RubyGems drastically lowers the time to run the full test suite.  You
  25 may setup a "local.mk" file in the top-level working directory to setup
  26 your RUBYLIB and any other environment variables.  A "local.mk.sample"
  27 file is provided for reference.
  28
  29 Running the entire test suite with 4 tests in parallel:
  30
  31   gmake -j4 check
  32
  33 Running just one unit test:
  34
  35   gmake test/unit/test_http_parser.rb
  36
  37 Running just one test case in a unit test:
  38
  39   gmake test/unit/test_http_parser.rb--test_parse_simple.n
  40
  41 === HttpServer
  42
  43 We strive to write as little code as possible while still maintaining
  44 readability.  However, readability and flexibility may be sacrificed for
  45 performance in hot code paths.  For Ruby, less code generally means
  46 faster code.
  47
  48 Memory allocation should be minimized as much as practically possible.
  49 Buffers for IO#readpartial are preallocated in the hot paths to avoid
  50 building up garbage.  Hash assignments use frozen strings to avoid the
  51 duplication behind-the-scenes.
  52
  53 We spend as little time as possible inside signal handlers and instead
  54 defer handling them for predictability and robustness.  Most of the
  55 Unix-specific things are in the Unicorn::HttpServer class.  Unix systems
  56 programming experience will come in handy (or be learned) here.
  57
  58 === Documentation
  59
  60 We use RDoc 2.5.x with Darkfish for documentation as much as possible,
  61 if you're on Ruby 1.8 you want to install the latest "rdoc" gem.  Due to
  62 the lack of RDoc-to-manpage converters we know about, we're writing
  63 manpages in Markdown and converting to troff/HTML with Pandoc.
  64
  65 Please wrap documentation at 72 characters-per-line or less (long URLs
  66 are exempt) so it is comfortably readable from terminals.
  67
  68 When referencing mailing list posts, use
  69 "http://bogomips.org/unicorn-public/m/$MESSAGE_ID.html" if possible
  70 since the Message-ID remains searchable even if a particular site
  71 becomes unavailable.
  72
  73 === Ruby/C Compatibility
  74
  75 We target Ruby 1.8.6+, 1.9 and will target Rubinius as it becomes
  76 production-ready.  We need the Ruby implementation to support fork,
  77 exec, pipe, UNIX signals, access to integer file descriptors and
  78 ability to use unlinked files.
  79
  80 All of our C code is OS-independent and should run on compilers
  81 supported by the versions of Ruby we target.
  82
  83 === Ragel Compatibility
  84
  85 We target the latest released version of Ragel and will update our code
  86 to keep up with new releases.  Packaged tarballs and gems include the
  87 generated source code so they will remain usable if compatibility is
  88 broken.
  89
  90 == Contributing
  91
  92 Contributions are welcome in the form of patches, pull requests, code
  93 review, testing, documentation, user support or any other feedback is
  94 welcome.  The mailing list is the central coordination point for all
  95 user and developer feedback and bug reports.
  96
  97 === Submitting Patches
  98
  99 Follow conventions already established in the code and do not exceed 80
 100 characters per line.
 101
 102 Inline patches (from "git format-patch -M") to the mailing list are
 103 preferred because they allow code review and comments in the reply to
 104 the patch.
 105
 106 We will adhere to mostly the same conventions for patch submissions as
 107 git itself.  See the
 108 {SubmittingPatches}[https://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches]
 109 document
 110 distributed with git on on patch submission guidelines to follow.  Just
 111 don't email the git mailing list or maintainer with Unicorn patches :)
 112
 113 == Building a Gem
 114
 115 In order to build the gem, you must install the following components:
 116
 117  * wrongdoc
 118  * pandoc
 119
 120 You can build the Unicorn gem with the following command:
 121
 122   gmake gem
 123
 124 == Running Development Versions
 125
 126 It is easy to install the contents of your git working directory:
 127
 128 Via RubyGems (RubyGems 1.3.5+ recommended for prerelease versions):
 129
 130   gmake install-gem
 131
 132 Without RubyGems (via setup.rb):
 133
 134   gmake install
 135
 136 It is not at all recommended to mix a RubyGems installation with an
 137 installation done without RubyGems, however.