Page MenuHomeFreeBSD

Document library types in the intro(3) manual page
ClosedPublic

Authored by gbe on Sep 15 2022, 3:45 PM.
Tags
None
Referenced Files
Unknown Object (File)
Sat, Oct 5, 12:51 PM
Unknown Object (File)
Thu, Oct 3, 2:27 PM
Unknown Object (File)
Wed, Oct 2, 9:56 AM
Unknown Object (File)
Sun, Sep 29, 8:02 PM
Unknown Object (File)
Sat, Sep 28, 7:42 PM
Unknown Object (File)
Fri, Sep 27, 12:24 AM
Unknown Object (File)
Thu, Sep 26, 11:09 AM
Unknown Object (File)
Tue, Sep 24, 4:34 AM

Details

Summary

Add a paragraph about library types to the intro(3) manual page.

Obtained from: OpenBSD
MFC after: 1 week

Test Plan

mandoc output review and 'mandoc -Tlint' checks

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
gbe requested review of this revision.Sep 15 2022, 3:45 PM

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.

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?

This revision now requires changes to proceed.Sep 17 2022, 1:48 AM
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?

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
gbe marked 16 inline comments as done.Apr 24 2023, 8:59 AM
rpokala added inline comments.
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.

Other than the missing "space", English LGTM, but I can't speak about correctness.

share/man/man3/intro.3
326
This revision is now accepted and ready to land.Apr 26 2023, 9:42 PM
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.

gbe marked 2 inline comments as done.
  • Address comments
This revision now requires review to proceed.Sep 24 2023, 12:03 PM
gbe marked 2 inline comments as done.Sep 24 2023, 12:04 PM

If nobody complaines, I would commit this change tomorrow to have it included for 14,.0-RELEASE.

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"
"library number" to me suggests that there's some sort of ID number for the library, like libc is library 1, libz is library 2, etc.

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.

gbe marked 7 inline comments as done.
  • Address comments

Seems like a good addition, and this page is a reasonable place to put this information.

share/man/man3/intro.3
307

Should it be "linked dynamically"?

333
377–378

Why?

gbe marked 2 inline comments as done.Oct 20 2023, 7:45 AM

Address comments of @mhorne

share/man/man3/intro.3
333

Good catch! :)

377–378

For reference of options I think. I can remove it, if necessary.

gbe marked an inline comment as done.Oct 26 2023, 11:56 AM

@emaste @mhorne any comments on the recent update?

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.

gbe marked 5 inline comments as done.
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:

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.

This revision is now accepted and ready to land.Nov 14 2023, 7:28 PM