Skip to content

Package Management

Overview

TSI manages packages through a local repository system. Packages are defined as JSON files and can have multiple versions.

Package Repository

The package repository is located at ~/.tsi/packages/ by default. Each package is defined as a JSON file.

Updating the Repository

# Update from default repository
tsi update

# Update from custom repository
tsi update --repo https://github.com/user/repo.git

# Update from local directory
tsi update --local /path/to/packages

Installing Packages

Basic Installation

# Install latest version
tsi install <package-name>

# Install specific version
tsi install <package-name>@<version>

Installation Process

When you install a package, TSI:

  1. Resolves Dependencies: Checks all required dependencies
  2. Builds Dependency Graph: Determines build order
  3. Fetches Sources: Downloads or clones source code
  4. Builds Packages: Compiles in dependency order
  5. Installs: Copies files to installation prefix
  6. Updates Database: Records installed packages

Dependency Resolution

TSI automatically resolves and installs dependencies:

# Installing curl will automatically install:
# - openssl
# - zlib
# - pkg-config (build dependency)
tsi install curl

Package Versions

TSI supports multiple versions of the same package:

# List available versions
tsi info git

# Install specific version
tsi install git@2.45.0
tsi install git@2.44.0

Version Format

Versions can be specified in several ways:

  • Semantic versioning: 1.2.3
  • With prefix: v1.2.3 (automatically handled)
  • Git tags: 2.45.0

Listing Installed Packages

# List all installed packages
tsi list

# List with custom prefix
tsi list --prefix /opt/tsi

Searching Packages

# Search available packages
tsi search <query>

# Search with custom prefix
tsi search <query> --prefix /opt/tsi

Upgrading Packages

# Upgrade all installed packages
tsi upgrade

# Upgrade specific packages
tsi upgrade <package1> <package2>

Package Information

# Show all available versions
tsi info <package-name>

# Show specific version
tsi info <package-name>@<version>

Removing Packages

# Remove a package
tsi uninstall <package-name>

# Remove multiple packages
tsi uninstall <package1> <package2>

# Remove with custom prefix
tsi uninstall <package-name> --prefix /opt/tsi

Note: Removing a package does not remove its dependencies. Dependencies are only removed if no other packages depend on them.

Custom Installation Prefix

You can install packages to a custom location:

# Install to custom prefix
tsi install curl --prefix /opt/tsi

# Environment variables are adjusted automatically

Build Parallelism

TSI builds with one job per CPU by default (make -j<cpus> for autotools, cmake --build --parallel for CMake; Meson is parallel on its own). Set TSI_JOBS to change that:

TSI_JOBS=4 tsi install curl    # cap at four jobs
TSI_JOBS=1 tsi install curl    # serial

Reach for TSI_JOBS=1 when a build fails and you need to read the error: a parallel build interleaves output from every job, and the failing command's message is rarely the last thing printed. It is also worth trying when a package fails only sometimes — a Makefile with missing dependencies can build at -j1 and race at -j8.

Packages using the raw make build system are built serially regardless; hand-written Makefiles too often lack the dependency information -j needs. A package that is known to be safe can request it in make_args.

Download Retries

A failed source download is retried: five attempts in all, 2, 8, 30 and 60 seconds apart, which rides out a flaky network or a DNS outage of a minute or two. A server that refuses outright — 404, 403 and the like — fails at once, since asking again will not change its answer. TSI_FETCH_ATTEMPTS sets the number of attempts:

TSI_FETCH_ATTEMPTS=1 tsi install curl   # fail on the first error
TSI_FETCH_ATTEMPTS=8 tsi install curl   # be more patient

Package Database

TSI maintains a database of installed packages at ~/.tsi/db/. This tracks:

  • Installed packages and versions
  • Installation timestamps
  • Dependencies
  • Build information

Best Practices

  1. Regular Updates: Run tsi update regularly to get new packages
  2. Version Pinning: Use specific versions for production environments
  3. Custom Prefix: Use --prefix for isolated installations
  4. Dependency Management: Let TSI handle dependencies automatically

Troubleshooting

Package Not Found

# Update repository
tsi update

# Verify package exists
tsi info <package-name>

Dependency Conflicts

TSI handles dependencies automatically, but if issues occur:

  1. Check package definitions for correct dependencies
  2. Verify all dependencies are available
  3. Check build order

Build Failures

  • Verify build tools are installed
  • Check package source URLs are valid
  • Review package build configuration