cde/util/tradcpp/tradcpp.1

   1 .\"
   2 .\" Copyright (c) 2013 The NetBSD Foundation, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to The NetBSD Foundation
   6 .\" by David A. Holland.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 .\" POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .Dd June 11, 2013
  30 .Dt TRADCPP 1
  31 .Os
  32 .Sh NAME
  33 .Nm tradcpp
  34 .Nd traditional (K&R-style) C macro preprocessor
  35 .Sh SYNOPSIS
  36 .Nm tradcpp
  37 .Op Fl options
  38 .Op Ar input-file Op Ar output-file
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 command provides a traditional K&R-style C macro preprocessor.
  43 It is intended to be suitable for historical Unix uses of the
  44 preprocessor, such as
  45 .Xr imake 1 ,
  46 particularly those that depend on preservation of whitespace.
  47 .Pp
  48 The chief ways in which traditional cpp differs from
  49 Standard C are:
  50 .Bl -bullet -offset indent
  51 .It
  52 Macro arguments are expanded within quoted strings.
  53 There is no stringize operator.
  54 .It
  55 There is no token pasting operator; tokens can be concatenated by
  56 placing comments between them.
  57 This process is also not limited to valid C language tokens.
  58 .It
  59 Whitespace is preserved, and in particular tabs are not expanded into
  60 spaces.
  61 Furthermore, additional whitespace is not injected.
  62 .El
  63 .Sh OPTIONS
  64 .Nm
  65 has many options, many of which are defined for compatibility with
  66 .Xr gcc 1
  67 or other compilers.
  68 Many of the options are not yet implemented.
  69 .\" The option lists have been sorted in what I hope is a sensible
  70 .\" order. Please don't arbitrarily alphabetize them.
  71 .Ss Common Options
  72 .Bl -tag -width bubblebabble
  73 .It Fl C
  74 Retain comments in output.
  75 .It Fl Dmacro[=expansion]
  76 Provide a definition for the named macro.
  77 If no expansion is provided, the value
  78 .Dq 1
  79 is used.
  80 Note that like many Unix compilers,
  81 .Nm
  82 does not accept a space between the
  83 .Dq D
  84 and the macro name.
  85 .It Fl Ipath
  86 Add the specified path to the main list of include directories.
  87 Note that like many Unix compilers,
  88 .Nm
  89 does not accept a space between the
  90 .Dq I
  91 and the directory name.
  92 .It Fl nostdinc
  93 Do not search the standard system include directories.
  94 .It Fl P
  95 Suppress line number information in the output.
  96 Currently line number information is not generated at all and this
  97 option has no effect.
  98 .It Fl Umacro
  99 Remove any existing definition for the named macro.
 100 Note that like many Unix compilers,
 101 .Nm
 102 does not accept a space between the
 103 .Dq U
 104 and the macro name.
 105 .It Fl undef
 106 Remove all predefined macros.
 107 .El
 108 .Ss Warning Options
 109 Warning options can be disabled or enabled by inserting, or not, the
 110 string
 111 .Dq no-
 112 between the
 113 .Dq W
 114 and the warning name.
 115 Herein the
 116 .Dq Fl Wno-
 117 form is shown for options that are enabled by default.
 118 .Bl -tag -width bubblebabble
 119 .It Fl Wall
 120 Turn on all warnings.
 121 The option
 122 .Fl Wno-all
 123 disables only the warnings that are disabled by default.
 124 .It Fl w
 125 Turn off all warnings.
 126 .It Fl Werror
 127 Make warnings into fatal errors.
 128 .It Fl Wcomment
 129 Warn about nested comments.
 130 .It Fl Wno-endif-labels
 131 Don't warn about symbols attached to #endif directives.
 132 (The warning is currently not implemented.)
 133 .It Fl Wundef
 134 Warn about undefined symbols appearing in #if and #elif expressions.
 135 .It Fl Wunused-macros
 136 Warn about macros that are defined and never used.
 137 Not implemented.
 138 .El
 139 .Ss Depend Options
 140 .Bl -tag -width bubblebabble
 141 .It Fl M
 142 Generate dependency information for
 143 .Xr make 1
 144 on the standard output, instead of preprocessing.
 145 Not implemented.
 146 .It Fl MD
 147 Like
 148 .Fl M
 149 but skip system headers.
 150 Not implemented.
 151 .It Fl MM
 152 Like
 153 .Fl M
 154 but write the dependency information to a file named after the input
 155 file with extension
 156 .Pa \.d
 157 and preprocess normally to standard output.
 158 Not implemented.
 159 .It Fl MMD
 160 Like
 161 .Fl MM
 162 but skip system headers.
 163 Not implemented.
 164 .It Fl MF Ar file
 165 Send dependency output to the named file instead of the default
 166 location.
 167 Not implemented.
 168 .It Fl MG
 169 When generating dependency information, assume that missing files are
 170 generated instead of failing.
 171 Not implemented.
 172 .It Fl MP
 173 Issue dummy rules for all include files.
 174 This prevents
 175 .Xr make 1
 176 from choking if an include file is removed.
 177 Not implemented.
 178 .It Fl MQ Ar target
 179 Same as
 180 .Fl MT
 181 except that any
 182 .Xr make 1
 183 metacharacters appearing in the target are escaped.
 184 .It Fl MT Ar target
 185 Set the name of the
 186 .Xr make 1
 187 target appearing in the generated dependency information.
 188 The default is the name of the input file with its suffix replaced
 189 with the suffix for object files, normally
 190 .Pa .o .
 191 .\" If this option is given more than once, all named targets will
 192 .\" be emitted.
 193 .\" (The current operating mode framework doesn't support that.)
 194 .El
 195 .Ss More Include Path Options
 196 .Bl -tag -width bubblebabble
 197 .It Fl idirafter Ar path
 198 Add the specified path to the
 199 .Dq afterwards
 200 include path.
 201 This path is searched after all directories specified with
 202 .Fl I
 203 and the standard system directories.
 204 Directories on this path are treated as containing system include
 205 files.
 206 .It Fl imacros Ar file
 207 Read in
 208 .Ar file
 209 prior to reading the main input file, and preprocess it, but throw
 210 away the output and retain only the macro definitions.
 211 .It Fl include Ar file
 212 Read in and preprocess
 213 .Ar file
 214 prior to reading the main input file.
 215 .It Fl iprefix Ar prefix
 216 Set the path prefix used with the
 217 .Fl iwithprefix
 218 option.
 219 .It Fl iquote Ar path
 220 Add
 221 .Ar path
 222 to the list of directories searched for include directives written
 223 with quotes.
 224 This list is not searched for include directives written with angle
 225 brackets.
 226 .It Fl iremap Ar string:replacement
 227 Substitute
 228 .Ar replacement
 229 for
 230 .Ar string
 231 in the
 232 .Dv __FILE__
 233 built-in macro.
 234 Not supported.
 235 .It Fl isysroot Ar path
 236 Use
 237 .Ar path
 238 as the
 239 .Dq system root ,
 240 that is, the directory under which the standard system paths are found.
 241 .It Fl isystem Ar path
 242 Add
 243 .Ar path
 244 to the list of system include directories.
 245 This list is searched after the list given with
 246 .Ar I .
 247 Files found on this path are treated as system headers.
 248 .It Fl iwithprefix Ar dir
 249 Splice
 250 .Ar dir
 251 onto the prefix given with
 252 .Fl iprefix
 253 and add this directory as if it were specified with
 254 .Fl idirafter .
 255 .It Fl iwithprefixbefore
 256 Like
 257 .Fl iwithprefix
 258 but adds the result as if it were specified with
 259 .Fl I .
 260 .El
 261 .Ss Diagnostic Options
 262 .Bl -tag -width bubblebabble
 263 .It Fl debuglog Ar file
 264 Write a trace of actions and operations to
 265 .Ar file
 266 as the input is processed.
 267 Meant for debugging problems in complex substitution schemes fed to
 268 .Nm ,
 269 such as those used by
 270 .Xr imake 1 .
 271 .It Fl dD
 272 Dump all macro definitions, except for the predefined macros, after
 273 the normal preprocessing output.
 274 Not implemented.
 275 .It Fl dI
 276 Dump all include directives along with the normal preprocessing
 277 output.
 278 Not implemented.
 279 .It Fl dM
 280 Dump all macro definitions instead of the normal preprocessing
 281 output.
 282 Not implemented.
 283 .It Fl dN
 284 Like
 285 .Fl dD
 286 but emits only macro names and not the expansions.
 287 Not implemented.
 288 .It Fl H
 289 Output a trace of the include tree as it gets processed.
 290 Not implemented.
 291 .El
 292 .Ss Other Options
 293 .Bl -tag -width bubblebabble
 294 .It Fl CC
 295 Retain comments in output.
 296 Same as
 297 .Fl C ,
 298 accepted for compatibility with
 299 .Xr gcc 1 .
 300 .It Fl fdollars-in-identifiers , Fl fno-dollars-in-identifiers
 301 Enable
 302 .Pq or disable, respectively
 303 the use of the dollar sign in identifiers.
 304 Not implemented.
 305 .It Fl ftabstop=num
 306 Set the tab width to the specified value, for reporting column
 307 positions in diagnostics.
 308 The default is 8.
 309 Not implemented.
 310 .It Fl std=standard
 311 Ask
 312 .Nm
 313 to conform to the named standard.
 314 The default, and the only supported value, is
 315 .Dq krc .
 316 .It Fl traditional
 317 This option is accepted for compatibility with
 318 .Xr gcc 1
 319 and ignored.
 320 .It Fl x Ar lang
 321 Adjust the preprocessor for the given language.
 322 The only values accepted for
 323 .Ar lang
 324 are
 325 .Dq assembler-with-cpp
 326 and
 327 .Dq c ,
 328 neither of which have any effect on the behavior of
 329 .Nm .
 330 .El
 331 .Sh FILES
 332 The default list of directories searched for include files is:
 333 .Bl -item -offset indent -compact
 334 .It
 335 .Pa /usr/local/include
 336 .It
 337 .Pa /usr/include
 338 .El
 339 .Sh SEE ALSO
 340 .Xr cc 1 ,
 341 .Xr cpp 1 ,
 342 .Xr make 1
 343 .Sh STANDARDS
 344 None.
 345 The whole point of a traditional cpp is that it reflects practices
 346 in pre-standardization implementations of C.
 347 Some information is available from the first edition of Kernighan and
 348 Ritchie.
 349 Much of the rest of the behavior is based on lore, pragmatism,
 350 material encountered in the wild, and comparison to other
 351 implementations.
 352 .Sh HISTORY
 353 The original version of
 354 .Nm
 355 was written one evening in late 2010.
 356 This version had some problems and was put aside.
 357 The first working version was released in June 2013.
 358 .\" .Sh AUTHORS
 359 .\" .An David A. Holland
 360 .Sh BUGS
 361 Probably plenty.