gcc/doc/cpp/invocation.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: invocation, command line
   7
   8 .. _invocation:
   9
  10 Invocation
  11 ----------
  12
  13 Most often when you use the C preprocessor you do not have to invoke it
  14 explicitly: the C compiler does so automatically.  However, the
  15 preprocessor is sometimes useful on its own.  You can invoke the
  16 preprocessor either with the :command:`cpp` command, or via :command:`gcc -E`.
  17 In GCC, the preprocessor is actually integrated with the compiler
  18 rather than a separate program, and both of these commands invoke
  19 GCC and tell it to stop after the preprocessing phase.
  20
  21 The :command:`cpp` options listed here are also accepted by
  22 :command:`gcc` and have the same meaning.  Likewise the :command:`cpp`
  23 command accepts all the usual :command:`gcc` driver options, although those
  24 pertaining to compilation phases after preprocessing are ignored.
  25
  26 Only options specific to preprocessing behavior are documented here.
  27 Refer to the GCC manual for full documentation of other driver options.
  28
  29 .. only:: man
  30
  31   Synopsis
  32   ^^^^^^^^
  33
  34   cpp [ :option:`-D`:samp:`{macro}` [= :samp:`{defn}` ]...] [ :option:`-U`:samp:`{macro}` ]
  35       [ :option:`-I`:samp:`{dir}`...] [ :option:`-iquote`:samp:`{dir}`...]
  36       [ :option:`-M` | :option:`-MM` ] [ :option:`-MG` ] [ :option:`-MF` :samp:`{filename}` ]
  37       [ :option:`-MP` ] [ :option:`-MQ` :samp:`{target}`...]
  38       [ :option:`-MT` :samp:`{target}`...]
  39       :samp:`{infile}` [[ :option:`-o` ] :samp:`{outfile}` ]
  40
  41   Only the most useful options are given above; see below for a more
  42   complete list of preprocessor-specific options.
  43   In addition, :command:`cpp` accepts most :command:`gcc` driver options, which
  44   are not listed here.  Refer to the GCC documentation for details.
  45
  46 Options
  47 ^^^^^^^
  48
  49 The :command:`cpp` command expects two file names as arguments, :samp:`{infile}` and
  50 :samp:`{outfile}`.  The preprocessor reads :samp:`{infile}` together with any
  51 other files it specifies with :samp:`#include`.  All the output generated
  52 by the combined input files is written in :samp:`{outfile}`.
  53
  54 Either :samp:`{infile}` or :samp:`{outfile}` may be :option:`-`, which as
  55 :samp:`{infile}` means to read from standard input and as :samp:`{outfile}`
  56 means to write to standard output.  If either file is omitted, it
  57 means the same as if :option:`-` had been specified for that file.
  58 You can also use the :option:`-o outfile` option to specify the
  59 output file.
  60
  61 Unless otherwise noted, or the option ends in :samp:`=`, all options
  62 which take an argument may have that argument appear either immediately
  63 after the option, or with a space between option and argument:
  64 :option:`-Ifoo` and :option:`-I foo` have the same effect.
  65
  66 .. index:: grouping options, options, grouping
  67
  68 Many options have multi-letter names; therefore multiple single-letter
  69 options may *not* be grouped: :option:`-dM` is very different from
  70 :samp:`-d -M`.
  71
  72 .. index:: options
  73
  74 .. include:: ../../../doc/cppopts.rst
  75
  76
  77 .. include:: ../../../doc/cppdiropts.rst
  78
  79 .. only:: man
  80
  81   .. include:: copyright.rst