unicorn.git  about / heads / tags
Rack HTTP server for Unix and fast clients
blob 6a05d4b1f60ca639003bde527fedba63eebaf45e 4125 bytes (raw)
$ git show v1.1.2:HACKING	# shows this blob on the CLI

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
= Unicorn Hacker's Guide

== Polyglot Infrastructure

Like Mongrel, we use Ruby where it makes sense, and Ragel with C where
it helps performance.  All of the code that actually runs your Rack
application is written Ruby, Ragel or C.

As far as tests and documentation goes, we're not afraid to embrace Unix
and use traditional Unix tools where they make sense and get the job
done.

=== Tests

Tests are good, but slow tests make development slow, so we make tests
faster (in parallel) with GNU make (instead of Rake) and avoiding
RubyGems.

Users of GNU-based systems (such as GNU/Linux) usually have GNU make installed
as "make" instead of "gmake".

Since we don't load RubyGems by default, loading Rack properly requires
setting up RUBYLIB to point to where Rack is located.  Not loading
RubyGems drastically lowers the time to run the full test suite.  You
may setup a "local.mk" file in the top-level working directory to setup
your RUBYLIB and any other environment variables.  A "local.mk.sample"
file is provided for reference.

Running the entire test suite with 4 tests in parallel:

  gmake -j4 test

Running just one unit test:

  gmake test/unit/test_http_parser.rb

Running just one test case in a unit test:

  gmake test/unit/test_http_parser.rb--test_parse_simple.n

=== HttpServer

We strive to write as little code as possible while still maintaining
readability.  However, readability and flexibility may be sacrificed for
performance in hot code paths.  For Ruby, less code generally means
faster code.

Memory allocation should be minimized as much as practically possible.
Buffers for IO#readpartial are preallocated in the hot paths to avoid
building up garbage.  Hash assignments use frozen strings to avoid the
duplication behind-the-scenes.

We spend as little time as possible inside signal handlers and instead
defer handling them for predictability and robustness.  Most of the
Unix-specific things are in the Unicorn::HttpServer class.  Unix systems
programming experience will come in handy (or be learned) here.

=== Documentation

We use RDoc 2.4.x with Darkfish for documentation as much as possible,
if you're on Ruby 1.8 you want to install the latest "rdoc" gem.  Due to
the lack of RDoc-to-manpage converters we know about, we're writing
manpages in Markdown and converting to troff/HTML with Pandoc.

=== Ruby/C Compatibility

We target Ruby 1.8.6+, 1.9 and will target Rubinius as it becomes
production-ready.  We need the Ruby implementation to support fork,
exec, pipe, UNIX signals, access to integer file descriptors and
ability to use unlinked files.

All of our C code is OS-independent and should run on compilers
supported by the versions of Ruby we target.

=== Ragel Compatibility

We target the latest released version of Ragel and will update our code
to keep up with new releases.  Packaged tarballs and gems include the
generated source code so they will remain usable if compatibility is
broken.

== Contributing

Contributions are welcome in the form of patches, pull requests, code
review, testing, documentation, user support or any other feedback is
welcome.  The mailing list is the central coordination point for all
user and developer feedback and bug reports.

=== Submitting Patches

Follow conventions already established in the code and do not exceed 80
characters per line.

Inline patches (from "git format-patch -M") to the mailing list are
preferred because they allow code review and comments in the reply to
the patch.

We will adhere to mostly the same conventions for patch submissions as
git itself.  See the Documentation/SubmittingPatches document
distributed with git on on patch submission guidelines to follow.  Just
don't email the git mailing list or maintainer with Unicorn patches :)

== Running Development Versions

It is easy to install the contents of your git working directory:

Via RubyGems (RubyGems 1.3.5+ recommended for prerelease versions):

  gmake install-gem

Without RubyGems (via setup.rb):

  gmake install

It is not at all recommended to mix a RubyGems installation with an
installation done without RubyGems, however.

git clone https://yhbt.net/unicorn.git