Command Line Interface

FastSandPM provides the fspm command-line tool for managing HDL/RTL library dependencies directly from your terminal.

Basic Usage

The simplest way to install dependencies is to run fspm from a directory containing (or with a parent containing) a proj.toml manifest file:

fspm

This will:

Search up the directory tree to find a proj.toml manifest file
Resolve all dependencies specified in the manifest
Install them to the ./lib directory
Create a library.f file listing all dependencies in the correct order

Command Reference

fspm

FastSandPM - Package manager for HDL Design and DV projects

usage: fspm [-h] [-V] [-m PATH] [-o PATH] [-c | --no-clean]
            [--optional GROUPS] [-v] [-q]

-h, --help: show this help message and exit

-V, --version: show program’s version number and exit

-m <path>, --manifest <path>: Path to manifest file or directory containing it (default: search up directory tree for proj.toml)

-o <path>, --output <path>: Output directory for installed libraries (default: ./lib)

-c, --clean: Clean conflicting directories during installation

--no-clean: Don’t clean conflicting directories (default)

--optional <groups>: Comma-separated list of optional dependency groups to install

-v, --verbose: Increase verbosity (can be used multiple times: -v, -vv, -vvv)

-q, --quiet: Suppress all output except errors

For more information, visit https://fastsandpm.readthedocs.io/

Examples

Install from Current Directory

Search for proj.toml in the current directory or any parent directory, then install dependencies to ./lib:

fspm

Specify a Manifest File

Install dependencies from a specific manifest file:

fspm --manifest /path/to/my-project/proj.toml

You can also specify a directory containing a proj.toml:

fspm --manifest /path/to/my-project

Custom Output Directory

Install dependencies to a custom directory:

fspm --output ./vendor
fspm -o /absolute/path/to/libs

Install Optional Dependencies

Install optional dependency groups defined in your manifest:

# Install the 'dev' optional group
fspm --optional dev

# Install multiple optional groups
fspm --optional dev,test,simulation

Clean Installation

By default, fspm will not overwrite directories that have local changes or are in an unexpected state. Use the --clean flag to force replacement:

# Clean conflicting directories during installation
fspm --clean

# Explicitly disable cleaning (default behavior)
fspm --no-clean

Warning

The --clean flag will delete directories with uncommitted changes. Make sure to commit or backup any local modifications before using this flag.

Verbose Output

Increase logging verbosity for debugging:

# Show INFO level messages
fspm -v

# Show DEBUG level messages
fspm -vv

# Maximum verbosity
fspm -vvv

Quiet Mode

Suppress all output except errors:

fspm --quiet

Version Information

Display the installed version:

fspm --version

Exit Codes

The fspm command returns the following exit codes:

Code	Meaning
0	Success - all dependencies installed successfully
1	Error - manifest not found, parse error, or installation failure

Typical Workflow

A typical workflow for using fspm in an HDL/RTL project:

Create a manifest file (proj.toml) in your project root:

[package]
name = "my-rtl-project"
version = "1.0.0"
description = "My RTL design project"

[dependencies]
uvm = { git = "https://github.com/accellera/uvm.git", tag = "1800.2-2020-2.0" }
my-lib = "^1.0.0"

[optional_dependencies.sim]
vip-axi = "2.0.0"

Install dependencies:
```
fspm
```
Include the library in your simulation by referencing lib/library.f:
```
vcs -f lib/library.f -f my_project.f
```
Update dependencies after modifying the manifest:
```
fspm --clean
```