Add a paragraph about library types to the intro(3) manual page.
Obtained from: OpenBSD
MFC after: 1 week
Details
Details
mandoc output review and 'mandoc -Tlint' checks
Diff Detail
Diff Detail
- Repository
- rG FreeBSD src repository
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
There are a very large number of changes, so older changes are hidden. Show Older Changes
Comment Actions
Thanks for taking this on - it's useful information to have in user-facing or developer-facing documentation. There are quite a few things that don't directly match from OpenBSD that I've noted inline.
| share/man/man3/intro.3 | ||
|---|---|---|
| 286 | we don't/wont have these any longer | |
| 287 | Our .so numbers are not usually this high and we typically don't have major/minor components -- e.g. ours is /lib/libc.so.7. Note also that this example is in /lib, not /usr/lib. /usr/lib/libc.so is a symlink to that, and is what is actually used in the linking process. | |
| 327 | I'm not sure there's value in specifying mmap here, IMO it's sufficient to mention that rtld loads the shared libraries when the program is executed. | |
| 359 | .a for PIE binaries is something that we still need to resolve | |
| 365 | on modern ISAs this isn't really true, it's primarily i386 where this is an issue | |
| 375 | There are only two classes of libraries, so this seems a bit of an odd phrasing. | |
| 385 | this isn't really true, the index is generally created by passing the s flag to ar. ranlib is really only of historical interest | |
| 391 | Note that this option is documented as deprecated and will be removed. | |
Comment Actions
No MFC until no supported version has
| share/man/man3/intro.3 | ||
|---|---|---|
| 282 | /lib too maybe? | |
| 286 | Are they gone in 12.3 and 13.1? If not, then either no MFC or wait until no supported 12.x or 13.x has them anymore. | |
| 326 | Unless you mean they get loaded at a specific address. (Aren't shared libraries supposed to be position-independent?) Alternatively, "loads them into the process' virtual address space". | |
| 330–341 | 7 is from emaste's example above and 8 is the equivalent of 31 in the original. | |
| 369–370 | ranlib too if not removed per emaste's abovre=ve | |
| 375 | Or whatever they're called. | |
| 380–381 | Can a library have members that aren't relocatable files? | |
| share/man/man3/intro.3 | ||
|---|---|---|
| 293–294 | During static linking only the necessary object files are linked in, not the whole library. Perhaps "all necessary library code" would be better? | |
| 305 | As far as I understand, profiling libraries are somewhat obsolete in FreeBSD. For example, pmcstat(8) doesn't need them. However, they still exist so they need to be described here. | |
| 345 | More advantages: a namespace per shared library is available via hidden visibility, allowing multiple compilation units in a library to share things without making them available to other libraries; it is possible to load libraries dynamically via dlopen(3). | |
| 347 | Another disadvantage: calls across shared libraries are also slightly slower and cannot be inlined (not even with link time optimization). | |
| 354 | Does FreeBSD have a supported configuration without shared libraries? I expect no? | |
Comment Actions
Address comments
- mention /lib
- correct library version numbers
- don't mention mmap(2) use rtld for further documentation
- Remove documetation of WITHOUT_PROFILE since is option is deprecated
| share/man/man3/intro.3 | ||
|---|---|---|
| 293 | ... linked against a static library, ... | |
| 328 | As written, it's not clear what ld.so does and what rtld does; they are both described as loading the libraries when the program is executed. | |
| 366 | This section does not explain the difference between PIC and relocatable code. | |
| 372 | Are -fpic and -fPIC literally identical? If so, pick one, and don't mention the other. | |
Comment Actions
Other than the missing "space", English LGTM, but I can't speak about correctness.
| share/man/man3/intro.3 | ||
|---|---|---|
| 326 | ||
| share/man/man3/intro.3 | ||
|---|---|---|
| 372 | The common way of working is to use -fPIC only; on certain architectures, -fpic generates slightly more efficient code if the resulting file is smaller than an architecture-dependent size. I'd say -fpic need not be mentioned here. What should perhaps be mentioned is -fPIE which generates position-independent code for executables. That is, it makes the code position-independent but still assumes that it will be linked into an executable and not a shared library. This might be slightly more efficient. | |
Comment Actions
If nobody complaines, I would commit this change tomorrow to have it included for 14,.0-RELEASE.
Comment Actions
a few small comments but overall I think this is good info.
I'm not entirely sure intro(3) is the best place for this, but off hand I don't have a better one to suggest, and we can always move the text later.
Let me also tag @mhorne who's been looking at kernel documentation.
| share/man/man3/intro.3 | ||
|---|---|---|
| 296 | it can be inefficient with both disk space and memory usage during execution | |
| 305 | They aren't built by default any longer, so there's no point in documenting them for 14. | |
| 332 | I'd say either "version number" or "library version number" | |
| 333–337 | We probably need to document symbol versioning, too | |
| 340 | s/program/library/? | |
| 354 | No, so I don't think we need to say "on systems that support it." -shared is the default and the only case I am aware of that it would be necessary is if some CFLAGS contained -static and it needed to be overridden. | |
Comment Actions
Thanks for the ping. I am trying not to be too picky here, but a couple more things stick out to me.
FYI, I found some well-hidden documentation talking a bit about shared libraries, in particular the naming convention:
https://docs.freebsd.org/en/books/developers-handbook/policies/#policies-shlib
| share/man/man3/intro.3 | ||
|---|---|---|
| 286–288 | Is this incomplete? I think I don't understand what this is meant to show. | |
| 294 | Otherwise you are saying, "when it is linked, it will be linked". | |
| 308 | ||
| 333 | ||
| 377–378 | The choice is yours, but it does not seem clearly relevant to me. | |
| share/man/man3/intro.3 | ||
|---|---|---|
| 286–288 | In a former version of this differential there where profiling versions descriptions, which was removed a while ago in FreeBSD. I would suggest to rewrite Typically, a library will have a number of variants: to A library has the following naming convention: | |
Comment Actions
Looks good, even if imperfect, let's get it committed.
| share/man/man3/intro.3 | ||
|---|---|---|
| 286–288 | Okay I understand. Still, the naming convention is explained in detail in the paragraphs following. It is strange to present the single arbitrary library name in an indented block like this. I think it could be removed, but I leave it to your judgement to decide what to do. | |