usm/slopdocs/structure.usm.manifest.executable-scripts.md

USM Executable Scripts Reference

Overview

USM packages use executable scripts to handle different phases of package lifecycle. Scripts are defined in the execs section of MANIFEST.usm and receive specific arguments based on their purpose.

Script Types

build

Required script that compiles source code into binaries.

Arguments: [build-directory]

• build-directory: Path where build output should be placed

Environment Variables:

• USM_DESTDIR, USM_PREFIX, USM_BINDIR, etc. are set

Example:

#!/bin/bash
set -e

build_dir=$1

cd ${build_dir}
meson setup ${src_dir} --prefix=${PREFIX} --libdir=${LIBDIR}
ninja

install

Optional script that installs built files to destination directory.

Arguments: [build-directory] [install-directory] [install-type]

• build-directory: Path containing build output
• install-directory: Path where files should be installed (DESTDIR)
• install-type: "fresh", "upgrade", or "downgrade"

Environment Variables:

• DESTDIR is overridden to install-directory
• Other USM variables are available

Example:

#!/bin/bash
set -e

build_dir=$1
install_dir=$2
install_type=$3

cd ${build_dir}
meson install --destdir ${install_dir}

postInstall

Optional script that runs after USM installs resources to system.

Arguments: [build-directory] [install-type]

• build-directory: Path containing build output
• install-type: "fresh", "upgrade", or "downgrade"

Use Case: System integration, cache generation, service registration

Example:

#!/bin/bash
set -e

build_dir=$1
install_type=$2

# Update desktop database
update-desktop-database

# Update icon cache
gtk-update-icon-cache -f -t /usr/share/icons/hicolor

remove

Optional script that runs before USM removes package resources.

Arguments: [remove-type]

• remove-type: "final", "upgrade", or "downgrade"

Use Case: Cleanup, service stopping, data preservation

Example:

#!/bin/bash
set -e

remove_type=$1

# Stop service if being upgraded
if [ "$remove_type" != "final" ]; then
    systemctl stop myapp || true
fi

# Remove user data only on final removal
if [ "$remove_type" = "final" ]; then
    rm -rf /var/lib/myapp
fi

acquire

Optional script that downloads and extracts source code.

Arguments: None Working Directory: Package root directory

Use Case: Projects without native USM support, repository packaging

Dependencies: Listed in depends.acquire section

Example:

#!/bin/bash
set -e

ARCHIVE_URL="https://github.com/example/myapp/archive/v1.0.0.tar.gz"
ARCHIVE_NAME="source.tar.gz"
EXTRACT_DIR="."

echo "Downloading source..."
wget -O ${ARCHIVE_NAME} ${ARCHIVE_URL}

echo "Extracting archive..."
tar -xzf ${ARCHIVE_NAME} --strip-components=1

echo "Cleaning up..."
rm ${ARCHIVE_NAME}

Script Requirements

Permissions

All scripts must be executable:

chmod +x scripts/build.sh

Error Handling

Scripts should:

• Use set -e to exit on errors
• Return appropriate exit codes
• Handle cleanup on failure

Environment Variables

USM sets these variables for all scripts:

• USM_DESTDIR: Destination directory
• USM_PREFIX: Installation prefix
• USM_BINDIR: Binary directory
• USM_INCLUDEDIR: Include directory
• USM_DATADIR: Data directory
• USM_INFODIR: Info directory
• USM_LIBDIR: Library directory
• USM_MANDIR: Manual directory
• USM_LIBEXECDIR: Libexec directory
• USM_LOCALEDIR: Locale directory
• USM_LOCALSTATEDIR: Local state directory
• USM_SBINDIR: System binary directory
• USM_SHAREDSTATEDIR: Shared state directory
• USM_SYSCONFIGDIR: Configuration directory
• USM_TAGSDIR: Tags directory

Script Locations

Scripts can be placed anywhere in the package, but common conventions:

• scripts/: Directory at package root
• usm-scripts/: Directory at package root
• Package root: For simple packages

Build System Integration

Meson

#!/bin/bash
set -e

src_dir=$(pwd)
build_dir=$1

cd ${build_dir}
meson setup ${src_dir} --prefix=${PREFIX} --libdir=${LIBDIR} --bindir=${BINDIR} --includedir=${INCLUDEDIR}
ninja

Make

#!/bin/bash
set -e

src_dir=$(pwd)
build_dir=$1

cd ${build_dir}
make PREFIX=${PREFIX} LIBDIR=${LIBDIR}

CMake

#!/bin/bash
set -e

src_dir=$(pwd)
build_dir=$1

cd ${build_dir}
cmake ${src_dir} -DCMAKE_INSTALL_PREFIX=${PREFIX} -DCMAKE_INSTALL_LIBDIR=${LIBDIR}
make

Progress Reporting

When using ninjaStyleProgress flag, USM parses build output for progress:

• Looks for pattern: [current/total]
• Updates progress bar accordingly
• Requires build system to output this format

Best Practices

Script Design

• Keep scripts focused on single responsibility
• Use absolute paths when available
• Handle all required arguments
• Validate environment before execution

Error Handling

• Check for required dependencies
• Validate input arguments
• Provide meaningful error messages
• Clean up temporary files on exit

Portability

• Use POSIX-compliant shell syntax
• Avoid bash-specific features when possible
• Test on target systems
• Consider different directory layouts

Security

• Validate input parameters
• Use secure temporary directories
• Avoid command injection vulnerabilities
• Follow principle of least privilege

---

This reference provides complete specification for USM executable scripts used throughout package lifecycle management.