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 Please wrap documentation at 72 characters-per-line or less (long URLs
  54 are exempt) so it is comfortably readable from terminals.
  55
  56 When referencing mailing list posts, use
  57 <tt>https://yhbt.net/unicorn-public/$MESSAGE_ID/</tt> if possible
  58 since the Message-ID remains searchable even if a particular site
  59 becomes unavailable.
  60
  61 === Ruby/C Compatibility
  62
  63 We target C Ruby 2.0 and later.  We need the Ruby
  64 implementation to support fork, exec, pipe, UNIX signals, access to
  65 integer file descriptors and ability to use unlinked files.
  66
  67 All of our C code is OS-independent and should run on compilers
  68 supported by the versions of Ruby we target.
  69
  70 === Ragel Compatibility
  71
  72 We target the latest released version of Ragel and will update our code
  73 to keep up with new releases.  Packaged tarballs and gems include the
  74 generated source code so they will remain usable if compatibility is
  75 broken.
  76
  77 == Contributing
  78
  79 Contributions are welcome in the form of patches, pull requests, code
  80 review, testing, documentation, user support or any other feedback is
  81 welcome.  The mailing list is the central coordination point for all
  82 user and developer feedback and bug reports.
  83
  84 === Submitting Patches
  85
  86 Follow conventions already established in the code and do not exceed 80
  87 characters per line.
  88
  89 Inline patches (from "git format-patch -M") to the mailing list are
  90 preferred because they allow code review and comments in the reply to
  91 the patch.
  92
  93 We will adhere to mostly the same conventions for patch submissions as
  94 git itself.  See the
  95 {SubmittingPatches}[https://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches]
  96 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 == Building a Gem
 101
 102 You can build the Unicorn gem with the following command:
 103
 104   gmake gem
 105
 106 == Running Development Versions
 107
 108 It is easy to install the contents of your git working directory:
 109
 110 Via RubyGems
 111
 112   gmake install-gem