README

   1 libpipeline, a pipeline manipulation library
   2 ============================================
   3
   4 libpipeline is a C library for setting up and running pipelines of
   5 processes, without needing to involve shell command-line parsing which is
   6 often error-prone and insecure.  This alleviates programmers of the need to
   7 laboriously construct pipelines using lower-level primitives such as fork(2)
   8 and execve(2).
   9
  10 Full programmers' documentation may be found using 'man libpipeline'.
  11
  12 Installation
  13 ------------
  14
  15 If you need to install libpipeline starting from source code, then you will
  16 need these separate packages installed before configuring libpipeline in
  17 order to run its test suite:
  18
  19   pkg-config (http://www.freedesktop.org/wiki/Software/pkg-config)
  20   check (http://check.sourceforge.net/)
  21
  22 See the INSTALL file for general installation instructions.
  23
  24 Building programs with libpipeline
  25 ----------------------------------
  26
  27 libpipeline supplies a pkg-config file which lists appropriate compiler and
  28 linker flags for building programs using it.  The output of 'pkg-config
  29 --cflags libpipeline' should be passed to the compiler (typically CFLAGS)
  30 and the output of 'pkg-config --libs libpipeline' should be passed to the
  31 linker (typically LDFLAGS).
  32
  33 If your program uses the GNU Autotools, then you can put this in
  34 configure.ac:
  35
  36   PKG_CHECK_MODULES([libpipeline], [libpipeline])
  37
  38 ... and this in the appropriate Makefile.am (replacing 'program' with the
  39 Automake-canonicalised name for your program):
  40
  41   AM_CFLAGS = $(libpipeline_CFLAGS)
  42   program_LDADD = $(libpipeline_LIBS)
  43
  44 The details may vary for particular build systems, but this should be a
  45 reasonable start.
  46
  47 When building with GCC, you should use at least the -Wformat option
  48 (included in -Wall) to ensure that the 'sentinel' function attribute is
  49 checked.  This means that your program will produce a warning if it calls
  50 any of the several libpipeline functions that require a trailing NULL
  51 without passing that trailing NULL.
  52
  53 Copyright and licensing
  54 -----------------------
  55
  56 Copyright (C) 1994 Markus Armbruster.
  57 Copyright (C) 1989, 1990, 1991, 1992, 2000, 2001, 2002, 2003, 2004, 2005,
  58               2006, 2007, 2008, 2009, 2010
  59               Free Software Foundation, Inc.
  60 Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Colin Watson.
  61
  62 libpipeline is free software; you can redistribute it and/or modify
  63 it under the terms of the GNU General Public License as published by
  64 the Free Software Foundation; either version 3 of the License, or (at
  65 your option) any later version.
  66
  67 libpipeline is distributed in the hope that it will be useful, but
  68 WITHOUT ANY WARRANTY; without even the implied warranty of
  69 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  70 General Public License for more details.
  71
  72 You should have received a copy of the GNU General Public License
  73 along with libpipeline; if not, write to the Free Software
  74 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  75 USA.
  76
  77 Note on GPL versions
  78 --------------------
  79
  80 (This note is informative, and if it conflicts with the terms of the licence
  81 then the licence is correct.  See the full text of the licence in the
  82 COPYING file for precise details.)
  83
  84 The core source code of libpipeline is licensed under GPL v2 or later.
  85 However, libpipeline incorporates parts of the Gnulib portability library,
  86 copyrighted by the Free Software Foundation and others, and much of Gnulib
  87 is distributed under GPL v3 or later.  This means that libpipeline as a
  88 whole falls under the terms of the GPL v3 or later.  Unless you take special
  89 pains to remove the GPL v3 portions, you must therefore follow the terms and
  90 conditions of the GPL v3 or later when distributing libpipeline itself, or
  91 distributing code linked against it.
  92
  93 Note that this does not require that your own source code be licensed under
  94 the GPL v3, contrary to popular misunderstanding.  However, you must be
  95 prepared to distribute your work as a whole under the terms of the GPL v3 or
  96 later, which requires that your licence be compatible with the GPL v3.  See
  97 http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses if you
  98 need advice on compatibility.
  99
 100 The GPL mainly restricts distribution ("conveying", in the specific language
 101 of GPL v3), and is careful not to restrict private use.  Therefore, you may
 102 write programs for your own use that use libpipeline without needing to
 103 license them under GPL v3-compatible terms.  If you distribute these
 104 programs to others, then you must take care to use compatible licensing.
 105
 106 Credits
 107 -------
 108
 109 Thanks to Scott James Remnant for code review, Ian Jackson for an extensive
 110 design review, and Kees Cook and Matthias Klose for helpful conversations.
 111
 112  -- Colin Watson <cjwatson@debian.org>