Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

add ruby packaging standard draft

  • Loading branch information...
commit 598186f6b00ad4fe2eb021027eed50328452e5e3 1 parent 4a0eb81
@yob authored
Showing with 172 additions and 0 deletions.
  1. +172 −0 doc/Ruby Packaging Standard, 0.5-draft.html
View
172 doc/Ruby Packaging Standard, 0.5-draft.html
@@ -0,0 +1,172 @@
+<!DOCTYPE HTML>
+<html><head>
+
+
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>Ruby Packaging Standard, 0.5-draft</title>
+ <style>
+body {
+ font: 14px/16px Corbel, Lucida Grande, serif;
+ background-color: #ffffff;
+ color: #000000;
+ margin: 2em;
+ max-width: 50em;
+}
+
+small {
+ font-size: 12px;
+}
+
+h1 {
+ font: 28px/32px Corbel, Lucida Grande, serif;
+}
+
+h2 {
+ font: bold 16px/32px Corbel, Lucida Grande, serif;
+ margin: 20px 0 12px 0;
+ padding: 0;
+}
+
+p {
+ padding: 0;
+ margin: 8px 0;
+}
+
+ol, ul {
+ margin: 0;
+ padding: 0;
+}
+
+pre, code {
+ font: 95% Consolas, Monaco, monospace;
+}
+
+pre {
+ margin-left: 40px;
+}
+ </style>
+ </head><body>
+<h1>Ruby Packaging Standard, 0.5-draft</h1>
+
+<p>The aim of this document is two-fold. First, to specify a common
+structure of how a Ruby package distributed as source (that is, but
+not limited to, development directories, version-controlled
+repositories, .tar.gz, Gems, …) should conform to.</p>
+
+<p>Second, to document common and proven ways to structure Ruby
+packages,
+and to point out certain anti-patterns that sneaked into common use.
+It is by intent not to innovate.</p>
+
+<p>(See <a href="http://www.ietf.org/rfc/rfc2119.txt"><small>RFC</small>
+ 2119</a> for use of
+<small>MUST</small>, <small>SHOULD</small>, <small>SHALL</small>.)</p>
+
+<h2>General</h2>
+
+<p>Project names <small>SHOULD</small> only contain underscores as
+separators in their names.</p>
+
+<p>If a project is an enhancement, plugin, extension, etc. for some
+other
+project it <small>SHOULD</small> contain a dash in the name between the
+original name
+and the project’s name.</p>
+
+<p>File names and directory structure <small>SHOULD</small> correspond
+like this:</p>
+
+<pre><code>Library: foo-bar
+Directory: lib/foo/bar
+Namespace: Foo::Bar
+
+Library: foo_bar
+Directory: lib/foo_bar
+Namespace: FooBar
+</code></pre>
+
+<h2>Library files</h2>
+
+<p>Library code <small>MUST</small> reside in <code>lib/</code>.</p>
+
+<p>Libraries <small>SHOULD</small> use a directory as namespace, e.g. <code>lib/foo.rb</code>
+ and
+<code>lib/foo/**</code>. (And, see above, thus limit their code to a
+module <code>Foo</code>.)</p>
+
+<p>Libraries <small>SHOULD</small> <small>NOT</small> require code of
+the project that are outside of <code>lib/</code>.</p>
+
+<p>Libraries <small>MUST</small> <small>NOT</small> <code>require
+'rubygems'</code> or modify the <code>$LOAD_PATH</code>,
+unless they are specifically made for doing that (e.g. package
+managers).</p>
+
+<p>Ruby library files <small>MUST</small> end with <code>.rb.</code></p>
+
+<p>Library files <small>SHOULD</small> be installed with mode 0644.</p>
+
+<h2>Executables</h2>
+
+<p>Executables <small>MUST</small> reside in <code>bin/</code>.</p>
+
+<p>Ruby executables <small>SHOULD</small> have a shebang line using <code>env</code>:</p>
+
+<pre><code>#!/usr/bin/env ruby
+</code></pre>
+
+<p>Executables <small>SHOULD</small> <small>NOT</small> require code of
+the project that are outside of <code>lib/</code>.</p>
+
+<p>Executables <small>SHOULD</small> <small>NOT</small> <code>require
+'rubygems'</code> or modify the <code>$LOAD_PATH</code>.</p>
+
+<p>Executable files <small>SHOULD</small> <small>NOT</small> end with <code>.rb</code>.</p>
+
+<p>Executable files <small>SHOULD</small> be installed with mode 0755.</p>
+
+<h2>Extensions</h2>
+
+<p>Extensions are directories which contain a <code>extconf.rb</code>.</p>
+
+<p>Extensions <small>SHOULD</small> reside in <code>ext/</code>.</p>
+
+<p>Extensions <small>SHOULD</small> be buildable with <code>ruby
+extconf.rb; make</code>.</p>
+
+<p>Files ending with <code>.so</code>, <code>.dylib</code>, <code>.bundle</code>,
+ <code>.dll</code>, <code>.exe</code> are
+considered compiled extensions to be installed.</p>
+
+<p>Extensions <small>SHOULD</small> be installed into an
+architecture-specific directory.</p>
+
+<h2>Data files</h2>
+
+<p>Data files and resources of the project belong to <code>data/$projectname</code>.</p>
+
+<p>Data files <small>SHOULD</small> be found at runtime using:</p>
+
+<pre><code>require 'rbconfig'
+require 'rbconfig/datadir'
+path = Config.datadir('$projectname')
+</code></pre>
+
+<p><small>XXX</small> find a way to make this work from checkouts, and
+with several
+package management mechanisms being used.</p>
+
+<h2>Tests</h2>
+
+<p>Tests <small>SHOULD</small> reside in <code>test/</code> or <code>spec/</code>.</p>
+
+<h2>History</h2>
+
+<ul>
+<li>09apr2010: First initial draft.</li>
+<li>10apr2010: Fix binary permissions.</li>
+<li>10apr2010: Add data files.</li>
+<li>11apr2010: Formatting, more detail on Extensions and Data files.</li>
+</ul>
+
+ </body></html>
Please sign in to comment.
Something went wrong with that request. Please try again.