git.ozlabs.org Git - ccan/blob - doc/configurator.1.txt

   1 CONFIGURATOR(1)
   2 ===============
   3 :doctype: manpage
   4
   5
   6 NAME
   7 ----
   8 configurator - Generate a simple config.h or variable file
   9
  10
  11 SYNOPSIS
  12 --------
  13 *configurator* ['OPTIONS'] ['CC'] ['CFLAGS'...]
  14
  15 DESCRIPTION
  16 -----------
  17 *configurator* is a standalone C program which evaluates the C
  18 environment using code snippets.
  19
  20 The C compiler (and flags) can be provided on the command-line,
  21 otherwise built-in defaults are used.
  22
  23 It has a builtin set of tests, to which more can be added.  By default
  24 it produces a C header file to standard output, but it can also
  25 produce a file containing simple "key=value" lines suitable for parsing
  26 by *sh* or *make*.
  27
  28 OPTIONS
  29 -------
  30 *-v*::
  31   Print out every test result; specified twice, print out each test too.
  32
  33 *-vv*::
  34   Shortcut for two *-v* options.
  35
  36 *--var-file=<file>*::
  37   Output results in format '<key>=<value>' to '<file>', or stdout if '<file>'
  38   is '-'.  Default is not to output this.
  39
  40 *--header-file=<file>*::
  41   Output C-style header to '<file>' instead out stdout.
  42
  43 *--autotools-style*::
  44   Produce output to stdout like autotools' configure script.  This
  45   usually means you want to use *--header-file* so that doesn't mix with stdout.
  46
  47 *-O<outflag>*::
  48   Override option to set compiler output file.
  49
  50 *--configurator-cc=<command>*::
  51   This gives the real compiler command to use for tests, instead of the first
  52   commandline argument or the default.
  53
  54 *--extra-tests*::
  55   Read additional tests from stdin, see 'EXTRA TESTS' below.
  56
  57 OUTPUT
  58 ------
  59
  60 The header output is '#ifndef/#define' idempotent-wrapped using
  61 'CCAN_CONFIG_H', and defines '_GNU_SOURCE'.  It also defines
  62 'CCAN_COMPILER', 'CCAN_CFLAGS' and 'CCAN_OUTPUT_EXE_CFLAG' as
  63 either the built-in definitions or those provided on the command line.
  64 The remainder is '#define' of the test names followed by a '0' or '1':
  65 note that this means you should use '#if' not '#ifdef' to test features
  66 in your C programs!
  67
  68 The var-file output is simply the test names followed by '=1' or '=0'.
  69
  70 EXTRA TESTS
  71 -----------
  72 Extra tests must be formatted as '<key>=<value>' pairs, with leading
  73 whitespace and '#' lines ignored.
  74
  75 The first three lines are always the same:
  76
  77 *var=<varname>*::
  78    Define the variable set by the test, e.g. 'var=HAVE_FOO'.
  79
  80 *desc=<description>*::
  81    The description printed out with *--autotools-style*, e.g. 'foo support'.
  82
  83 *style=<style>*::
  84    The set of strings defining how to treat the code snippet.  It must
  85    include one of 'OUTSIDE_MAIN', 'DEFINES_FUNC', 'INSIDE_MAIN' or
  86    'DEFINES_EVERYTHING' which control the boilerplate to surround the
  87    file, and may include 'EXECUTE' or both 'EXECUTE' and
  88    'MAY_NOT_COMPILE'.  e.g. 'INSIDE_MAIN|EXECUTE'.
  89
  90 The following styles are defined:
  91
  92 *OUTSIDE_MAIN*::
  93   means we put a simple boilerplate main below it.
  94
  95 *DEFINES_FUNC*::
  96   put a simple boilerplate main below it, which references 'func' (to
  97   avoid any unused warnings).
  98
  99 *INSIDE_MAIN*::
 100   put this inside main().  This also means it must exit with status 0
 101   if it compiles, unless *EXECUTE* is added.
 102
 103 *DEFINES_EVERYTHING*::
 104   don't add any boilerplate at all.
 105
 106 *EXECUTE*::
 107   this is an execution test; it must compile, but may not exit with
 108   status 0 when run.
 109
 110 *MAY_NOT_COMPILE*::
 111   Only useful with EXECUTE: don't get upset if it doesn't compile.
 112
 113 The following lines are optional, and may follow in any order:
 114
 115 *depends=<varnames>*::
 116   A space-separates set of vars which must pass to even try to pass this
 117   one.  If the var begins with '!' then the dependency must fail to try
 118   this one. e.g. 'depends=HAVE_UCONTEXT !HAVE_VALGRIND_MEMCHECK_H'.
 119
 120 *link=<linkargs>*::
 121   Extra arguments for linking with this test, e.g. 'link=-lrt'.
 122
 123 *flags=<cflags>*::
 124   Extra flags for compiling with this test, e.g. 'flags=-fopenmp'.
 125
 126 *overrides=<varname>*::
 127   Tests to force passing if this one passes. e.g. 'overrides=HAVE_SOME_FOO'.
 128
 129 The final line is the code to test, itself, either as a single
 130 'code=<oneline>' or as multiple lines starting with 'code=' and ending
 131 with '/\*END*/' on a line by itself. e.g. 'code=return 0;'
 132
 133 EXIT STATUS
 134 -----------
 135 It will exit with non-zero status if it has a problem.  *1* means bad
 136 commandline options. *2* means some operational problem creating and
 137 running tests. *3* means a bad test. *4* means failure to parse an
 138 extra test.
 139
 140 AUTHOR
 141 ------
 142 Rusty Russell wrote *configurator*.
 143
 144 RESOURCES
 145 ---------
 146 Main web site: http://ccodearchive.net/
 147
 148 Wiki: https://github.com/rustyrussell/ccan/wiki/
 149
 150 COPYING
 151 -------
 152 This program is under the MIT-style BSD license; see code for details.