gcc/doc/gcc/gcc-command-options/machine-dependent-options/darwin-options.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 .. program:: Darwin
   7
   8 .. index:: Darwin options
   9
  10 .. _darwin-options:
  11
  12 Darwin Options
  13 ^^^^^^^^^^^^^^
  14
  15 These options are defined for all architectures running the Darwin operating
  16 system.
  17
  18 FSF GCC on Darwin does not create 'fat' object files; it creates
  19 an object file for the single architecture that GCC was built to
  20 target.  Apple's GCC on Darwin does create 'fat' files if multiple
  21 :option:`-arch` options are used; it does so by running the compiler or
  22 linker multiple times and joining the results together with
  23 :samp:`lipo`.
  24
  25 The subtype of the file created (like :samp:`ppc7400` or :samp:`ppc970` or
  26 :samp:`i686`) is determined by the flags that specify the ISA
  27 that GCC is targeting, like :option:`-mcpu` or :option:`-march`.  The
  28 :option:`-force_cpusubtype_ALL` option can be used to override this.
  29
  30 The Darwin tools vary in their behavior when presented with an ISA
  31 mismatch.  The assembler, :samp:`as`, only permits instructions to
  32 be used that are valid for the subtype of the file it is generating,
  33 so you cannot put 64-bit instructions in a :samp:`ppc750` object file.
  34 The linker for shared libraries, :samp:`/usr/bin/libtool`, fails
  35 and prints an error if asked to create a shared library with a less
  36 restrictive subtype than its input files (for instance, trying to put
  37 a :samp:`ppc970` object file in a :samp:`ppc7400` library).  The linker
  38 for executables, :command:`ld`, quietly gives the executable the most
  39 restrictive subtype of any of its input files.
  40
  41 .. option:: -Fdir
  42
  43   Add the framework directory :samp:`{dir}` to the head of the list of
  44   directories to be searched for header files.  These directories are
  45   interleaved with those specified by :option:`-I` options and are
  46   scanned in a left-to-right order.
  47
  48   A framework directory is a directory with frameworks in it.  A
  49   framework is a directory with a :samp:`Headers` and/or
  50   :samp:`PrivateHeaders` directory contained directly in it that ends
  51   in :samp:`.framework`.  The name of a framework is the name of this
  52   directory excluding the :samp:`.framework`.  Headers associated with
  53   the framework are found in one of those two directories, with
  54   :samp:`Headers` being searched first.  A subframework is a framework
  55   directory that is in a framework's :samp:`Frameworks` directory.
  56   Includes of subframework headers can only appear in a header of a
  57   framework that contains the subframework, or in a sibling subframework
  58   header.  Two subframeworks are siblings if they occur in the same
  59   framework.  A subframework should not have the same name as a
  60   framework; a warning is issued if this is violated.  Currently a
  61   subframework cannot have subframeworks; in the future, the mechanism
  62   may be extended to support this.  The standard frameworks can be found
  63   in :samp:`/System/Library/Frameworks` and
  64   :samp:`/Library/Frameworks`.  An example include looks like
  65   ``#include <Framework/header.h>``, where :samp:`Framework` denotes
  66   the name of the framework and :samp:`header.h` is found in the
  67   :samp:`PrivateHeaders` or :samp:`Headers` directory.
  68
  69 .. option:: -iframeworkdir
  70
  71   Like :option:`-F` except the directory is a treated as a system
  72   directory.  The main difference between this :option:`-iframework` and
  73   :option:`-F` is that with :option:`-iframework` the compiler does not
  74   warn about constructs contained within header files found via
  75   :samp:`{dir}`.  This option is valid only for the C family of languages.
  76
  77 .. option:: -gused
  78
  79   Emit debugging information for symbols that are used.  For stabs
  80   debugging format, this enables :option:`-feliminate-unused-debug-symbols`.
  81   This is by default ON.
  82
  83 .. option:: -gfull
  84
  85   Emit debugging information for all symbols and types.
  86
  87 .. option:: -mmacosx-version-min=version
  88
  89   The earliest version of MacOS X that this executable will run on
  90   is :samp:`{version}`.  Typical values of :samp:`{version}` include ``10.1``,
  91   ``10.2``, and ``10.3.9``.
  92
  93   If the compiler was built to use the system's headers by default,
  94   then the default for this option is the system version on which the
  95   compiler is running, otherwise the default is to make choices that
  96   are compatible with as many systems and code bases as possible.
  97
  98 .. option:: -mkernel
  99
 100   Enable kernel development mode.  The :option:`-mkernel` option sets
 101   :option:`-static`, :option:`-fno-common`, :option:`-fno-use-cxa-atexit`,
 102   :option:`-fno-exceptions`, :option:`-fno-non-call-exceptions`,
 103   :option:`-fapple-kext`, :option:`-fno-weak` and :option:`-fno-rtti` where
 104   applicable.  This mode also sets :option:`-mno-altivec`,
 105   :option:`-msoft-float`, :option:`-fno-builtin` and
 106   :option:`-mlong-branch` for PowerPC targets.
 107
 108 .. option:: -mone-byte-bool
 109
 110   Override the defaults for ``bool`` so that ``sizeof(bool)==1``.
 111   By default ``sizeof(bool)`` is ``4`` when compiling for
 112   Darwin/PowerPC and ``1`` when compiling for Darwin/x86, so this
 113   option has no effect on x86.
 114
 115   .. warning::
 116
 117     The :option:`-mone-byte-bool` switch causes GCC
 118     to generate code that is not binary compatible with code generated
 119     without that switch.  Using this switch may require recompiling all
 120     other modules in a program, including system libraries.  Use this
 121     switch to conform to a non-default data model.
 122
 123 .. option:: -mfix-and-continue, -ffix-and-continue, -findirect-data
 124
 125   Generate code suitable for fast turnaround development, such as to
 126   allow GDB to dynamically load :samp:`.o` files into already-running
 127   programs.  :option:`-findirect-data` and :option:`-ffix-and-continue`
 128   are provided for backwards compatibility.
 129
 130 .. option:: -all_load
 131
 132   Loads all members of static archive libraries.
 133   See man ld(1) for more information.
 134
 135 .. option:: -arch_errors_fatal
 136
 137   Cause the errors having to do with files that have the wrong architecture
 138   to be fatal.
 139
 140 .. option:: -bind_at_load
 141
 142   Causes the output file to be marked such that the dynamic linker will
 143   bind all undefined references when the file is loaded or launched.
 144
 145 .. option:: -bundle
 146
 147   Produce a Mach-o bundle format file.
 148   See man ld(1) for more information.
 149
 150 .. option:: -bundle_loader {executable}
 151
 152   This option specifies the :samp:`{executable}` that will load the build
 153   output file being linked.  See man ld(1) for more information.
 154
 155 .. option:: -dynamiclib
 156
 157   When passed this option, GCC produces a dynamic library instead of
 158   an executable when linking, using the Darwin :samp:`libtool` command.
 159
 160 .. option:: -force_cpusubtype_ALL
 161
 162   This causes GCC's output file to have the :samp:`ALL` subtype, instead of
 163   one controlled by the :option:`-mcpu` or :option:`-march` option.
 164
 165 .. option:: -allowable_client  {client_name}
 166 .. option:: -compatibility_version
 167 .. option:: -current_version
 168 .. option:: -dead_strip
 169 .. option:: -dependency-file
 170 .. option:: -dylib_file
 171 .. option:: -dylinker_install_name
 172 .. option:: -dynamic
 173 .. option:: -exported_symbols_list
 174 .. option:: -filelist
 175 .. option:: -flat_namespace
 176 .. option:: -force_flat_namespace
 177 .. option:: -headerpad_max_install_names
 178 .. option:: -image_base
 179 .. option:: -init
 180 .. option:: -install_name
 181 .. option:: -keep_private_externs
 182 .. option:: -multi_module
 183 .. option:: -multiply_defined
 184 .. option:: -multiply_defined_unused
 185 .. option:: -noall_load
 186 .. option:: -no_dead_strip_inits_and_terms
 187 .. option:: -nofixprebinding
 188 .. option:: -nomultidefs
 189 .. option:: -noprebind
 190 .. option:: -noseglinkedit
 191 .. option:: -pagezero_size
 192 .. option:: -prebind
 193 .. option:: -prebind_all_twolevel_modules
 194 .. option:: -private_bundle
 195 .. option:: -read_only_relocs
 196 .. option:: -sectalign
 197 .. option:: -sectobjectsymbols
 198 .. option:: -whyload
 199 .. option:: -seg1addr
 200 .. option:: -sectcreate
 201 .. option:: -sectobjectsymbols
 202 .. option:: -sectorder
 203 .. option:: -segaddr
 204 .. option:: -segs_read_only_addr
 205 .. option:: -segs_read_write_addr
 206 .. option:: -seg_addr_table
 207 .. option:: -seg_addr_table_filename
 208 .. option:: -seglinkedit
 209 .. option:: -segprot
 210 .. option:: -segs_read_only_addr
 211 .. option:: -segs_read_write_addr
 212 .. option:: -single_module
 213 .. option:: -static
 214 .. option:: -sub_library
 215 .. option:: -sub_umbrella
 216 .. option:: -twolevel_namespace
 217 .. option:: -umbrella
 218 .. option:: -undefined
 219 .. option:: -unexported_symbols_list
 220 .. option:: -weak_reference_mismatches
 221 .. option:: -whatsloaded
 222
 223   These options are passed to the Darwin linker.  The Darwin linker man page
 224   describes them in detail.