pkgtools/autoswc/files/autoswc.8

   1 .\" $NetBSD$
   2 .\"
   3 .\" autoswc - Generates system wide cache files for GNU autoconf
   4 .\" Copyright (c) 2004 Julio M. Merino Vidal <jmmv@NetBSD.org>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Neither the name of The NetBSD Foundation nor the names of its
  12 .\"    contributors may be used to endorse or promote products derived
  13 .\"    from this software without specific prior written permission.
  14 .\" 3. Neither the name of author nor the names of its contributors may
  15 .\"    be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd February 21, 2004
  31 .Dt AUTOSWC 8
  32 .Os
  33 .Sh NAME
  34 .Nm autoswc
  35 .Nd generates system wide cache files for GNU autoconf
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl c Ar ac_file
  39 .Op Fl n Ar cache_name
  40 .Sh DESCRIPTION
  41 .Nm
  42 is an utility that automatically generates system wide cache files for use
  43 with configure scripts created by
  44 .Nm GNU autoconf ,
  45 and specially by those executed within
  46 .Nm pkgsrc .
  47 .Pp
  48 .Nm
  49 starts by reading the configuration script template.
  50 It will use
  51 .Pa @SYSCONFDIR@/configure.ac
  52 if found, or fallback to
  53 .Pa @PREFIX@/share/autoswc/configure.ac
  54 otherwise (a custom file may be given using the
  55 .Fl c
  56 flag, though).
  57 This issues all checks that the user wants to store in the system wide
  58 cache file, and are basically calls to standard
  59 .Nm GNU autoconf ,
  60 .Nm GNU automake
  61 and/or
  62 .Nm GNU libtool
  63 macros.
  64 There is no need to manually execute any of the
  65 .Sq AC_INIT ,
  66 .Sq AM_INIT_AUTOMAKE ,
  67 .Sq AC_CACHE_SAVE
  68 and
  69 .Sq AC_OUTPUT
  70 macros, as they are automatically inserted in the right place during
  71 execution.
  72 .Pp
  73 The default cache file is stored inside the
  74 .Pa @CACHEDIR@
  75 directory, using
  76 .Pa config.cache.default
  77 as the file name.
  78 The
  79 .Sq default
  80 part can be changed using the
  81 .Fl n
  82 flag, which takes the base name of the cache file.
  83 .Pp
  84 To tell
  85 .Nm pkgsrc
  86 to use the system wide cache, all you need to do is append the following
  87 line to your
  88 .Pa @MKCONF@
  89 file:
  90 .Bd -literal -offset indent
  91 \&.sinclude "@PREFIX@/share/autoswc/autoswc.mk"
  92 .Ed
  93 .Pp
  94 In case you used the
  95 .Fl n
  96 flag, you also need to define the
  97 .Va AUTOSWC_CACHE_NAME
  98 variable in this file, setting it to the value passed to the flag.
  99 .Sh NOTES
 100 Be very careful about what you add to
 101 .Pa configure.ac .
 102 You should only check for things that are unlikely to change over time,
 103 as functions in the
 104 .Lb libc
 105 and its header files.
 106 Failure to do so can easily lead to cache files that get outdated very
 107 easily during installation of new packages, and cause unexpected
 108 configuration errors.
 109 .Pp
 110 It is recommended that you rebuild the cache file periodically.
 111 You can configure a simple
 112 .Xr cron 8
 113 job to it, which just needs to launch this utility.
 114 .Pp
 115 If you hit a compilation problem in any package when using
 116 .Nm ,
 117 be
 118 .Em absolutely
 119 sure it is not beeing caused by an outdated cache before reporting
 120 problems.
 121 The safest and easiest way to do this is to clean the package in question
 122 and restart the build with the
 123 .Va AUTOSWC_DISABLE
 124 variable set, like in the following example:
 125 .Bd -literal -offset indent
 126 $ @MAKE@ clean
 127 $ @MAKE@ AUTOSWC_DISABLE=YES
 128 .Ed
 129 .Sh AUTHORS
 130 .An Julio M. Merino Vidal Aq jmmv@netbsd.org