doc: Document the 'validate-runpath' phase.

* doc/guix.texi (Build Systems): Replace paragraph about RUNPATH
validation with a cross-reference.
(Build Phases): Add 'validate-runpath' phase, with the paragraph taken
above.
This commit is contained in:
Ludovic Courtès 2022-07-05 13:53:44 +02:00
parent f14895d0c4
commit ef97576972
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5

View file

@ -8524,14 +8524,8 @@ the number specified as the @option{--cores} option of
This Boolean, @code{#t} by default, determines whether to ``validate'' This Boolean, @code{#t} by default, determines whether to ``validate''
the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
as executables) previously installed by the @code{install} phase. as executables) previously installed by the @code{install} phase.
@xref{phase-validate-runpath, the @code{validate-runpath} phase}, for
This validation step consists in making sure that all the shared details.
libraries needed by an ELF binary, which are listed as
@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
@code{DT_RUNPATH} entry of that binary. In other words, it ensures that
running or using those binaries will not result in a ``file not found''
error at run time. @xref{Options, @option{-rpath},, ld, The GNU
Linker}, for more information on @code{RUNPATH}.
@item #:substitutable? @item #:substitutable?
This Boolean, @code{#t} by default, tells whether the package outputs This Boolean, @code{#t} by default, tells whether the package outputs
@ -9610,6 +9604,21 @@ Patch shebangs on the installed executable files.
Strip debugging symbols from ELF files (unless @code{#:strip-binaries?} Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
is false), copying them to the @code{debug} output when available is false), copying them to the @code{debug} output when available
(@pxref{Installing Debugging Files}). (@pxref{Installing Debugging Files}).
@cindex RUNPATH, validation
@anchor{phase-validate-runpath}
@item validate-runpath
Validate the @code{RUNPATH} of ELF binaries, unless
@code{#:validate-runpath?} is false (@pxref{Build Systems}).
This validation step consists in making sure that all the shared
libraries needed by an ELF binary, which are listed as @code{DT_NEEDED}
entries in its @code{PT_DYNAMIC} segment, appear in the
@code{DT_RUNPATH} entry of that binary. In other words, it ensures that
running or using those binaries will not result in a ``file not found''
error at run time. @xref{Options, @option{-rpath},, ld, The GNU
Linker}, for more information on @code{RUNPATH}.
@end table @end table
Other build systems have similar phases, with some variations. For Other build systems have similar phases, with some variations. For