https://gcc.gnu.org/bugzilla/show_bug.cgi?id=93694
--- Comment #4 from Iain Sandoe <iains at gcc dot gnu.org> --- Created attachment 47938 --> https://gcc.gnu.org/bugzilla/attachment.cgi?id=47938&action=edit Update darwin opts descriptions Thanks for the comments. As background, (most of) these options have ben present in the Darwin toolchain since before my involvement - however they were never described; there is note in the GCC manual suggesting that the user should use the man page. The majority here are actually options passed on to the linker, and the details can be quite complex - so that the user should still make use of the manage (so I would not delete that statement from the GCC manual). The idea here is a brief summary to serve as a reminder for a more detailed description. Perhaps I should have left them undocumented .... an example of the manpage: https://www.manpagez.com/man/1/ld64/ In some cases (especially for determining which options are obsolete) several versions of the man pages were consulted - and the linker source code itself. ==== I will apply a patch that makes the following changes in a few days if there are no more comments (such comments are welcome): > Loads all members of archive libraries Load all members of archive libraries, rather than only those that satisfy undefined symbols. > The version of ld64 in use for this toolchain. -mtarget-linker <version> Specify that ld64 <version> is the toolchain linker for the current invocation. > Produce an output file that will bind symbols on load, rather than lazily. Generate an output executable that binds symbols on load, rather than lazily. > Produce a Mach-O bundle (file type MH_BUNDLE) Generate a Mach-O bundle (file type MH_BUNDLE). > This will allow relocs -read_only_relocs <treatment> Allow relocations in read-only pages (not recommended). >And a typo: > exectuable fixed. >Unnecessarily unspecific wording: > Allows setting the page 0 size to 4kb for certain special cases >What exactly are "certain special cases"? I don't think that can be reasonable answered in a brief option description, I suggest what's below, it is the user's responsibility to know when the option is required. -pagezero_size <size> Allows setting the page 0 size (for example, to 4kb) when required. double space: > architecture \"name\" fixed. > unnecessarily verbose: > Specify that the output file should be generated for architecture "name" > Why not simply: Generate output file for the named architecture. -arch <name> Generate output for architecture <name>. >anachronism: > MacOS X > Should that be macOS nowadays? Changed throughout. > off-by-one: > must record a greater > I think this should rather be "greater or equal". Actually, the man page is quite confusing on this option, I've tried to make this more specific: -compatibility_version <number> Set the version for the client interface. Client programs must record a value less than or equal to <number>, or the binding will fail at runtime. >double space: > dyld will fixed, > <treatment> Provided > (Obsolete after 10.3.9) Set > Shouldn't there be a tab between the words instead of the space? fixed. > -pagezero_size size > The other placeholders are written in <angle_brackets>, so should this one. done, as per the comment above. > (Obsolete, ld_classic only) -sectcreate segname sectname file > segname, sectname and file should be marked as <placeholders>. > (Obsolete, ld_classic only) -sectcreate segname sectname file -sectcreate <segname> <sectname> <file> Create section <sectname> in segment <segname> from the contents of <file>. > -segprot <segname> max_prot init_prot\tThe protection values are > This like only describes the syntax but doesn't lose a single word about the > effect. Indeed ... -segprot <segname> <max_prot> <init_prot> The virtual memory protections for segment <segname> are set to maximum and initial values <max_prot> and <init_prot> respectively. The specified values may contain \"r\", \"w\", \"x\" or \"-\" the latter meaning \"no access\". > -segs_read_only_addr address >Missing placeholder. > space-tab. -segs_read_only_addr <address> Specify that <address> is the base address of the read-only segments of a dylib. > Allows specifying >I hope that this option actually _sets_ the address instead of only _allowing_ >to set. (2 times) done as per segs_read_only_addr above. > Specifies content > That's another case of very unspecific wording. As the German translator I > have no idea what this could mean. This option is documented nowhere. It only > appears in the ChangeLogs, darwin.h and darwin.opt. As noted, the source for the information is outside the GCC tree - ld64 source / manages suggested change: Add extra information to the executable that can speed up dynamic loading (provided that dependent libraries are unchanged).
