configurator: Enable running configurator in wrapper
[ccan] / 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.