The Darwin target options documentation was a bit of a mess, with several
undocumented options, some that were listed in the option summary or mentioned
in discussion of other options but not actually documented, and a large
number of options listed in darwin.opt as being obsolete.
I've undocumented all the obsolete options to streamline things, plus a few
others that seem to have been intentially undocumented or supplanted by
other options. For the others that were probably supposed to documented,
I did my best to guess what they're for by reading the code or just
copying the documentation string in the .opt file, but it's certainly
possible I screwed some up.
gcc/ChangeLog
PR other/122243
* config/darwin.opt (findirect-virtual-calls): Mark as Undocumented.
(fterminated-vtables): Likewise.
(multi_module): Likewise.
(multiply_defined): Likewise.
(multiply_defined_unused): Likewise.
(no_dead_strip_inits_and_terms): Likewise.
(noprefixbinding): Likewise.
(nomultidefs): Likewise.
(noprebind): Likewise.
(noseglinkedit): Likewise.
(ObjC, ObjC++): Add documentation strings.
(object): Mark as Undocumented.
(prebind): Likewise.
(prebind_all_twolevel_modules): Likewise.
(private_bundle): Likewise.
(sectobjectsymbols): Likewise.
(sectorder): Likewise.
(seg_addr_table_filename): Likewise.
(segcreate): Likewise.
(seglinkedit): Likewise.
(single_module): Likewise.
(X): Likewise.
(y): Likewise.
(Mach): Likewise.
* doc/invoke.texi (Option Summary) <Darwin Options>: Improve
alphabetization of the list. Remove obsolete/undocumented
options and add missing entries.
(Darwin Options): Add documentation for -arch, -dependency-file,
-fapple-kext, -matt-stubs, -fconstant-cfstrings, -mdynamic-no-pic,
-asm_macosx_version_min, -msymbol-stubs, -mtarget-linker,
-ObjC, -ObjC++, -Wnonportable-cfstrings. Update the list
of options passed to the linker to remove obsolete options
and add missing ones; also move the block of @opindex entries
before the list items instead of putting it in the middle.
---
gcc/config/darwin.opt | 53 ++++----
gcc/doc/invoke.texi | 300 ++++++++++++++++++++++++------------------
2 files changed, 202 insertions(+), 151 deletions(-)
diff --git a/gcc/config/darwin.opt b/gcc/config/darwin.opt
index e275d846cd1..d6e6271f9cf 100644
--- a/gcc/config/darwin.opt
+++ b/gcc/config/darwin.opt
@@ -169,8 +169,9 @@ filelist
Driver RejectNegative Separate
Supply a list of objects to be linked from a file, rather than the command
line.
+; specs turn this into fapple-kext.
findirect-virtual-calls
-Driver RejectNegative
+Driver RejectNegative Undocumented
Used for generating code for some older kernel revisions.
flat_namespace
@@ -189,8 +190,9 @@ framework
Driver RejectNegative Separate
-framework <name> The linker should search for the framework <name> in
the framework search path.
+; specs turn this into fapple-kext.
fterminated-vtables
-Driver RejectNegative
+Driver RejectNegative Undocumented
Used for generating code for some older kernel revisions.
gfull
@@ -222,19 +224,19 @@ Driver RejectNegative
Usually \"private extern\" (hidden) symbols are made local when linking, this
command suppresses that such that they remain exported.
multi_module
-Driver RejectNegative
+Driver RejectNegative Undocumented
(Obsolete after 10.4) Multi modules are ignored at runtime since macOS 10.4.
multiply_defined
-Driver RejectNegative Separate
+Driver RejectNegative Separate Undocumented
(Obsolete after 10.4) -multiply_defined <treatment> Provided a mechanism
for warning about symbols defined in multiple dylibs.
multiply_defined_unused
-Driver RejectNegative Separate
+Driver RejectNegative Separate Undocumented
(Obsolete after 10.4) -multiply_defined_unused <treatment> Provided a
mechanism for warning about symbols defined in the current executable also
being defined in linked dylibs.
no_dead_strip_inits_and_terms
-Driver RejectNegative
+Driver RejectNegative Undocumented
(Obsolete) Current linkers never dead-strip these items, so the option is not
needed.
nodefaultexport
@@ -246,40 +248,45 @@ Driver RejectNegative
Do not add default run paths (for the compiler library directories) to
executables, modules or dynamic libraries.
nofixprebinding
-Driver RejectNegative
+Driver RejectNegative Undocumented
(Obsolete after 10.3.9) Set MH_NOPREFIXBINDING, in an executable.
nomultidefs
-Driver RejectNegative
+Driver RejectNegative Undocumented
(Obsolete after 10.4) Set MH_NOMULTIDEFS in an umbrella framework.
noprebind
-Driver RejectNegative Negative(prebind)
+Driver RejectNegative Negative(prebind) Undocumented
(Obsolete) LD_PREBIND is no longer supported.
noseglinkedit
-Driver RejectNegative Negative(seglinkedit)
+Driver RejectNegative Negative(seglinkedit) Undocumented
(Obsolete) This is the default.
ObjC
Driver RejectNegative
+Equivalent to -xobjective-c.
ObjC++
Driver RejectNegative
+Equivalent to -xobjective-c++.
+; This option is only used in STARTFILE_SPEC and has never been
+; documented since it was added in 2002, so it appears to be
+; intentionally undocumented.
object
-Driver RejectNegative
+Driver RejectNegative Undocumented
pagezero_size
Driver RejectNegative Separate
-pagezero_size <size> Allows setting the page 0 size to 4kb when required.
prebind
-Driver RejectNegative Negative(noprebind)
+Driver RejectNegative Negative(noprebind) Undocumented
(Obsolete) LD_PREBIND is no longer supported.
prebind_all_twolevel_modules
-Driver RejectNegative
+Driver RejectNegative Undocumented
(Obsolete) LD_PREBIND is no longer supported.
preload
@@ -287,7 +294,7 @@ Driver RejectNegative
Produces a Mach-O file suitable for embedded/ROM use.
private_bundle
-Driver RejectNegative
+Driver RejectNegative Undocumented
(Obsolete) Allowed linking to proceed with \"-flat_namespace\" when a linked
bundle contained a symbol also exported from the main executable.
pthread
@@ -310,11 +317,11 @@ Driver RejectNegative Separate Args(3)
-sectcreate <segname> <sectname> <file> Create section <sectname> in
segment <segname> from the contents of <file>.
sectobjectsymbols
-Driver RejectNegative Separate Args(2)
+Driver RejectNegative Separate Args(2) Undocumented
(Obsolete) -sectobjectsymbols <segname> <sectname> Setting a local symbol
at the start of a section is no longer supported.
sectorder
-Driver RejectNegative Separate Args(3)
+Driver RejectNegative Separate Args(3) Undocumented
(Obsolete) -sectorder <segname> <sectname> <orderfile> Replaced by a more
general option \"-order_file\".
seg_addr_table
@@ -323,7 +330,7 @@ Driver RejectNegative Separate
; This is only usable by the ld_classic linker.
seg_addr_table_filename
-Driver RejectNegative Separate
+Driver RejectNegative Separate Undocumented
(Obsolete, ld_classic only) -seg_addr_table_filename <path>.
seg1addr
@@ -336,11 +343,11 @@ Driver RejectNegative Separate Args(2)
; This is only usable by the ld_classic linker.
segcreate
-Driver RejectNegative Separate Args(3)
+Driver RejectNegative Separate Args(3) Undocumented
(Obsolete, ld_classic only) -sectcreate <segname> <sectname> <file> Allowed
creation of a section from a file.
seglinkedit
-Driver RejectNegative Negative(noseglinkedit)
+Driver RejectNegative Negative(noseglinkedit) Undocumented
(Obsolete) Object files with LINKEDIT sections are no longer supported.
segprot
@@ -356,7 +363,7 @@ Driver RejectNegative Separate
-segs_read_write_addr <address> Specify that <address> is the base
address address of the read-write segments of a dylib.
single_module
-Driver RejectNegative
+Driver RejectNegative Undocumented
(Obsolete) This is the default.
sub_library
@@ -405,12 +412,12 @@ Logs which symbol(s) caused an object to be loaded.
;(Obsolete, ignored) Strip symbols starting with "L", this is the default.
X
-Driver RejectNegative
+Driver RejectNegative Undocumented
y
-Driver RejectNegative Joined
+Driver RejectNegative Joined Undocumented
(Obsolete, ignored) Old support similar to \"-whyload\".
Mach
-Driver RejectNegative
+Driver RejectNegative Undocumented
(Obsolete and unhandled by ld64, ignored) ld should produce an executable
(only handled by ld_classic).
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 8d5582d6d15..9cfeb690c21 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1033,31 +1033,33 @@ Objective-C and Objective-C++ Dialects}.
-fwritable-relocated-rdata -mpe-aligned-commons}
@emph{Darwin Options} (@ref{Darwin Options})
-@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal
--arch_only -bind_at_load -bundle -bundle_loader
+@gccoptlist{-all_load -allowable_client -arch @var{name}
+-arch_errors_fatal -asm_macosx_version_min=@var{version}
+-bind_at_load -bundle -bundle_loader
-client_name -compatibility_version -current_version
-dead_strip
--dependency-file -dylib_file -dylinker_install_name
+-dependency-file -dylib_file -dylinker -dylinker_install_name
-dynamic -dynamiclib -exported_symbols_list
--filelist -flat_namespace -force_cpusubtype_ALL
--force_flat_namespace -headerpad_max_install_names
--iframework
--image_base -init -install_name -keep_private_externs
--multi_module -multiply_defined -multiply_defined_unused
--noall_load -no_dead_strip_inits_and_terms -nodefaultrpaths
--nofixprebinding -nomultidefs -noprebind -noseglinkedit
--pagezero_size -prebind -prebind_all_twolevel_modules
--private_bundle -read_only_relocs -sectalign
--sectobjectsymbols -whyload -seg1addr
--sectcreate -sectobjectsymbols -sectorder
--segaddr -segs_read_only_addr -segs_read_write_addr
--seg_addr_table -seg_addr_table_filename -seglinkedit
+-fapple-kext -fconstant-cfstrings -ffix-and-continue
+-filelist -findirect-data -flat_namespace -force_cpusubtype_ALL
+-force_flat_namespace -framework @var{name} -gfull -gused
+-headerpad_max_install_names -iframework
+-image_base -init @var{symbol-name} -install_name -keep_private_externs
+-matt-stubs -mconstant-cfstrings -mdynamic-no-pic
+-mfix-and-continue -mkernel -mmacosx-version-min=@var{version}
+-mone-byte-bool -msymbol-stubs -mtarget-linker@r{[}=@r{]}@var{version}
+-nodefaultexport -nodefaultrpaths
+-pagezero_size -preload -read_only_relocs
+-sectalign -sectcreate
+-seg_addr_table
+-seg1addr -segaddr
-segprot -segs_read_only_addr -segs_read_write_addr
--single_module -static -sub_library -sub_umbrella
--twolevel_namespace -umbrella -undefined
--unexported_symbols_list -weak_reference_mismatches
--whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version}
--mkernel -mone-byte-bool}
+-sub_library -sub_umbrella
+-twolevel_namespace -twolevel_namespace_hints
+-umbrella -undefined -unexported_symbols_list
+-weak_framework @var{name} -weak_reference_mismatches
+-whatsloaded -whyload
+-F -ObjC -ObjC++ -Wnonportable-cfstrings}
@emph{DEC Alpha Options} (@ref{DEC Alpha Options})
@gccoptlist{-mno-fp-regs -msoft-float
@@ -26752,6 +26754,24 @@ directory. The main difference between this
@option{-iframework} and
warn about constructs contained within header files found via
@var{dir}. This option is valid only for the C family of languages.
+@opindex arch
+@item -arch @var{name}
+Generate output for architecture @var{name}. As described above, GCC
+generates output for the architecture it was configured for, using its
+usual options to select subarchitecture variants. The @option{-arch}
+option is accepted for compatibility, but an error is diagnosed if
+@var{name} is inconsistent with GCC's own idea of the target architecture.
+
+@opindex dependency-file
+@item -dependency-file @var{filename}
+Alias for the preprocessor option @option{-MF @var{filename}}.
+@xref{Preprocessor Options}.
+
+@opindex fapple-kext
+@opindex fno-apple-kext
+@item -fapple-kext
+Generate code for Darwin loadable kernel extensions.
+
@opindex gused
@item -gused
Emit debugging information for symbols that are used. For stabs
@@ -26762,28 +26782,45 @@ This is by default ON@.
@item -gfull
Emit debugging information for all symbols and types.
-@opindex fconstant-cfstrings
-@item -fconstant-cfstrings
-The @option{-fconstant-cfstrings} is an alias for
@option{-mconstant-cfstrings}.
+@opindex matt-stubs
+@opindex mno-att-stubs
+@item -matt-stubs
+@itemx -mno-att-stubs
+Enable AT&T-style PIC stubs. This is the default when supported by
+the target architecture (currently x86 only).
@opindex mconstant-cfstrings
+@opindex mno-constant-cfstrings
+@opindex fconstant-cfstrings
@item -mconstant-cfstrings
+@itemx -fconstant-cfstrings
When the NeXT runtime is being used (the default on these systems), override
any @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"}
literals to be laid out as constant CoreFoundation strings.
-@opindex mmacosx-version-min
-@item -mmacosx-version-min=@var{version}
-The earliest version of MacOS X that this executable will run on is
-@var{version}. Typical values supported for @var{version} include @code{12},
-@code{10.12}, and @code{10.5.8}.
+@option{-fconstant-cfstrings} is an alias for @option{-mconstant-cfstrings}.
-If the compiler was built to use the system's headers by default,
-then the default for this option is the system version on which the
-compiler is running, otherwise the default is to make choices that
-are compatible with as many systems and code bases as possible.
+@opindex mdynamic-no-pic
+@opindex mno-dynamic-no-pic
+@item -mdynamic-no-pic
+Generate code suitable for executables (not shared libraries). This
+option is incompatible with @option{-fpic}, @option{-fPIC}, @option{-fpie},
+or @option{-fPIE}.
+
+@opindex mfix-and-continue
+@opindex mno-fix-and-continue
+@opindex ffix-and-continue
+@opindex findirect-data
+@item -mfix-and-continue
+@itemx -ffix-and-continue
+@itemx -findirect-data
+Generate code suitable for fast turnaround development, such as to
+allow GDB to dynamically load @file{.o} files into already-running
+programs. @option{-findirect-data} and @option{-ffix-and-continue}
+are provided for backwards compatibility.
@opindex mkernel
+@opindex mno-kernel
@item -mkernel
Enable kernel development mode. The @option{-mkernel} option sets
@option{-static}, @option{-fno-common}, @option{-fno-use-cxa-atexit},
@@ -26793,6 +26830,23 @@ applicable. This mode also sets @option{-mno-altivec},
@option{-msoft-float}, @option{-fno-builtin} and
@option{-mlong-branch} for PowerPC targets.
+@opindex mmacosx-version-min
+@opindex asm_macosx_version_min
+@item -mmacosx-version-min=@var{version}
+@itemx -asm_macosx_version_min=@var{version}
+The @option{-mmacosx-version-min} option specifies
+the earliest version of MacOS X that this executable will run on is
+@var{version}. Typical values supported for @var{version} include @code{12},
+@code{10.12}, and @code{10.5.8}.
+
+If the compiler was built to use the system's headers by default,
+then the default for this option is the system version on which the
+compiler is running, otherwise the default is to make choices that
+are compatible with as many systems and code bases as possible.
+
+@option{-asm_macosx_version_min=@var{version}} is similar, but the GCC
+driver passes its @var{version} information only to the assembler.
+
@opindex mone-byte-bool
@item -mone-byte-bool
Override the defaults for @code{bool} so that @code{sizeof(bool)==1}.
@@ -26806,16 +26860,37 @@ without that switch. Using this switch may require
recompiling all
other modules in a program, including system libraries. Use this
switch to conform to a non-default data model.
-@opindex mfix-and-continue
-@opindex ffix-and-continue
-@opindex findirect-data
-@item -mfix-and-continue
-@itemx -ffix-and-continue
-@itemx -findirect-data
-Generate code suitable for fast turnaround development, such as to
-allow GDB to dynamically load @file{.o} files into already-running
-programs. @option{-findirect-data} and @option{-ffix-and-continue}
-are provided for backwards compatibility.
+@opindex msymbol-stubs
+@opindex mno-symbol-stubs
+@item -msymbol-stubs
+@itemx -mno-symbol-stubs
+Force generation of external symbol indirection stubs for PIC references.
+By default, this option is enabled automatically if the target linker
+version (@option{-mtarget-linker}) is old enough to require them.
+
+@opindex mtarget-linker
+@item -mtarget-linker=@var{version}
+@item -mtarget-linker @var{version}
+Specify the target @command{ld64} version, overriding any version specified
+in the GCC configuration. Newer linker versions support improved code
+generation in some cases, for example for PIC code.
+
+@opindex ObjC
+@item -ObjC
+Equivalent to @samp{-x objective-c}; specifies that the input is
+is Objective-C source code.
+
+@opindex ObjC++
+@item -ObjC++
+Equivalent to @samp{-x objective-c++}; specifies that the input is
+is Objective-C++ source code.
+
+@opindex Wnonportable-cfstrings
+@opindex Wno-nonportable-cfstrings
+@item -Wnonportable-cfstrings
+@itemx -Wno-nonportable-cfstrings
+Warn if constant CoreFoundation string objects contain non-portable
+characters. This warning is enabled by default.
@opindex all_load
@item -all_load
@@ -26860,13 +26935,57 @@ the embedded runpath is added by default unless the
user adds
@option{-nodefaultrpaths} to the link line. Run paths are needed
(and therefore enforced) to build on macOS version 10.11 or later.
+@opindex nodefaultexport
+@item -nodefaultexport
+Do not add default symbol exports to modules or dynamic libraries.
+
+@opindex allowable_client
+@opindex client_name
+@opindex compatibility_version
+@opindex current_version
+@opindex dead_strip
+@opindex dylib_file
+@opindex dylinker
+@opindex dylinker_install_name
+@opindex dynamic
+@opindex exported_symbols_list
+@opindex filelist
+@opindex flat_namespace
+@opindex force_flat_namespace
+@opindex framework
+@opindex headerpad_max_install_names
+@opindex image_base
+@opindex init
+@opindex install_name
+@opindex keep_private_externs
+@opindex pagezero_size
+@opindex read_only_relocs
+@opindex sectalign
+@opindex sectcreate
+@opindex seg_addr_table
+@opindex seg1addr
+@opindex segaddr
+@opindex segprot
+@opindex segs_read_only_addr
+@opindex segs_read_write_addr
+@opindex sub_library
+@opindex sub_umbrella
+@opindex twolevel_namespace
+@opindex twolevel_namespace_hints
+@opindex umbrella
+@opindex undefined
+@opindex unexported_symbols_list
+@opindex weak_framework
+@opindex weak_reference_mismatches
+@opindex whatsloaded
+@opindex whyload
@item -allowable_client @var{client_name}
@itemx -client_name
@itemx -compatibility_version
@itemx -current_version
@itemx -dead_strip
-@itemx -dependency-file
@itemx -dylib_file
+@itemx -dylinker
@itemx -dylinker_install_name
@itemx -dynamic
@itemx -exported_symbols_list
@@ -26874,113 +26993,38 @@ the embedded runpath is added by default unless the
user adds
@need 800
@itemx -flat_namespace
@itemx -force_flat_namespace
+@itemx -framework
@itemx -headerpad_max_install_names
@itemx -image_base
-@itemx -init
+@itemx -init @var{symbol-name}
@itemx -install_name
@itemx -keep_private_externs
-@itemx -multi_module
-@itemx -multiply_defined
-@itemx -multiply_defined_unused
@need 800
-@itemx -noall_load
-@itemx -no_dead_strip_inits_and_terms
-@itemx -nofixprebinding
-@itemx -nomultidefs
-@itemx -noprebind
-@itemx -noseglinkedit
@itemx -pagezero_size
-@itemx -prebind
-@itemx -prebind_all_twolevel_modules
-@itemx -private_bundle
+@itemx -preload
@need 800
@itemx -read_only_relocs
@itemx -sectalign
-@itemx -sectobjectsymbols
-@itemx -whyload
-@itemx -seg1addr
@itemx -sectcreate
-@itemx -sectobjectsymbols
-@itemx -sectorder
-@itemx -segaddr
-@itemx -segs_read_only_addr
-@need 800
-@itemx -segs_read_write_addr
@itemx -seg_addr_table
-@itemx -seg_addr_table_filename
-@itemx -seglinkedit
+@itemx -seg1addr
+@itemx -segaddr
+@need 800
@itemx -segprot
@itemx -segs_read_only_addr
@itemx -segs_read_write_addr
-@itemx -single_module
-@itemx -static
@itemx -sub_library
@need 800
-@opindex allowable_client
-@opindex client_name
-@opindex compatibility_version
-@opindex current_version
-@opindex dead_strip
-@opindex dependency-file
-@opindex dylib_file
-@opindex dylinker_install_name
-@opindex dynamic
-@opindex exported_symbols_list
-@opindex filelist
-@opindex flat_namespace
-@opindex force_flat_namespace
-@opindex headerpad_max_install_names
-@opindex image_base
-@opindex init
-@opindex install_name
-@opindex keep_private_externs
-@opindex multi_module
-@opindex multiply_defined
-@opindex multiply_defined_unused
-@opindex noall_load
-@opindex no_dead_strip_inits_and_terms
-@opindex nofixprebinding
-@opindex nomultidefs
-@opindex noprebind
-@opindex noseglinkedit
-@opindex pagezero_size
-@opindex prebind
-@opindex prebind_all_twolevel_modules
-@opindex private_bundle
-@opindex read_only_relocs
-@opindex sectalign
-@opindex sectobjectsymbols
-@opindex whyload
-@opindex seg1addr
-@opindex sectcreate
-@opindex sectobjectsymbols
-@opindex sectorder
-@opindex segaddr
-@opindex segs_read_only_addr
-@opindex segs_read_write_addr
-@opindex seg_addr_table
-@opindex seg_addr_table_filename
-@opindex seglinkedit
-@opindex segprot
-@opindex segs_read_only_addr
-@opindex segs_read_write_addr
-@opindex single_module
-@opindex static
-@opindex sub_library
-@opindex sub_umbrella
-@opindex twolevel_namespace
-@opindex umbrella
-@opindex undefined
-@opindex unexported_symbols_list
-@opindex weak_reference_mismatches
-@opindex whatsloaded
@itemx -sub_umbrella
@itemx -twolevel_namespace
+@itemx -twolevel_namespace_hints
@itemx -umbrella
@itemx -undefined
@itemx -unexported_symbols_list
+@itemx -weak_framework
@itemx -weak_reference_mismatches
@itemx -whatsloaded
+@itemx -whyload
These options are passed to the Darwin linker. The Darwin linker man page
describes them in detail.
@end table
--
2.39.5
