libgcobol/README.runpath

Native Linux runtime search paths
================================

For native Linux builds with shared libraries enabled, libgcobol.spec adds
--enable-new-dtags and -rpath to ordinary GCobol links.  The path is the
configured toolexeclibdir, expanded by make so that multilib and
--enable-version-specific-runtime-libs layouts are respected.  No /opt path
is hard-coded.  DESTDIR is not part of the path.

The three runtime DSOs receive the same RUNPATH.  This is necessary because
ELF DT_RUNPATH applies to an object's direct dependencies, not recursively
to the dependencies of those dependencies.  Private dependencies installed
elsewhere still need their own suitable search paths.  This change does not
automatically discover arbitrary directories containing private libxml2,
libiconv, or other external dependencies.

The path is absolute.  An executable can be moved independently of the
compiler, but moving the runtime installation requires relinking programs
(or explicitly overriding the loader search).  $ORIGIN in a user executable
would refer to that executable's directory, not the compiler's directory.

--disable-libgcobol-rpath restores the previous runtime-path behavior.
Non-Linux targets, cross builds, and builds without shared libraries do not
receive these new ELF options.  Darwin's existing rpath flags are unchanged.
Static and static-PIE links receive no RUNPATH.  -static-libgcobol may still
need RUNPATH for the shared POSIX/compatibility libraries.  Shared COBOL
outputs receive RUNPATH too, for their own direct runtime dependencies.

The driver now loads libgcobol.spec for links with inputs even when the
user explicitly supplied -lgcobol or libgcobol.a.  It must not use the
"automatically add -lgcobol" decision to decide whether to load specs.
Compile-only, preprocess-only, assembly-only, relocatable, syntax-only,
-nostdlib and -nodefaultlibs invocations do not load the runtime specs.

Packaging
---------

1. Keep libgcobol.spec and the runtime DSOs in their configured installation
   locations.  Reconfigure/rebuild for a different final prefix.  Stage with
   DESTDIR; never configure the staging directory as the final prefix.

2. Stop registering the GCobol library directory in /etc/ld.so.conf.d and
   stop exporting a global LD_LIBRARY_PATH.  On upgrades, remove only the
   obsolete configuration owned/generated by this package, using the
   package manager's conffile migration machinery where applicable.  Refresh
   the loader cache after removing the old registration.  Do not delete
   unrelated or locally maintained loader configuration.

3. Removing global registration prevents unrelated programs such as apt
   from selecting GCobol's private libstdc++.so.6 or libgcc_s.so.1.  RUNPATH
   still makes ALL matching libraries in that directory eligible for the
   GCobol program itself.  Prefer system dependency packages when their ABI
   is sufficient.  If private GCC runtimes are necessary, bundle compatible
   versions deliberately; this patch does not provide per-SONAME isolation.

4. Build all packaged binaries and shared libraries against the oldest
   supported glibc baseline.  A RUNPATH cannot make a library requiring
   GLIBC_2.38 run against glibc 2.35.  Audit the compiler executables and any
   separately packaged tools too: this patch changes generated COBOL links
   and libgcobol DSOs, not the bootstrap compiler/tool link flags.

5. Previously linked COBOL executables do not acquire RUNPATH on upgrade.
   Rebuild those executables before relying on removal of the old global
   configuration.  Include this change in the package's migration notes.

Regression checks
-----------------

Run the mechanism tests on Linux with a C compiler and readelf:

    python3 libgcobol/testsuite/runpath.py

These exercise GCC spec expansion and the real ELF loader, including a
negative transitive-dependency test, but do not build the COBOL compiler.

After building and installing the patched compiler into a clean GNU/Linux
container with no GCobol loader configuration, run, for example:

    python3 libgcobol/testsuite/runpath.py \
      --gcobol /opt/gcobol/bin/gcobol \
      --runtime-dir /opt/gcobol/lib64

Use the actual configured runtime directory.  This tests ordinary linking,
explicit -lgcobol, the mf compatibility dialect, -static-libgcobol, separate
compilation, shared output, driver suppression options, all runtime DSO
tags, and execution with the loader cache inhibited.  It prints the actual
loaded libraries for review.  Static-libgcobol requires static archives to
have been built/installed.  Dependencies requiring ABI symbols missing
from the target system are a test failure, not a reason to restore global
loader registration.

In the package-install/upgrade test, also compare `ldd /usr/bin/apt` before
and after installation and run `apt --version`.  Its libstdc++ and libgcc_s
must remain the system copies.  Test fresh installation and upgrade from a
package that registered /opt/gcobol/lib64, plus removal of the new package.
Package scripts are maintained outside this upstream GCC source tree; the
exact migration edits must be made and tested in that packaging repository.