README for dispatch
===================
Jason J.A. Stephenson <jason@sigio.com>
v2.0.1, 7 November 2014

dispatch is a small utility program intended to be used to run various
other commands, or jobs, in parallel.  It will read commands from
standard input or from files passed as arguments to its command line.
Once the internal list of commands has been built, dispatch will fork
a process to run each command by invoking /bin/sh with the -c option
followed by the command and its arguments.  It will run a certain
number of these commands in parallel.  The number is determined by the
numeric argument of dispatch's num (n) command line option.  If this
option is omitted, a default value of 2 is used.

dispatch also has a verbose (v) option that takes no argument.  If
this argument is passed on the command line, it will output some
information about the processes that are being run and the progress on
the total list of commands.  This output is sent to the standard error
device so as not to interfere with any redirection of the standard
output from the commands being run.

See the man page for a brief synopsis of this program's use.

Installation
------------

dispatch uses the GNU autotools for installation.  If you have a file
named `configure` in your distribution, you run it and then `make`,
followed by `make install`.  You can run `configure --help` for build
options.

If you don't have the `configure` script, but you do have
`configure.ac`, then you can generate the `configure` script by
running `autoreconf -i` in the main distribution directory.  This
latter event very likely means that you got the code via git.

boost
~~~~~

dispatch requires boost version 1.48 or later.  Specifically, it uses
the IOStreams, Locale, and Program Options libraries.  If boost is not
installed in your normal include or library paths, the `configure`
script provides options to specify where boost is installed.  If your
boost installation is not available in your normal include and library
search paths, you may specify one of the following options to indicate
where your boost libraries are installed:

`--with-libboost_locale-prefix=/path/to/boost`
`--with-libboost_iostreams-prefix=/path/to/boost`
`--with-libboost_program_options-prefix=/path/to/boost`

If you happen to have split your boost installation up over multiple
directories, then you may need to specify all of the above options.

Libdispatch
-----------

Beginning with version 2.0.0, dispatch installs a shared library,
libdispatch, to your libdir.  If you are not installing to one of your
system's standard locations, you may need to add `${PREFIX}/lib` to
`LD_LIBRARY_PATH` or alter `ld.so.conf`.

This library contains the implemenation of the dispatch function that
is used to fork and exec the commands that are dispatched by the
dispatch program.  This library and function may be used in your own
programs if you want a similar functionality.  Keep in mind that
libdispatch is also released under the terms of the GNU GPL version 3,
or later.  In order to use it, the license of your application must be
compatible.

If you want to read how to use the function, a man page is included in
section 3 describing it: `man 3 dispatch` for the details after
installation.

In version 2.0.1 of dispatch, the dispatch library function was fixed
to use the current user's environment when running dispatched
commands.  In version 2.0.0, it used an empty environment.

License
-------

dispatch is distributed under the terms of the GNU General Public
License version 3, or later.  The file gpl-3.0.txt contains the text
of this license.