From 2730d875650ee8c3121d457743419dce7ce69aef Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Sat, 19 Sep 2009 19:01:03 -0700 Subject: Add HACKING document --- .document | 1 + HACKING | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 HACKING diff --git a/.document b/.document index a73dbea..a7632aa 100644 --- a/.document +++ b/.document @@ -1,6 +1,7 @@ README TUNING PHILOSOPHY +HACKING DESIGN CONTRIBUTORS LICENSE diff --git a/HACKING b/HACKING new file mode 100644 index 0000000..5085545 --- /dev/null +++ b/HACKING @@ -0,0 +1,98 @@ += 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. + +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: + + make -j4 test + +Running just one unit test: + + make test/unit/test_http_parser.rb + +Running just one test case in a unit test: + + make 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") 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 :) -- cgit v1.2.3-24-ge0c7