src/libopts/README

   1         THIS TARBALL IS NOT A FULL DISTRIBUTION.
   2
   3 The contents of this tarball is designed to be incorporated into
   4 software packages that utilize the AutoOpts option automation package
   5 and are intended to be installed on systems that may not have libopts
   6 installed.  It is redistributable under the terms of either the LGPL
   7 (see COPYING.lgpl) or under the terms of the advertising clause free BSD
   8 license (see COPYING.mbsd).
   9
  10 Usage Instructions for autoconf/automake/libtoolized projects:
  11
  12 1. Install the unrolled tarball into your package source tree,
  13    copying ``libopts.m4'' to your autoconf macro directory.
  14
  15    In your bootstrap (pre-configure) script, you can do this:
  16
  17       rm -rf libopts libopts-*
  18       gunzip -c `autoopts-config libsrc` | tar -xvf -
  19       mv -f libopts-*.*.* libopts
  20       cp -fp libopts/m4/*.m4 m4/.
  21
  22    I tend to put my configure auxiliary files in "m4".
  23    Whatever directory you choose, if it is not ".", then
  24    be sure to tell autoconf about it with:
  25
  26       AC_CONFIG_AUX_DIR(m4)
  27
  28    This is one macro where you *MUST* remember to *NOT* quote
  29    the argument.  If you do, automake will get lost.
  30
  31 2. Add an invocation of either LIBOPTS_CHECK or LIBOPTS_CHECK_NOBUILD
  32    to your configure.ac file.  See LIBOPTS_CHECK: below for details.
  33
  34 3. Add the following to your top level ``Makefile.am'' file:
  35
  36       if NEED_LIBOPTS
  37          SUBDIRS += $(LIBOPTS_DIR)
  38       endif
  39
  40    where ``<...>'' can be whatever other files or directories you may
  41    need.  The SUBDIRS must be properly ordered.  *PLEASE NOTE* it is
  42    crucial that the SUBDIRS be set under the control of an automake
  43    conditional.  To work correctly, automake has to know the range of
  44    possible values of SUBDIRS.  It's a magical name with magical
  45    properties.  ``NEED_LIBOPTS'' will be correctly set by the
  46    ``LIBOPTS_CHECK'' macro, above.
  47
  48 4. Add ``$(LIBOPTS_CFLAGS)'' to relevant compiler flags and
  49    ``$(LIBOPTS_LDADD)'' to relevant link options whereever
  50    you need them in your build tree.
  51
  52 5. Make sure your object files explicitly depend upon the
  53    generated options header file.  e.g.:
  54
  55      $(prog_OBJECTS) : prog-opts.h
  56      prog-opts.h : prog-opts.c
  57      prog-opts.c : prog-opts.def
  58          autogen prog-opts.def
  59
  60 6. *OPTIONAL* --
  61    If you are creating man pages and texi documentation from
  62    the program options, you will need these rules somewhere, too:
  63
  64      man_MANS = prog.1
  65      prog.1 : prog-opts.def
  66          autogen -Tagman-cmd.tpl -bprog prog-opts.def
  67
  68      invoke-prog.texi : prog-opts.def
  69          autogen -Tagtexi-cmd.tpl prog-opts.def
  70
  71 If your package does not utilize the auto* tools, then you
  72 will need to hand craft the rules for building the library.
  73
  74 LIBOPTS_CHECK:
  75
  76 The arguments to both macro are a relative path to the directory with
  77 the libopts source code.  It is optional and defaults to "libopts".
  78 These macros work as follows:
  79
  80 1.  LIBOPTS_CHECK([libopts/rel/path/optional])
  81
  82     Adds two command-line options to the generated configure script,
  83     --enable-local-libopts and --disable-libopts-install.  AC_SUBST's
  84     LIBOPTS_CFLAGS, LIBOPTS_LDADD, and LIBOPTS_DIR for use in
  85     Makefile.am files.  Adds Automake conditional NEED_LIBOPTS which
  86     will be true when the local copy of libopts should be built.  Uses
  87     AC_CONFIG_FILES([$libopts-dir/Makefile]) to cause the local libopts
  88     into the package build.  If the optional relative path to libopts is
  89     not provided, it defaults to simply "libopts".
  90
  91 2.  LIBOPTS_CHECK_NOBUILD([libopts/rel/path/optional])
  92
  93     This variant of LIBOPTS_CHECK is useful when multiple configure.ac
  94     files in a package make use of a single libopts tearoff.  In that
  95     case, only one of the configure.ac files should build libopts and
  96     others should simply use it.  Consider this package arrangment:
  97
  98     all-tools/
  99       configure.ac
 100       common-tools/
 101         configure.ac
 102         libopts/
 103
 104     The parent package all-tools contains a subpackage common-tools
 105     which can be torn off and used independently.  Programs configured
 106     by both configure.ac files link against the common-tools/libopts
 107     tearoff, when not using the system's libopts.  The top-level
 108     configure.ac uses LIBOPTS_CHECK_NOBUILD([common-tools/libopts]),
 109     while common-tools/configure.ac uses LIBOPTS_CHECK.  The difference
 110     is LIBOPTS_CHECK_NOBUILD will never build the libopts tearoff,
 111     leaving that to the subpackage configure.ac's LIBOPTS_CHECK.
 112     Specifically, LIBOPTS_CHECK_NOBUILD always results in the
 113     NEED_LIBOPTS Automake conditional being false, and does not invoke
 114     AC_CONFIG_FILES(path-to-libopts/Makefile).
 115
 116 LICENSING:
 117
 118 This material is Copyright (c) 1992-2012 by Bruce Korb.  You are
 119 licensed to use this under the terms of either the GNU Lesser General
 120 Public License (see: COPYING.lgpl), or, at your option, the modified
 121 Berkeley Software Distribution License (see: COPYING.mbsd).  Both of
 122 these files should be included with this tarball.