https://gcc.gnu.org/g:3b66b18fe806863e7b9a9bcb4bdaa0a6f28e8aab
commit r16-5714-g3b66b18fe806863e7b9a9bcb4bdaa0a6f28e8aab Author: Sandra Loosemore <[email protected]> Date: Tue Nov 18 23:34:09 2025 +0000 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: --- gcc/config/darwin.opt | 53 +++++---- gcc/doc/invoke.texi | 292 +++++++++++++++++++++++++++++--------------------- 2 files changed, 198 insertions(+), 147 deletions(-) diff --git a/gcc/config/darwin.opt b/gcc/config/darwin.opt index e275d846cd19..d6e6271f9cf2 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 8acf0317f737..02f2c9a6e933 100644 --- 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
