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