systemd/tools/find-unused-library-symbols.py

#!/usr/bin/env python3
# SPDX-License-Identifier: LGPL-2.1-or-later

"""
Find unused symbols in a shared library.

This script analyzes a shared library and a list of executables that link
against it to determine which publicly exported symbols from the library
are not used by any of the executables or by the library itself internally.

The script checks for symbol usage in three ways:
1. Internal library references: Uses objdump -R to find relocations within
   the library that reference its own exported symbols
2. Executable dependencies: Uses nm to find undefined symbols in executables
   that match the library's exported symbols
3. Cross-references: Identifies symbols used across all provided binaries

This comprehensive approach ensures that symbols used internally by the
library are not incorrectly marked as unused.
"""

import argparse
import subprocess
import sys
from pathlib import Path


def get_exported_symbols(library_path):
    """
    Extract all exported (public) symbols from a shared library.

    Public API symbols (those starting with 'sd_') are excluded from the analysis
    since they cannot be removed or made private due to API compatibility requirements.

    Returns a set of symbol names that are defined and exported by the library.
    """
    try:
        result = subprocess.run(
            ['nm', '--dynamic', '--defined-only', '--extern-only', library_path],
            capture_output=True,
            text=True,
            check=True,
        )
    except subprocess.CalledProcessError as e:
        print(f'Error: Failed to run nm on {library_path}: {e}', file=sys.stderr)
        sys.exit(1)
    except FileNotFoundError:
        print("Error: 'nm' command not found. Please install binutils.", file=sys.stderr)
        sys.exit(1)

    symbols = set()
    for line in result.stdout.splitlines():
        parts = line.split()
        if len(parts) >= 3:
            # Format: address type name
            symbol_type = parts[1]
            symbol_name = parts[2]
            # Include text (T) and data (D, B, R) symbols
            if symbol_type in ('T', 'D', 'B', 'R', 'W'):
                # Strip version information (e.g., @@SD_SHARED or @SD_SHARED)
                symbol_name = symbol_name.split('@')[0]
                # Skip public API symbols (those starting with sd_)
                if symbol_name.startswith('sd_'):
                    continue
                symbols.add(symbol_name)

    return symbols


def get_undefined_symbols(executable_path):
    """
    Extract all undefined symbols from an executable.

    These are symbols that the executable expects to be provided by
    shared libraries it links against.
    """
    try:
        result = subprocess.run(
            ['nm', '--dynamic', '--undefined-only', executable_path],
            capture_output=True,
            text=True,
            check=True,
        )
    except subprocess.CalledProcessError as e:
        print(f'Warning: Failed to run nm on {executable_path}: {e}', file=sys.stderr)
        return set()
    except FileNotFoundError:
        print("Error: 'nm' command not found. Please install binutils.", file=sys.stderr)
        sys.exit(1)

    symbols = set()
    for line in result.stdout.splitlines():
        parts = line.split()
        if len(parts) >= 2:
            # Format: type name (no address for undefined symbols)
            symbol_name = parts[1]
            # Strip version information (e.g., @SD_SHARED)
            symbol_name = symbol_name.split('@')[0]
            symbols.add(symbol_name)

    return symbols


def verify_executable_links_library(executable_path, library_name):
    """
    Verify that an executable actually links against the given library.

    Returns True if the executable links against a library with the given name.
    """
    try:
        result = subprocess.run(
            ['ldd', executable_path],
            capture_output=True,
            text=True,
            check=True,
        )
    except (subprocess.CalledProcessError, FileNotFoundError):
        # If ldd fails or doesn't exist, we'll skip the verification
        return True

    # Check if library_name appears in the ldd output
    for line in result.stdout.splitlines():
        if library_name in line:
            return True

    return False


def get_library_internal_references(library_path, exported_symbols):
    """
    Find which exported symbols are referenced internally within the library itself.

    This uses objdump to look for relocations that reference the exported symbols.
    """
    try:
        result = subprocess.run(
            ['objdump', '-R', library_path],
            capture_output=True,
            text=True,
            check=True,
        )
    except subprocess.CalledProcessError as e:
        print(f'Warning: Failed to run objdump on {library_path}: {e}', file=sys.stderr)
        return set()
    except FileNotFoundError:
        print(
            "Warning: 'objdump' command not found. Internal references won't be detected.",
            file=sys.stderr,
        )
        return set()

    internal_refs = set()
    for line in result.stdout.splitlines():
        parts = line.split()
        if len(parts) >= 3:
            # objdump -R format: offset type symbol
            # The symbol is typically the last field
            symbol_name = parts[-1]
            # Strip version information
            symbol_name = symbol_name.split('@')[0]
            # Only include if it's one of our exported symbols
            if symbol_name in exported_symbols:
                internal_refs.add(symbol_name)

    return internal_refs


def find_unused_symbols(library_path, executable_paths, verify_linkage=True):
    """
    Find symbols exported by the library that are not used by any executable.

    Args:
        library_path: Path to the shared library
        executable_paths: List of paths to executables
        verify_linkage: Whether to verify executables link against the library

    Returns:
        Tuple of (unused_symbols, exported_symbols, used_symbols)
    """
    library_name = Path(library_path).name

    # Get all exported symbols from the library (excluding public API symbols)
    exported_symbols = get_exported_symbols(library_path)

    if not exported_symbols:
        print(f'Warning: No exported symbols found in {library_path}', file=sys.stderr)
        return set(), set(), set()

    # Collect all symbols used by the executables
    used_symbols = set()

    # First, check if the library references its own exported symbols internally
    internal_refs = get_library_internal_references(library_path, exported_symbols)
    used_symbols.update(internal_refs)

    for exe_path in executable_paths:
        # Optionally verify linkage
        if verify_linkage and not verify_executable_links_library(exe_path, library_name):
            print(f'Warning: {exe_path} does not appear to link against {library_name}', file=sys.stderr)

        undefined_symbols = get_undefined_symbols(exe_path)
        # Only count symbols that are actually exported by our library
        used_symbols.update(undefined_symbols & exported_symbols)

    # Find unused symbols
    unused_symbols = exported_symbols - used_symbols

    return unused_symbols, exported_symbols, used_symbols


def main():
    parser = argparse.ArgumentParser(
        description='Find unused exported symbols in a shared library',
    )
    parser.add_argument(
        'library',
        help='Path to the shared library to analyze',
    )
    parser.add_argument(
        'executables',
        nargs='+',
        help='Paths to executables that link against the library',
    )
    parser.add_argument(
        '--no-verify-linkage',
        action='store_true',
        help='Skip verification that executables actually link against the library',
    )
    parser.add_argument(
        '--show-used',
        action='store_true',
        help='Also show used symbols',
    )
    parser.add_argument(
        '--stats-only',
        action='store_true',
        help='Only show statistics, not individual symbols',
    )

    args = parser.parse_args()

    # Verify library exists
    library_path = Path(args.library)
    if not library_path.exists():
        print(f'Error: Library not found: {library_path}', file=sys.stderr)
        sys.exit(1)

    # Verify executables exist
    executable_paths = []
    for exe in args.executables:
        exe_path = Path(exe)
        if not exe_path.exists():
            print(f'Warning: Executable not found: {exe_path}', file=sys.stderr)
        else:
            executable_paths.append(str(exe_path))

    if not executable_paths:
        print('Error: No valid executables provided', file=sys.stderr)
        sys.exit(1)

    # Analyze symbols
    unused, exported, used = find_unused_symbols(
        str(library_path), executable_paths, verify_linkage=not args.no_verify_linkage
    )

    # Print results
    print(f'Analysis of {library_path.name}')
    print('=' * 70)
    print(f'Total exported symbols: {len(exported)}')
    print("  (excluding public API symbols starting with 'sd_')")
    print(f'Used symbols: {len(used)}')
    print(f'Unused symbols: {len(unused)}')
    print(f'Usage rate: {len(used) / len(exported) * 100:.1f}%' if exported else 'N/A')
    print()

    if not args.stats_only:
        if unused:
            print('Unused symbols:')
            print('-' * 70)
            for symbol in sorted(unused):
                print(f'  {symbol}')
            print()
        else:
            print('All exported symbols are used!')
            print()

        if args.show_used and used:
            print('Used symbols:')
            print('-' * 70)
            for symbol in sorted(used):
                print(f'  {symbol}')
            print()

    # Exit with non-zero if there are unused symbols (useful for CI)
    sys.exit(0 if not unused else 1)


if __name__ == '__main__':
    main()