autoopts_back

BLOCKSORT
an AutoOpts example package

Main
AutoGen
Pages

Home
Announce
FAQ
docs
XML Defs
testimonials
downloads

Automated
Options

AutoOpts
Comparison
Man example
Redistribute
Licensing
local use
using getopt

GCC's
Fixincludes

fixincludes

Automated
FSM

description
example
usagefsm

Addons
addon

Project GNU
Home Page

Automated
XDR

xdr project

i

Blocksort is a "Hello, world!" example that actually does something. It will sort blocks of text in a text file. See the usage text for more details. It is being released in conjunction with AutoGen as a detailed example of how to incorporate AutoOpts into your projects. Before you look at the example, you need to consider that there are three levels of integration. You can:

  1. Compile and link your program locally and either not distribute it at all, or only distribute it in a fully-linked binary form.
  2. Rely on a pre-installed "libopts" library for whereever it gets built. This can be accomplished either by installing AutoGen in its entirety, or by building and installing strictly the libopts package.
  3. Integrate the "libopts" sources into your project's sources and use it when "libopts" has not been pre-installed.

This example program tackles the last and most difficult of these levels of integration.


Local Only Use This is actually very simple example (see the man2html for a more complete example). All you need to do is add the output from the "autoopts-config" script to your CFLAGS and linker options, a la:

  CFLAGS=`autoopts-config cflags` ...
  LDFLAGS=`autoopts-config ldflags` ...

Depend on a pre-installation AutoGen will install an autoconf M4 macro file named, "autoopts.m4". Invoke the macro, "AG_PATH_AUTOOPTS" in your "configure.ac" file. It will produce four substitution variables and two configure options:

  1. AUTOGEN
    This is the full path name of the autogen executable.
  2. AUTOOPTS_CFLAGS
    Add this to your CFLAGS makefile variable.
  3. AUTOOPTS_LIBS
    Add this to the link command.
  4. AUTOGEN_TPLIB
    The full path to the directory where the AutoGen template library is installed.
  5. --with-opts-prefix=PFX
    Prefix where autoopts is installed.
  6. --with-opts-exec-prefix=PFX
    Exec prefix where autogen is installed

Integrate and redistribute This takes a little work. Here's the readme that comes with the libopts tear-off tarball:

The contents of this tarball is designed to be incorporated into
software packages that utilize the AutoOpts option automation
package and are intended to be installed on systems that may not
have libopts installed.  It is redistributable under the terms
of either the LGPL (see COPYING.lgpl) or under the terms of
the advertising clause free BSD license (see COPYING.mbsd).

Usage Instructions for autoconf/automake/libtoolized projects:

1. Install the unrolled tarball into your package source tree,
   copying ``libopts.m4'' to your autoconf macro directory.

   In your bootstrap (pre-configure) script, you can do this:

      rm -rf libopts libopts-*
      gunzip -c `autoopts-config libsrc` | tar -xvf -
      mv -f libopts-*.*.* libopts
      cp -fp libopts/m4/*.m4 m4/.

   I tend to put my configure auxiliary files in "m4".
   Whatever directory you choose, if it is not ".", then
   be sure to tell autoconf about it with:

      AC_CONFIG_AUX_DIR(m4)

   This is one macro where you *MUST* remember to *NOT* quote
   the argument.  If you do, automake will get lost.

2. Add the following to your ``configure.ac'' file:

      LIBOPTS_CHECK

   or:

      LIBOPTS_CHECK([relative/path/to/libopts])

   This macro will automatically invoke

      AC_CONFIG_FILES( [relative/path/to/libopts/Makefile] )

   The default ``relative/path/to/libopts'' is simply
   ``libopts''.

3. Add the following to your top level ``Makefile.am'' file:

      if NEED_LIBOPTS
         SUBDIRS += $(LIBOPTS_DIR)
      endif

   where ``<...>'' can be whatever other files or directories
   you may need.  The SUBDIRS must be properly ordered.
   *PLEASE NOTE* it is crucial that the SUBDIRS be set under the
   control of an automake conditional.  To work correctly,
   automake has to know the range of possible values of SUBDIRS.
   It's a magical name with magical properties.  ``NEED_LIBOPTS''
   will be correctly set by the ``LIBOPTS_CHECK'' macro, above.

4. Add ``$(LIBOPTS_CFLAGS)'' to relevant compiler flags and
   ``$(LIBOPTS_LDADD)'' to relevant link options whereever
   you need them in your build tree.

5. Make sure your object files explicitly depend upon the
   generated options header file.  e.g.:

     $(prog_OBJECTS) : prog-opts.h
     prog-opts.h : prog-opts.c
     prog-opts.c : prog-opts.def
         autogen prog-opts.def

6. *OPTIONAL* --
   If you are creating man pages and texi documentation from
   the program options, you will need these rules somewhere, too:

     man_MANS = prog.1
     prog.1 : prog-opts.def
         autogen -Tagman1.tpl -bprog prog-opts.def

     prog-invoke.texi : prog-opts.def
         autogen -Taginfo.tpl -bprog-invoke prog-opts.def

If your package does not utilize the auto* tools, then you
will need to hand craft the rules for building the library.

LICENSING:

This material is copyright 1993-2006 by Bruce Korb.
You are licensed to use this under the terms of either
the GNU Lesser General Public License (see: COPYING.lgpl), or,
at your option, the modified Berkeley Software Distribution
License (see:  COPYING.mbsd).  Both of these files should be
included with this tarball.

blocksort text sorting utility

Here is the AutoGen-erated usage text:

blocksort (MyTools) - Sort Blocks of Text - Ver. 1.1
USAGE:  blocksort { <option-name>[{=| }<val>] }...
   Arg Option-Name   Req?  Description
   Mbr syntax         opt  EXTENDED, ICASE or NEWLINE (see regcomp(3))
				- is a set membership option
   no  cook           opt  process escaped characters
				- disabled as --no-cook
				- may appear up to 4 times
   Str pattern        YES  File Segmentation Pattern
   Str key            opt  Sort Key Finding Pattern
   Str date-key       opt  Date Format Sort Key
				- an alternate for key
   no  invert         opt  Reverse the sort order
   Str trailer        opt  Trailer Finding Pattern
   Str start          opt  Starting Point Pattern
   Str input          opt  Input File
				- default option for unnamed options
   Str output         opt  Output File
   Num spacing        opt  blank line count between sections
   no  verbose        opt  Display extra information
   opt version        opt  Output version information and exit
   no  help           opt  Display usage information and exit
   no  more-help      opt  Extended usage information passed thru pager

All arguments are named options.

Given a search pattern, this program will segment a file on the
start of every line that matches a pattern.  Each block of text
is then lexicographically sorted and reassembled into the output.
Any text found before the first match will be left in place.
If "KEY" or "DATE_KEY" is supplied, the sort is based on the
matching text (or date).  If that expression contains subexpressions,
then the comparison(s) will be against those subexpressions only.
If "KEY" is not found in a block, the sort key becomes the empty
string.  The "Trailer" pattern can be used to keep a block of text
at the end of the file.

The valid "syntax" option keywords are:
  extended icase newline
or you may use a numeric representation.  Preceding these with a '!' will
clear the bits, specifying 'none' will clear all bits, and 'all' will set them
all.  Multiple entries may be passed as an option argument list.

please send bug reports to:  autogen-bugs@lists.sf.net

top  Viewable With Any Browser  Valid XHTML 1.0!


AutoGen, AutoOpts, columns, getdefs, AutoFSM, AutoXDR and these web pages copyright (c) 1999-2002 Bruce Korb, all rights reserved.

Return to GNU's home page.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

Please send comments on these web pages to webmasters@www.gnu.org, send other questions to gnu@gnu.org.

This article, Copyright © 2000-2002 by Bruce Korb

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. Last modified: Sun Oct 1 12:59:15 PDT 2006