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)
Tue, Nov 26, 1:47 PM
Unknown Object (File)
Mon, Nov 25, 5:12 AM
Unknown Object (File)
Sat, Nov 23, 10:59 PM
Unknown Object (File)
Sat, Nov 23, 1:33 AM
Unknown Object (File)
Thu, Nov 21, 12:26 PM
Unknown Object (File)
Wed, Nov 20, 2:11 AM
Unknown Object (File)
Tue, Nov 19, 3:37 PM
Unknown Object (File)
Fri, Nov 15, 6:16 PM

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 Passed
Unit
No Test Coverage
Build Status
Buildable 53701
Build 50592: arc lint + arc unit

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
281

we don't/wont have these any longer

282

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.

322

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.

354

.a for PIE binaries is something that we still need to resolve

360

on modern ISAs this isn't really true, it's primarily i386 where this is an issue

370

There are only two classes of libraries, so this seems a bit of an odd phrasing.

380

this isn't really true, the index is generally created by passing the s flag to ar. ranlib is really only of historical interest

386

Note that this option is documented as deprecated and will be removed.

No MFC until no supported version has

share/man/man3/intro.3
277

/lib too maybe?

281

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.

321

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".

325–336

7 is from emaste's example above and 8 is the equivalent of 31 in the original.

370

Or whatever they're called.

375–376

Can a library have members that aren't relocatable files?

378–379

ranlib too if not removed per emaste's abovre=ve

This revision now requires changes to proceed.Sep 17 2022, 1:48 AM
share/man/man3/intro.3
288–289

During static linking only the necessary object files are linked in, not the whole library. Perhaps "all necessary library code" would be better?

300

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.

340

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).

342

Another disadvantage: calls across shared libraries are also slightly slower and cannot be inlined (not even with link time optimization).

349

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
288

... linked against a static library, ...

323

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.

361

This section does not explain the difference between PIC and relocatable code.

367

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

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
291

it can be inefficient with both disk space and memory usage during execution

300

They aren't built by default any longer, so there's no point in documenting them for 14.

327

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.

328–332

We probably need to document symbol versioning, too

335

s/program/library/?

349

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
302

Should it be "linked dynamically"?

328
386–387

Why?

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

Address comments of @mhorne

share/man/man3/intro.3
328

Good catch! :)

386–387

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
281–283

Is this incomplete? I think I don't understand what this is meant to show.

289

Otherwise you are saying, "when it is linked, it will be linked".

303
328
386–387

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
281–283

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
281–283

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