gcc/doc/gcc/gcc-command-options/description.rst

   1 Description
   2 ***********
   3
   4 When you invoke GCC, it normally does preprocessing, compilation,
   5 assembly and linking.  The 'overall options' allow you to stop this
   6 process at an intermediate stage.  For example, the :option:`-c` option
   7 says not to run the linker.  Then the output consists of object files
   8 output by the assembler.
   9 See :ref:`overall-options`.
  10
  11 Other options are passed on to one or more stages of processing.  Some options
  12 control the preprocessor and others the compiler itself.  Yet other
  13 options control the assembler and linker; most of these are not
  14 documented here, since you rarely need to use any of them.
  15
  16 .. index:: C compilation options
  17
  18 Most of the command-line options that you can use with GCC are useful
  19 for C programs; when an option is only useful with another language
  20 (usually C++), the explanation says so explicitly.  If the description
  21 for a particular option does not mention a source language, you can use
  22 that option with all supported languages.
  23
  24 .. index:: cross compiling, specifying machine version, specifying compiler version and target machine, compiler version, specifying, target machine, specifying
  25
  26 The usual way to run GCC is to run the executable called :samp:`gcc`, or
  27 :samp:`{machine}-gcc` when cross-compiling, or
  28 :samp:`{machine}-gcc-{version}` to run a specific version of GCC.
  29 When you compile C++ programs, you should invoke GCC as :samp:`g++`
  30 instead.  See :ref:`invoking-g++`,
  31 for information about the differences in behavior between :samp:`gcc`
  32 and :samp:`g++` when compiling C++ programs.
  33
  34 .. index:: grouping options, options, grouping
  35
  36 The :command:`gcc` program accepts options and file names as operands.  Many
  37 options have multi-letter names; therefore multiple single-letter options
  38 may *not* be grouped: :option:`-dv` is very different from :samp:`-d
  39 -v`.
  40
  41 .. index:: order of options, options, order
  42
  43 You can mix options and other arguments.  For the most part, the order
  44 you use doesn't matter.  Order does matter when you use several
  45 options of the same kind; for example, if you specify :option:`-L` more
  46 than once, the directories are searched in the order specified.  Also,
  47 the placement of the :option:`-l` option is significant.
  48
  49 Many options have long names starting with :samp:`-f` or with
  50 :samp:`-W`---for example,
  51 :option:`-fmove-loop-invariants`, :option:`-Wformat` and so on.  Most of
  52 these have both positive and negative forms; the negative form of
  53 :samp:`-ffoo` is :samp:`-fno-foo`.  This manual documents
  54 only one of these two forms, whichever one is not the default.
  55
  56 Some options take one or more arguments typically separated either
  57 by a space or by the equals sign (:samp:`=`) from the option name.
  58 Unless documented otherwise, an argument can be either numeric or
  59 a string.  Numeric arguments must typically be small unsigned decimal
  60 or hexadecimal integers.  Hexadecimal arguments must begin with
  61 the :samp:`0x` prefix.  Arguments to options that specify a size
  62 threshold of some sort may be arbitrarily large decimal or hexadecimal
  63 integers followed by a byte size suffix designating a multiple of bytes
  64 such as ``kB`` and ``KiB`` for kilobyte and kibibyte, respectively,
  65 ``MB`` and ``MiB`` for megabyte and mebibyte, ``GB`` and
  66 ``GiB`` for gigabyte and gigibyte, and so on.  Such arguments are
  67 designated by :samp:`{byte-size}` in the following text.  Refer to the NIST,
  68 IEC, and other relevant national and international standards for the full
  69 listing and explanation of the binary and decimal byte size prefixes.
  70
  71 .. only:: html
  72
  73     See :ref:`genindex`, for an index to GCC's options.