Jonathan, you said the manage is clear. I just show you that is not. You don't change the topic to whether my expectation is realistic or not. The previous email is in response to those who just ask others who said to read the man page. I do not expect manage to be a tutorial. I know the manpage is limited. But for those who tell others to read man page, don’t say so. It is meaningless given the limitation of manage. On Fri, Apr 23, 2021 at 3:05 AM Jonathan Wakely <jwakely.gcc@xxxxxxxxx> wrote: > > > On Thu, 22 Apr 2021, 23:25 Peng Yu, <pengyu.ut@xxxxxxxxx> wrote: > >> On 4/22/21, Jonathan Wakely <jwakely.gcc@xxxxxxxxx> wrote: >> > On Thu, 22 Apr 2021 at 19:45, Peng Yu wrote: >> >> The man is not well written in this and is confusing. It also doesn't >> >> explain the underlying details. >> > >> > The manual seems quite clear regarding those options. >> >> Here is why the manpage of these 4 options is poorly written. >> >> > -fpic >> > Generate position-independent code (PIC) suitable for use in >> a shared library, >> >> The above sentence means it can be used for shared libraries or can >> just be used for shared library? >> > > If it meant *only* for shared libraries it would say so. > > The man page is not a tutorial, so it tells you what you need to know for > practical usage. If you want to create a shared library, you want to know > the option to use for that. Explaining the exact effect of -fpic here (on > all the different architectures) would make it less useful to most readers. > > Explaining that PIC code can also be used in non-shared library code isn't > necessary here. Most readers either don't care or don't need to know > (because they're not creating shared libraries and not using the option), > or they already know. > > >> It is ambiguous as written in this way. >> > > I disagree. If it meant only suitable for shared libraries it would say so. > > >> > if supported for the target machine. >> >> If not supported on the target machine, so what? How do I know what >> target machines support it? >> > > The ones that let you use the option, without an error. The list of > targets is always changing, listing every single one in every place in the > manual is not practical. > > >> > Such code accesses all constant addresses through a global >> offset table (GOT). >> >> "Such code" is to give a definition of any position-independent code. >> Or more narrowly, just mean the code generated by this option. >> > > This is the description of GCC's option, not a tutorial on PIC in general. > You need to read it in that context, not assume it's trying to teach you > everything you curious about. > > Your expectations of what this text is doing seem to be part of your > problem. > > > >> > The dynamic loader resolves the GOT entries when the program starts >> (the dynamic loader is not part of GCC; it is part of the operating >> system). If the >> GOT size for the linked executable exceeds a >> machine-specific maximum size, you get an error message from the >> linker indicating that -fpic does not work; in that case, >> recompile with -fPIC instead. >> >> This is a forward reference to -fPIC. It hasn't explained what -fPIC >> is at this point in the manpage. >> > > > So what? It's *right* below, the very next option documented. > > >> > (These maximums are 8k on the SPARC, 28k on AArch64 and 32k on the m68k >> and RS/6000. The x86 has no such limit.) >> >> This seems to be an incompletely mentioned list of architectures. What >> about other architectures? As mentioned in this thread, the upper and >> lower case options are no different on x86. But this can not be seen >> here. >> > > Erm, it says this option gives an error if you need to use -fPIC instead > because of exceeding a limit for -fpic, and tells you "x86 has no such > limit". Most people would be able to understand that if there is no limit > for x86, then the -fPIC option that removes any limit is no different from > -fpic. > > It tells you the architectures with limits. If your architecture isn't > given, you can assume either it has no limit, or is so obscure that you > probably already know its properties (maybe you're using a modified GCC > with support for an architecture that isn't in upstream GCC, so of course > can't be documented in the upstream manual). > > You keep implying you want the manual to give an exhaustive list of every > possible situation for every option. That's unreasonable. > > >> > Position-independent code requires special support, and >> therefore works only on certain machines. For the x86, GCC supports PIC >> for System V but not for the Sun 386i. >> > Code >> > generated for the IBM RS/6000 is always position-independent. >> >> So -fpic should not be specified on IBM RS/6000? Is it still a >> relevant architecture nowadays? It seems to be an old architecture >> which is not relevant nowadays. This seems to be some history text >> lingering on the manpage. Why not delete them from the manpage? >> >> https://en.wikipedia.org/wiki/IBM_RISC_System/6000 > > > > As stated in another reply, it's what GCC calls PowerPC. There are lots of > references to rs/6000 in the GCC manual, do you think they should all be > deleted? (The answer is no, they shouldn't). > > >> >> > When this flag is set, the macros "__pic__" and "__PIC__" are >> defined to 1. >> >> What these values are for? If I were to write it, I would add a clause >> to explain what it is for. Like "... are defined to 1, which is for >> blah blah." >> > > > They're not "for" anything specific. They are defined so that code that > wants to know if it is being compiled as PIC can detect it by checking for > the macros. What that is for depends on the code being compiled, not on GCC. > > If you don't understand how such macros can be useful for conditional > compilation, maybe you should just ignore this part. For people who do want > to detect of PIC is being generated, this tells them how to do it. The fact > you don't know why that's useful is not a flaw in the docs. Again, this is > not a tutorial. > > So your "if I were to write it" suggestion would not improve the manual. > Your complaints about it being badly written are not helped by suggestions > that would make it worse. > > >> > -fPIC >> If supported for the target machine, emit >> position-independent code, suitable for dynamic linking and avoiding >> any limit on the size of the global offset table. >> >> The above description doesn't apply to -fpic. Or they equally apply to >> -fpic. I don't see the difference between -fpic and -fPIC up reading >> here. >> > > Seriously? The -fpic description said it might fail if a limit is > exceeded. This says it avoids any limits. Can you really not relate those > two pieces of information? > > > >> > This option makes a difference on AArch64, m68k, PowerPC and SPARC. >> >> Difference of what? > > > Different from -fpic. Are you unable to retain any context between two > successive paragraphs? > > > It could mean on these systems, specifying this >> option can be different from not specifying them. Or it could mean >> this option has different effects on these systems. Again it is an >> ambiguous sentence. >> >> > Position-independent code requires special support, and >> therefore works only on certain machines. >> >> What special support? What certain machines? >> > > That level of detail is not needed here. You can try the option and see if > it works on your machine. > > > >> > When this flag is set, the macros "__pic__" and "__PIC__" are >> defined to 2. >> >> Same question. What are these for? And how they are used? >> > > See above. > > > >> > -fpie >> > -fPIE >> These options are similar to -fpic and -fPIC, but the >> generated position-independent code can be only linked into >> executables. >> >> This is also ambiguous. What does "linked into executables" mean? >> "shared library" can also be linked into executables? The wording >> choice should be reconsidered. As I understand from previous >> discussion. This seems to mean, to make shared library, -fpic/-fPIC >> should be used. To make executable -fpie/-fPIE should be used. But as >> it is written, it is confusing. >> >> > Usually these options are used to compile code that will be linked >> using the -pie GCC option. >> >> What "usual" cases are referred? >> > > > When creating a position independent executable. If you want to use -fpie > without using the -pie linker option, presumably you have an unusual case > and know what you're doing. > > In the usual case, you compile a PIE with -fpie or -fPIE and link with > -pie. > > >> > -fpie and -fPIE both define the macros "__pie__" and >> "__PIE__". The macros have the value 1 for -fpie and 2 for -fPIE. >> >> What are these used for? >> > > See above. > > >> > If you want more >> > details, you can always go looking in the code. Also see page 15 in >> > https://www.akkadia.org/drepper/dsohowto.pdf >> >> The problem is not just "more details". It is the man page is poorly >> written. >> > > You are doing a lot of complaining and objecting. Maybe you should write > something better. > > > >> This dsohowto.pdf document does not help to answer my question of >> -fpic/-fPIC/-fpie/-fPIE at this moment. As it is written, "The most >> important recommendation is to always use -fpic or -fPIC when >> generating code which ends up in DSOs. " It doesn't explain what -fpic >> and -fPIC are, and their difference. So it does not help. >> > > > Did you even look at page 15? It gives a precise example of code > generation differences for the two options. So you expect that for every > single architecture and every kind of symbol access? Because that's > completely unreasonable. > > > > >> > More generally, https://lwn.net/Articles/276782/ has links to a series >> > of great blog posts about symbol relocations and linking. >> > https://www.airs.com/blog/archives/549 is from the same author. >> >> Article 549 says "It turns out to be quite simple to create a PIE: a >> PIE is simply an executable shared library." So this also causes >> confusion here. The "shared library" in "Generate >> position-independent code (PIC) suitable for use in a shared library," >> actually means "shared library" that is not executable? >> >> By "executable", it means whether it can be run or not? Many .so files >> (see below) do have the x permission. So the word "executable" is also >> ambiguous? >> >> $ ls -lgG /lib/x86_64-linux-gnu/libc-2.31.so >> -rwxr-xr-x 1 1839792 2021/01/05-00:47:42 /lib/x86_64-linux-gnu/ >> libc-2.31.so >> >> "To make a shared library executable you just need to give it a >> PT_INTERP segment and appropriate startup code." >> >> Although there is this explanation of executable afterward, it is >> again confusing. The following .so file also has .interp. I don't know >> what "startup code" specifically refers to. But it does have some >> startup code. However, I don't think the author means this file is an >> "executable". My understanding of "executable" is just something that >> can run. >> >> $ readelf -x .interp /lib/x86_64-linux-gnu/libc-2.31.so >> >> Hex dump of section '.interp': >> 0x00193f20 2f6c6962 36342f6c 642d6c69 6e75782d /lib64/ld-linux- >> 0x00193f30 7838362d 36342e73 6f2e3200 x86-64.so.2. >> >> $ objdump -d /lib/x86_64-linux-gnu/libc-2.31.so |grep start >> 26b97: 48 8b 05 a2 73 19 00 mov 0x1973a2(%rip),%rax >> # >> 1bdf40 <_dl_starting_up> >> 0000000000026c20 <__libc_start_main@@GLIBC_2.2.5>: >> 26c3a: 48 8b 15 ff 72 19 00 mov 0x1972ff(%rip),%rdx >> # >> 1bdf40 <_dl_starting_up> >> ... >> >> Do you see what is wrong with writeup like these? >> >> Any verbal explanation on a complex topic like is very likely to end >> up confusions and ambiguities. I don't know the best solution. > > > > So you don't like the information other people have provided, and you > don't have a better suggestion. OK. > > > > But it > > seems concrete runnable examples >> (https://linux.xidian.edu.cn/git/xry111/pie_vs_pic >> is good in this regard) and explaining the disassembled results (it >> lacks this aspect though to understand what exactly is going on, I am >> not blaming it (as it is not made for this purpose), just to mention >> the fact) is one way to go to fully resolve these problems. >> > > Well maybe you should write your own book on it. So far you have objected > and argued about every point when people have tried to help answer your > questions. I won't be trying again. > > > >> Nevertheless, the manpage is poorly written even from a pure English >> language point of view. >> > > > You need to read more than one sentence at a time. It's not a tutorial > intended to be read from start to finish like a book, it's a reference > document. > > -- Regards, Peng
