Unicorn Hacker's Guide
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 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".
Running the entire test suite with 4 tests in parallel:
gmake -j4 check
Running just one unit test:
Running just one test case in a unit test:
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.
Please wrap documentation at 72 characters-per-line or less (long URLs are exempt) so it is comfortably readable from terminals.
When referencing mailing list posts, use
https://yhbt.net/unicorn-public/$MESSAGE_ID/ if possible since the Message-ID remains searchable even if a particular site becomes unavailable.
We target C Ruby 2.0 and later. 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.
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.
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.
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 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 :)
You can build the
Unicorn gem with the following command:
It is easy to install the contents of your git working directory:
mail archives: https://yhbt.net/unicorn-public/ http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/unicorn-public/ nntps://news.public-inbox.org/inbox.comp.lang.ruby.unicorn nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.unicorn nntp://news.gmane.io/gmane.comp.lang.ruby.unicorn.general imaps://;AUTH=ANONYMOUS@yhbt.net/inbox.comp.lang.ruby.unicorn.0 imap://;AUTH=ANONYMOUS@7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.unicorn.0 public: firstname.lastname@example.org source code: git clone https://yhbt.net/unicorn.git torsocks git clone http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/unicorn.git