JezK
Edit File: page-HACKING.ri
U:RDoc::TopLevel[ i I"HACKING:ETcRDoc::Parser::Simpleo:RDoc::Markup::Document:@parts[QS:RDoc::Markup::Heading: leveli: textI"Unicorn Hacker's Guide;To:RDoc::Markup::BlankLine S; ; i;I"Polyglot Infrastructure;T@ o:RDoc::Markup::Paragraph;[I"LLike Mongrel, we use Ruby where it makes sense, and Ragel with C where ;TI"Iit helps performance. All of the code that actually runs your Rack ;TI"-application is written Ruby, Ragel or C.;T@ o; ;[I"NAs far as tests and documentation goes, we're not afraid to embrace Unix ;TI"Jand use traditional Unix tools where they make sense and get the job ;TI" done.;T@ S; ; i;I" Tests;T@ o; ;[I"LTests are good, but slow tests make development slow, so we make tests ;TI"Gfaster (in parallel) with GNU make (instead of Rake) and avoiding ;TI"RubyGems.;T@ o; ;[I"JUsers of GNU-based systems (such as GNU/Linux) usually have GNU make ;TI",installed as "make" instead of "gmake".;T@ o; ;[I"<Running the entire test suite with 4 tests in parallel:;T@ o:RDoc::Markup::Verbatim;[I"gmake -j4 check ;T:@format0o; ;[I" Running just one unit test:;T@ o;;[I")gmake test/unit/test_http_parser.rb ;T;0o; ;[I"/Running just one test case in a unit test:;T@ o;;[I">gmake test/unit/test_http_parser.rb--test_parse_simple.n ;T;0S; ; i;I"HttpServer;T@ o; ;[ I"KWe strive to write as little code as possible while still maintaining ;TI"Nreadability. However, readability and flexibility may be sacrificed for ;TI"Iperformance in hot code paths. For Ruby, less code generally means ;TI"faster code.;T@ o; ;[ I"LMemory allocation should be minimized as much as practically possible. ;TI"KBuffers for IO#readpartial are preallocated in the hot paths to avoid ;TI"Lbuilding up garbage. Hash assignments use frozen strings to avoid the ;TI"#duplication behind-the-scenes.;T@ o; ;[ I"LWe spend as little time as possible inside signal handlers and instead ;TI"Idefer handling them for predictability and robustness. Most of the ;TI"NUnix-specific things are in the Unicorn::HttpServer class. Unix systems ;TI"Dprogramming experience will come in handy (or be learned) here.;T@ S; ; i;I"Documentation;T@ o; ;[I"HDue to the lack of RDoc-to-manpage converters we know about, we're ;TI"Kwriting manpages in Markdown and converting to troff/HTML with Pandoc.;T@ o; ;[I"LPlease wrap documentation at 72 characters-per-line or less (long URLs ;TI">are exempt) so it is comfortably readable from terminals.;T@ o; ;[ I".When referencing mailing list posts, use ;TI"K<tt>https://bogomips.org/unicorn-public/$MESSAGE_ID/</tt> if possible ;TI"Gsince the Message-ID remains searchable even if a particular site ;TI"becomes unavailable.;T@ S; ; i;I"Ruby/C Compatibility;T@ o; ;[I"@We target mainline Ruby 1.9.3 and later. We need the Ruby ;TI"Iimplementation to support fork, exec, pipe, UNIX signals, access to ;TI"@integer file descriptors and ability to use unlinked files.;T@ o; ;[I"EAll of our C code is OS-independent and should run on compilers ;TI"1supported by the versions of Ruby we target.;T@ S; ; i;I"Ragel Compatibility;T@ o; ;[ I"MWe target the latest released version of Ragel and will update our code ;TI"Kto keep up with new releases. Packaged tarballs and gems include the ;TI"Jgenerated source code so they will remain usable if compatibility is ;TI"broken.;T@ S; ; i;I"Contributing;T@ o; ;[ I"KContributions are welcome in the form of patches, pull requests, code ;TI"Kreview, testing, documentation, user support or any other feedback is ;TI"Jwelcome. The mailing list is the central coordination point for all ;TI"1user and developer feedback and bug reports.;T@ S; ; i;I"Submitting Patches;T@ o; ;[I"MFollow conventions already established in the code and do not exceed 80 ;TI"characters per line.;T@ o; ;[I"IInline patches (from "git format-patch -M") to the mailing list are ;TI"Kpreferred because they allow code review and comments in the reply to ;TI"the patch.;T@ o; ;[I"LWe will adhere to mostly the same conventions for patch submissions as ;TI"git itself. See the ;TI"g{SubmittingPatches}[https://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches] ;TI"document ;TI"Mdistributed with git on on patch submission guidelines to follow. Just ;TI"Kdon't email the git mailing list or maintainer with Unicorn patches :);T@ S; ; i;I"Building a Gem;T@ o; ;[I"JIn order to build the gem, you must install the following components:;T@ o;;[I"* pandoc ;T;0o; ;[I">You can build the Unicorn gem with the following command:;T@ o;;[I"gmake gem ;T;0S; ; i;I"!Running Development Versions;T@ o; ;[I"FIt is easy to install the contents of your git working directory:;T@ o; ;[I"Via RubyGems;T@ o;;[I"gmake install-gem;T;0: @file@:0@omit_headings_from_table_of_contents_below0