yahns-rackup launcher

This should make it easier for Rack users to get started with yahns.

3 files changed, 154 insertions, 1 deletions

diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index 482b5b1..b08a2a4 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -9,6 +9,7 @@ pandoc = $(PANDOC) $(PANDOC_OPTS)
 
 m1 =
 m1 += yahns
+m1 += yahns-rackup
 
 m5 =
 m5 += yahns_config
diff --git a/Documentation/yahns-rackup.txt b/Documentation/yahns-rackup.txt
new file mode 100644
index 0000000..269d013
--- /dev/null
+++ b/Documentation/yahns-rackup.txt
@@ -0,0 +1,152 @@
+% yahns-rackup(1) yahns user manual
+
+# NAME
+
+yahns-rackup - a rackup-like command to launch yahns
+
+# SYNOPSIS
+
+yahns-rackup [-E RACK_ENV] [-O worker_threads=NUM] [RACKUP_FILE]
+
+# DESCRIPTION
+
+A rackup(1)-like command to launch Rack applications using yahns.
+It is expected to start in your application root (APP_ROOT).
+
+# RACKUP FILE
+
+This defaults to \"config.ru\" in APP_ROOT.  It should be the same
+file used by rackup(1) and other Rack launchers, it uses the
+*Rack::Builder* DSL.
+
+# YAHNS OPTIONS
+-O client_timeout=SECONDS
+:   Defines the timeout expiring idle connections.
+
+    Increase this if your application takes longer to run than the
+    default timeout.  Lower this if you run out of FDs.
+
+    Default: 15 (seconds)
+
+-O listen=ADDRESS[,ADDRESS...]
+:   Listens on a given ADDRESS.  ADDRESS may be in the form of
+    HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
+    and PATH is meant to be a path to a UNIX domain socket.
+    Defaults to "0.0.0.0:9292" (all addresses on TCP port 9292).
+    Multiple addresses may be separated with commas.
+
+-O stderr_path=PATHNAME
+:   Allow redirecting $stderr to a given path.  Unlike doing this from
+    the shell, this allows the yahns process to know the path its
+    writing to and rotate the file if it is used for logging.  The
+    file will be opened with the O_APPEND flag and writes
+    synchronized to the kernel (but not necessarily to _disk_) so
+    multiple processes can safely append to it.
+
+    If you are daemonizing and using the default logger, it is important
+    to specify this as errors will otherwise be lost to /dev/null.
+    Some applications/libraries may also triggering warnings that go to
+    stderr, and they will end up here.
+
+    Default: /dev/null if daemonized, controlling terminal if not
+
+-O stdout_path=PATH
+:   Same as stderr_path, except for $stdout.  Not many applications
+    write to $stdout, but any that do will have their output written here.
+    It is safe to point this to the same location a stderr_path.
+    Like stderr_path, this defaults to /dev/null when daemonized.
+
+    Default: /dev/null if daemonized, controlling terminal if not
+
+-O worker_threads=INTEGER
+:   This controls the number of threads for application processing.
+    Each queue has its own thread pool.  Increase this number if your
+    applications are able to use more threads effectively or if either
+    (or both) input/output buffering are disabled.  Lower this number if
+    you do not need multi-thread concurrency at all.
+
+    Default: 7
+
+# RACKUP OPTIONS
+-D, \--daemonize
+:   Run daemonized in the background.  The process is detached from
+    the controlling terminal and stdin is redirected to /dev/null.
+    Unless specified via stderr_path and stdout_path, stderr and stdout will
+    also be redirected to "/dev/null".
+
+-E, \--env RACK_ENV
+:   Run under the given RACK_ENV.  See the RACK ENVIRONMENT section
+    for more details.
+
+-o, \--host HOST
+:   Listen on a TCP socket belonging to HOST, default is
+    "0.0.0.0" (all addresses).
+    If specified multiple times on the command-line, only the
+    last-specified value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+-p, \--port PORT
+:   Listen on the specified TCP PORT, default is 9292.
+    If specified multiple times on the command-line, only the last-specified
+    value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+# RUBY OPTIONS
+-e, \--eval LINE
+:   Evaluate a LINE of Ruby code.  This evaluation happens
+    immediately as the command-line is being parsed.
+
+-d, \--debug
+:   Turn on debug mode, the $DEBUG variable is set to true.
+
+-w, \--warn
+:   Turn on verbose warnings, the $VERBOSE variable is set to true.
+
+-I, \--include PATH
+:   specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
+    The \':\' character may be used to delimit multiple directories.
+    This directive may be used more than once.  Modifications to
+    $LOAD_PATH take place immediately and in the order they were
+    specified on the command-line.
+
+-r, \--require LIBRARY
+:   require a specified LIBRARY before executing the application.  The
+    \"require\" statement will be executed immediately and in the order
+    they were specified on the command-line.
+
+# SIGNALS
+
+See yahns(1)
+
+# FILES
+
+See Rack documentation for a description of the rackup file format.
+
+# ENVIRONMENT VARIABLES
+
+The RACK_ENV variable is set by the aforementioned \-E switch.
+If RACK_ENV is already set, it will be used unless \-E is used.
+See rackup documentation for more details.
+
+# CONTACT
+
+All feedback welcome via plain-text mail to <yahns-public@rubyforge.org>\
+No subscription is necessary to post to the mailing list.
+
+# COPYRIGHT
+
+Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
+License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
+
+# SEE ALSO
+
+yahns(1), yahns_config(5)
+
+* *Rack::Builder* ri/RDoc
+* [Rack RDoc][1]
+* [Rackup HowTo][2]
+
+[1]: http://rack.rubyforge.org/doc/
+[2]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
diff --git a/Documentation/yahns.txt b/Documentation/yahns.txt
index 0725f49..362851f 100644
--- a/Documentation/yahns.txt
+++ b/Documentation/yahns.txt
@@ -65,4 +65,4 @@ License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
 
 # SEE ALSO
 
-yahns_config(5)
+yahns-rackup(1), yahns_config(5)