Home | History | Annotate | Line # | Download | only in libopts 
      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-2018 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.
    123