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