doc, darwin: Clean up Darwin options and documentation [PR122243]

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.

diff --git a/gcc/config/darwin.opt b/gcc/config/darwin.opt
index e275d846cd19d7ef6c86dbc45aeadf5a67e30f55..d6e6271f9cf2a7c66d9bf21654a827b5ab2d73f8 100644 (file)
--- 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 8acf0317f737e26fd3cbab77fa1ecbd368f21d79..02f2c9a6e933b6328e6ca3f089de405b54ec6ccf 100644 (file)
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1034,31 +1034,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
@@ -26931,6 +26933,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
@@ -26941,28 +26961,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},
@@ -26972,6 +27009,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}.
@@ -26985,16 +27039,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
@@ -27039,127 +27114,96 @@ 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.
 
-@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_install_name
-@itemx -dynamic
-@itemx -exported_symbols_list
-@itemx -filelist
-@need 800
-@itemx -flat_namespace
-@itemx -force_flat_namespace
-@itemx -headerpad_max_install_names
-@itemx -image_base
-@itemx -init
-@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
-@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 -segprot
-@itemx -segs_read_only_addr
-@itemx -segs_read_write_addr
-@itemx -single_module
-@itemx -static
-@itemx -sub_library
-@need 800
+@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 dependency-file
 @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 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 seg1addr
+@opindex segaddr
 @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 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 -dylib_file
+@itemx -dylinker
+@itemx -dylinker_install_name
+@itemx -dynamic
+@itemx -exported_symbols_list
+@itemx -filelist
+@need 800
+@itemx -flat_namespace
+@itemx -force_flat_namespace
+@itemx -framework
+@itemx -headerpad_max_install_names
+@itemx -image_base
+@itemx -init @var{symbol-name}
+@itemx -install_name
+@itemx -keep_private_externs
+@need 800
+@itemx -pagezero_size
+@itemx -preload
+@need 800
+@itemx -read_only_relocs
+@itemx -sectalign
+@itemx -sectcreate
+@itemx -seg_addr_table
+@itemx -seg1addr
+@itemx -segaddr
+@need 800
+@itemx -segprot
+@itemx -segs_read_only_addr
+@itemx -segs_read_write_addr
+@itemx -sub_library
+@need 800
 @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