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

   1 '\" t
   2 .\"     Title: configurator
   3 .\"    Author: [see the "AUTHOR" section]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
   5 .\"      Date: 03/01/2018
   6 .\"    Manual: \ \&
   7 .\"    Source: \ \&
   8 .\"  Language: English
   9 .\"
  10 .TH "CONFIGURATOR" "1" "03/01/2018" "\ \&" "\ \&"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 configurator \- Generate a simple config\&.h or variable file
  32 .SH "SYNOPSIS"
  33 .sp
  34 \fBconfigurator\fR [\fIOPTIONS\fR] [\fICC\fR] [\fICFLAGS\fR\&...]
  35 .SH "DESCRIPTION"
  36 .sp
  37 \fBconfigurator\fR is a standalone C program which evaluates the C environment using code snippets\&.
  38 .sp
  39 The C compiler (and flags) can be provided on the command\-line, otherwise built\-in defaults are used\&.
  40 .sp
  41 It has a builtin set of tests, to which more can be added\&. By default it produces a C header file to standard output, but it can also produce a file containing simple "key=value" lines suitable for parsing by \fBsh\fR or \fBmake\fR\&.
  42 .SH "OPTIONS"
  43 .PP
  44 \fB\-v\fR
  45 .RS 4
  46 Print out every test result; specified twice, print out each test too\&.
  47 .RE
  48 .PP
  49 \fB\-vv\fR
  50 .RS 4
  51 Shortcut for two
  52 \fB\-v\fR
  53 options\&.
  54 .RE
  55 .PP
  56 \fB\-\-var\-file=<file>\fR
  57 .RS 4
  58 Output results in format
  59 \fI<key>=<value>\fR
  60 to
  61 \fI<file>\fR, or stdout if
  62 \fI<file>\fR
  63 is
  64 \fI\-\fR\&. Default is not to output this\&.
  65 .RE
  66 .PP
  67 \fB\-\-header\-file=<file>\fR
  68 .RS 4
  69 Output C\-style header to
  70 \fI<file>\fR
  71 instead out stdout\&.
  72 .RE
  73 .PP
  74 \fB\-\-autotools\-style\fR
  75 .RS 4
  76 Produce output to stdout like autotools\*(Aq configure script\&. This usually means you want to use
  77 \fB\-\-header\-file\fR
  78 so that doesn\(cqt mix with stdout\&.
  79 .RE
  80 .PP
  81 \fB\-O<outflag>\fR
  82 .RS 4
  83 Override option to set compiler output file\&.
  84 .RE
  85 .PP
  86 \fB\-\-configurator\-cc=<command>\fR
  87 .RS 4
  88 This gives the real compiler command to use for tests, instead of the first commandline argument or the default\&.
  89 .RE
  90 .PP
  91 \fB\-\-extra\-tests\fR
  92 .RS 4
  93 Read additional tests from stdin, see
  94 \fIEXTRA TESTS\fR
  95 below\&.
  96 .RE
  97 .SH "OUTPUT"
  98 .sp
  99 The header output is \fI#ifndef/#define\fR idempotent\-wrapped using \fICCAN_CONFIG_H\fR, and defines \fI_GNU_SOURCE\fR\&. It also defines \fICCAN_COMPILER\fR, \fICCAN_CFLAGS\fR and \fICCAN_OUTPUT_EXE_CFLAG\fR as either the built\-in definitions or those provided on the command line\&. The remainder is \fI#define\fR of the test names followed by a \fI0\fR or \fI1\fR: note that this means you should use \fI#if\fR not \fI#ifdef\fR to test features in your C programs!
 100 .sp
 101 The var\-file output is simply the test names followed by \fI=1\fR or \fI=0\fR\&.
 102 .SH "EXTRA TESTS"
 103 .sp
 104 Extra tests must be formatted as \fI<key>=<value>\fR pairs, with leading whitespace and \fI#\fR lines ignored\&.
 105 .sp
 106 The first three lines are always the same:
 107 .PP
 108 \fBvar=<varname>\fR
 109 .RS 4
 110 Define the variable set by the test, e\&.g\&.
 111 \fIvar=HAVE_FOO\fR\&.
 112 .RE
 113 .PP
 114 \fBdesc=<description>\fR
 115 .RS 4
 116 The description printed out with
 117 \fB\-\-autotools\-style\fR, e\&.g\&.
 118 \fIfoo support\fR\&.
 119 .RE
 120 .PP
 121 \fBstyle=<style>\fR
 122 .RS 4
 123 The set of strings defining how to treat the code snippet\&. It must include one of
 124 \fIOUTSIDE_MAIN\fR,
 125 \fIDEFINES_FUNC\fR,
 126 \fIINSIDE_MAIN\fR
 127 or
 128 \fIDEFINES_EVERYTHING\fR
 129 which control the boilerplate to surround the file, and may include
 130 \fIEXECUTE\fR
 131 or both
 132 \fIEXECUTE\fR
 133 and
 134 \fIMAY_NOT_COMPILE\fR\&. e\&.g\&.
 135 \fIINSIDE_MAIN|EXECUTE\fR\&.
 136 .RE
 137 .sp
 138 The following styles are defined:
 139 .PP
 140 \fBOUTSIDE_MAIN\fR
 141 .RS 4
 142 means we put a simple boilerplate main below it\&.
 143 .RE
 144 .PP
 145 \fBDEFINES_FUNC\fR
 146 .RS 4
 147 put a simple boilerplate main below it, which references
 148 \fIfunc\fR
 149 (to avoid any unused warnings)\&.
 150 .RE
 151 .PP
 152 \fBINSIDE_MAIN\fR
 153 .RS 4
 154 put this inside main()\&. This also means it must exit with status 0 if it compiles, unless
 155 \fBEXECUTE\fR
 156 is added\&.
 157 .RE
 158 .PP
 159 \fBDEFINES_EVERYTHING\fR
 160 .RS 4
 161 don\(cqt add any boilerplate at all\&.
 162 .RE
 163 .PP
 164 \fBEXECUTE\fR
 165 .RS 4
 166 this is an execution test; it must compile, but may not exit with status 0 when run\&.
 167 .RE
 168 .PP
 169 \fBMAY_NOT_COMPILE\fR
 170 .RS 4
 171 Only useful with EXECUTE: don\(cqt get upset if it doesn\(cqt compile\&.
 172 .RE
 173 .sp
 174 The following lines are optional, and may follow in any order:
 175 .PP
 176 \fBdepends=<varnames>\fR
 177 .RS 4
 178 A space\-separates set of vars which must pass to even try to pass this one\&. If the var begins with
 179 \fI!\fR
 180 then the dependency must fail to try this one\&. e\&.g\&.
 181 \fIdepends=HAVE_UCONTEXT !HAVE_VALGRIND_MEMCHECK_H\fR\&.
 182 .RE
 183 .PP
 184 \fBlink=<linkargs>\fR
 185 .RS 4
 186 Extra arguments for linking with this test, e\&.g\&.
 187 \fIlink=\-lrt\fR\&.
 188 .RE
 189 .PP
 190 \fBflags=<cflags>\fR
 191 .RS 4
 192 Extra flags for compiling with this test, e\&.g\&.
 193 \fIflags=\-fopenmp\fR\&.
 194 .RE
 195 .PP
 196 \fBoverrides=<varname>\fR
 197 .RS 4
 198 Tests to force passing if this one passes\&. e\&.g\&.
 199 \fIoverrides=HAVE_SOME_FOO\fR\&.
 200 .RE
 201 .sp
 202 The final line is the code to test, itself, either as a single \fIcode=<oneline>\fR or as multiple lines starting with \fIcode=\fR and ending with \fI/*END*/\fR on a line by itself\&. e\&.g\&. \fIcode=return 0;\fR\&.
 203 .SH "EXIT STATUS"
 204 .sp
 205 It will exit with non\-zero status if it has a problem\&. \fB1\fR means bad commandline options\&. \fB2\fR means some operational problem creating and running tests\&. \fB3\fR means a bad test\&. \fB4\fR means failure to parse an extra test\&.
 206 .SH "AUTHOR"
 207 .sp
 208 Rusty Russell wrote \fBconfigurator\fR\&.
 209 .SH "RESOURCES"
 210 .sp
 211 Main web site: http://ccodearchive\&.net/
 212 .sp
 213 Wiki: https://github\&.com/rustyrussell/ccan/wiki/
 214 .SH "COPYING"
 215 .sp
 216 This program is under the MIT\-style BSD license; see code for details\&.