Linux defines several standard directories where shared libraries should be installed. The dynamic linker automatically searches these at runtime, so no LD_LIBRARY_PATH is needed once a library is installed correctly.

# View current ld.so.conf on your system:
$ cat /etc/ld.so.conf
include /etc/ld.so.conf.d/*.conf

# Many systems use the include-directory pattern:
$ ls /etc/ld.so.conf.d/
cuda.conf        libc.conf        x86_64-linux-gnu.conf

$ cat /etc/ld.so.conf.d/cuda.conf
/usr/local/cuda/lib64
/usr/local/cuda/lib

# After editing ld.so.conf, always run ldconfig to update the cache:

Installing our libdemo library system-wide requires root privileges since /usr/lib is not writable by regular users.

# Complete installation sequence for libdemo in /usr/lib

# Step 1: Become root
$ su
Password:

# Step 2: Move the real-name file to /usr/lib
# mv preserves the file's permissions and avoids a copy+delete
# (use cp -p if you want to keep the original for other uses)
# mv libdemo.so.1.0.1 /usr/lib/
# libdemo.so.1.0.1 is now at /usr/lib/libdemo.so.1.0.1

# Step 3: Create the soname symbolic link (relative, in same directory)
# ln -s libdemo.so.1.0.1 /usr/lib/libdemo.so.1

# Step 4: Create the linker name symbolic link
# ln -s libdemo.so.1 /usr/lib/libdemo.so

# Step 5: Run ldconfig to update the dynamic linker cache
# ldconfig

# Verify the installation:
# ls -l /usr/lib/libdemo.so*
# lrwxrwxrwx libdemo.so      -> libdemo.so.1
# lrwxrwxrwx libdemo.so.1    -> libdemo.so.1.0.1
# -rwxr-xr-x libdemo.so.1.0.1

# Now run the program WITHOUT LD_LIBRARY_PATH — it works!
$ exit    # back to normal user
$ ./prog
Called mod1-x1
Called mod2-x2

ldconfig is a system utility that does two important things:

• Scans library directories (standard dirs + those in /etc/ld.so.conf) and finds all shared libraries
• Creates/updates soname symbolic links to point to the most recent minor version of each major library version
• Rebuilds /etc/ld.so.cache — a binary cache file that the dynamic linker uses for fast library lookup at runtime

How ldconfig works internally:

# --- Using ldconfig ---

# Basic usage (must be root) - scan dirs and rebuild cache:
$ sudo ldconfig

# Verbose mode - shows which soname links are being created:
$ sudo ldconfig -v
/usr/lib:
        libdemo.so.1 -> libdemo.so.1.0.2
        libreadline.so.8 -> libreadline.so.8.2
        libssl.so.3 -> libssl.so.3.0.8
        ...

# List all libraries currently in the cache:
$ ldconfig -p
        libdemo.so.1 (libc6,x86-64) => /usr/lib/libdemo.so.1
        libreadline.so.8 (libc6,x86-64) => /usr/lib/x86_64-linux-gnu/libreadline.so.8.2
        libc.so.6 (libc6,x86-64) => /lib/x86_64-linux-gnu/libc.so.6
        ...

# Search for a specific library in the cache:
$ ldconfig -p | grep libdemo
        libdemo.so.1 (libc6,x86-64) => /usr/lib/libdemo.so.1

# Example: ldconfig automatically creates soname links
# Suppose you've installed THREE versions of libdemo:
# /usr/lib/libdemo.so.1.0.1   (older)
# /usr/lib/libdemo.so.1.0.2   (newer, bugfix)
# /usr/lib/libdemo.so.2.0.0   (new major version)

# After running ldconfig:
$ sudo ldconfig -v 2>&1 | grep libdemo
        libdemo.so.1 -> libdemo.so.1.0.2   # latest of major 1
        libdemo.so.2 -> libdemo.so.2.0.0   # latest of major 2

# ldconfig correctly creates TWO soname links:
# - libdemo.so.1 -> libdemo.so.1.0.2 (NOT 1.0.1 — picks the newest minor)
# - libdemo.so.2 -> libdemo.so.2.0.0

# This is the key power of ldconfig: it automatically maintains soname links!

If you want to install a library outside the standard directories (e.g., in /opt/myapp/lib), you can register that directory in /etc/ld.so.conf so ldconfig and the dynamic linker know to search there.

# Example: Installing libdemo in /opt/myapp/lib

# Step 1: Create the directory and install the library file
$ sudo mkdir -p /opt/myapp/lib
$ sudo cp libdemo.so.1.0.1 /opt/myapp/lib/
$ sudo ln -s libdemo.so.1.0.1 /opt/myapp/lib/libdemo.so.1
$ sudo ln -s libdemo.so.1 /opt/myapp/lib/libdemo.so

# Step 2: Register the directory in ldconfig config
# Method A: Add directly to /etc/ld.so.conf
$ echo "/opt/myapp/lib" | sudo tee -a /etc/ld.so.conf

# Method B (preferred): Create a separate .conf file in ld.so.conf.d/
$ echo "/opt/myapp/lib" | sudo tee /etc/ld.so.conf.d/myapp.conf

# Step 3: Rebuild the linker cache
$ sudo ldconfig

# Step 4: Verify it's in the cache
$ ldconfig -p | grep libdemo
        libdemo.so.1 (libc6,x86-64) => /opt/myapp/lib/libdemo.so.1

# Step 5: Now programs can link and run against the library
# without LD_LIBRARY_PATH:
$ gcc -o prog prog.c -ldemo
$ ./prog            # works without LD_LIBRARY_PATH!
Called mod1-x1
Called mod2-x2

The dynamic linker searches in this order:

# --- Diagnostic Tool 1: ldd ---
# ldd shows which shared libraries a program depends on
# and where the dynamic linker will find each one

$ ldd prog
        linux-vdso.so.1 (0x00007ffd3e9de000)
        libdemo.so.1 => /usr/lib/libdemo.so.1 (0x00007f3e5a200000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f3e5a000000)
        /lib64/ld-linux-x86-64.so.2 (0x00007f3e5a450000)

# If a library is NOT found, ldd shows:
#       libdemo.so.1 => not found    ← this means install failed or ldconfig not run

# --- Diagnostic Tool 2: readelf -d ---
# Shows the NEEDED entries (sonames) and RPATH/RUNPATH embedded in the binary

$ readelf -d prog | grep -E '(NEEDED|RPATH|RUNPATH|SONAME)'
 0x0000000000000001 (NEEDED)  Shared library: [libdemo.so.1]
 0x0000000000000001 (NEEDED)  Shared library: [libc.so.6]

# --- Diagnostic Tool 3: objdump -p ---
$ objdump -p prog | grep NEEDED
  NEEDED               libdemo.so.1
  NEEDED               libc.so.6

# --- Using rpath (embed library path in binary) ---
# For deployment where you can't touch /etc/ld.so.conf:
$ gcc -g -Wall -o prog prog.c -L/opt/myapp/lib -ldemo \
      -Wl,-rpath,/opt/myapp/lib
# prog will look in /opt/myapp/lib at runtime, always — no ldconfig needed
$ ./prog
Called mod1-x1

# --- Common Installation Mistakes & Fixes ---

# Problem 1: "cannot open shared object file: No such file or directory"
# Fix: Check if ldconfig has been run after installation
$ sudo ldconfig
$ ldd prog   # verify library is found now

# Problem 2: Wrong version loaded at runtime
# Fix: Check soname symlinks and ldconfig cache
$ ldconfig -p | grep libdemo
$ ls -la /usr/lib/libdemo.so*

# Problem 3: Library installed but gcc can't find it at link time
# Fix: Make sure the LINKER NAME symlink exists (libdemo.so, not just libdemo.so.1)
$ ls /usr/lib/libdemo.so   # must exist!
# If missing: sudo ln -s libdemo.so.1 /usr/lib/libdemo.so

# Problem 4: Installed in /usr/local/lib but not found
# Fix: /usr/local/lib must be in ldconfig config
$ cat /etc/ld.so.conf.d/*.conf | grep local
# If missing:
$ echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/local.conf
$ sudo ldconfig

#!/bin/bash
# install_shared_lib.sh — Production installation of libdemo
# Run as root or with sudo

set -e  # Exit on any error

LIB_NAME="libdemo"
MAJOR="1"
MINOR="0"
PATCH="2"
REAL_NAME="${LIB_NAME}.so.${MAJOR}.${MINOR}.${PATCH}"
SONAME="${LIB_NAME}.so.${MAJOR}"
LINKER_NAME="${LIB_NAME}.so"
INSTALL_DIR="/usr/lib"

echo "=== Installing ${REAL_NAME} to ${INSTALL_DIR} ==="

# Step 1: Copy the library file
if [ ! -f "./${REAL_NAME}" ]; then
    echo "ERROR: ${REAL_NAME} not found in current directory"
    exit 1
fi

cp -p "./${REAL_NAME}" "${INSTALL_DIR}/"
chmod 755 "${INSTALL_DIR}/${REAL_NAME}"
echo "[OK] Copied ${REAL_NAME} to ${INSTALL_DIR}"

# Step 2: Create soname symlink
ln -sf "${REAL_NAME}" "${INSTALL_DIR}/${SONAME}"
echo "[OK] Created ${SONAME} -> ${REAL_NAME}"

# Step 3: Create linker name symlink (points to soname, not real name)
ln -sf "${SONAME}" "${INSTALL_DIR}/${LINKER_NAME}"
echo "[OK] Created ${LINKER_NAME} -> ${SONAME}"

# Step 4: Run ldconfig to update the cache
ldconfig
echo "[OK] ldconfig cache updated"

# Step 5: Verify
echo ""
echo "=== Verification ==="
ls -la "${INSTALL_DIR}/${LIB_NAME}.so"*
echo ""
ldconfig -p | grep "${LIB_NAME}"
echo ""
echo "=== Installation complete! ==="