Feature/cli

CHANGELOG.md

@@ -12,3 +12,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial creation of API
 - Initial spec for manifest defintion
+- Initial creation of CLI tool

README.md

@@ -24,27 +24,68 @@ Quick Start
 
 Installation:
 
-.. code-block:: bash
+```bash
+# For UV Based projects
+uv add fastsandpm
 
-   # For UV Based projects
-   uv add fastsandpm
+# For pip-based projects
+pip install fastsandpm
+```
 
-   # For pip-based projects
-   pip install fastsandpm
+### Command Line Usage
 
-Basic Usage:
+The simplest way to use FastSandPM is via the `fspm` command:
 
-    >>> import pathlib
-    >>> import fastsandpm
-    >>> manifest = fastsandpm.get_manifest("./my-project")
-    >>> print(manifest.package.name)
-    'my-package'
-    >>> resolved = fastsandpm.dependencies.resolve(manifest)
-    >>> print(type(resolved))
-    <class 'dict'>
-    >>> build_library(resolved, pathlib.Path("my-library"))
+```bash
+# Install dependencies from proj.toml in current or parent directory
+fspm
+
+# Install from a specific manifest file
+fspm --manifest /path/to/proj.toml
+
+# Install to a custom output directory
+fspm --output ./vendor
+
+# Install with optional dependency groups
+fspm --optional dev,test
+
+# Clean conflicting directories during installation
+fspm --clean
+```
+
+#### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `-m, --manifest PATH` | Path to manifest file or directory (default: search up tree for `proj.toml`) |
+| `-o, --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 |
+| `-v, --verbose` | Increase verbosity (can stack: `-v`, `-vv`, `-vvv`) |
+| `-q, --quiet` | Suppress all output except errors |
+| `-V, --version` | Show version and exit |
+
+### Python API Usage
+
+```python
+import pathlib
+import fastsandpm
+
+# Load a manifest
+manifest = fastsandpm.get_manifest("./my-project")
+print(manifest.package.name)
+# 'my-package'
+
+# Resolve dependencies
+resolved = fastsandpm.dependencies.resolve(manifest)
+
+# Build the library
+fastsandpm.build_library(resolved, pathlib.Path("my-library"))
+```
 
 This will bring in the library dependencies for a project into the specified directory.
-Additionally, a 'dependencies.f' file will be created which will point to the dependencies file list in the required order.
+Additionally, a `library.f` file will be created which will point to the dependencies
+file list in the required order.
 
 For more examples, see [the docs](https://fastsandpm.readthedocs.io/en/latest/usage_guide/index.html) for details.

docs/source/index.rst

@@ -31,7 +31,24 @@ Installation:
    # For pip-based projects
    pip install fastsandpm
 
-Basic Usage:
+Command Line Usage:
+
+The simplest way to use FastSandPM is via the ``fspm`` command:
+
+.. code-block:: bash
+
+   # Install dependencies from proj.toml in current or parent directory
+   fspm
+
+   # Install to a custom directory
+   fspm --output ./vendor
+
+   # Install with optional dependency groups
+   fspm --optional dev,test
+
+See :doc:`usage_guide/cli` for the complete CLI reference.
+
+Python API Usage:
 
     >>> import pathlib
     >>> import fastsandpm
@@ -41,10 +58,11 @@ Basic Usage:
     >>> resolved = fastsandpm.dependencies.resolve(manifest)
     >>> print(type(resolved))
     <class 'dict'>
-    >>> build_library(resolved, pathlib.Path("my-library"))
+    >>> fastsandpm.build_library(resolved, pathlib.Path("my-library"))
 
 This will bring in the library dependencies for a project into the specified directory.
-Additionally, a 'dependencies.f' file will be created which will point to the dependencies file list in the required order.
+Additionally, a ``library.f`` file will be created which will point to the dependencies
+file list in the required order.
 
 For more examples, see the :doc:`usage_guide/index`.
 

docs/source/usage_guide/cli.rst

@@ -0,0 +1,193 @@
+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:
+
+.. prompt:: bash
+
+   fspm
+
+This will:
+
+1. Search up the directory tree to find a ``proj.toml`` manifest file
+2. Resolve all dependencies specified in the manifest
+3. Install them to the ``./lib`` directory
+4. Create a ``library.f`` file listing all dependencies in the correct order
+
+Command Reference
+-----------------
+
+.. autoprogram:: fastsandpm.cli:create_parser()
+   :prog: fspm
+
+Examples
+--------
+
+Install from Current Directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Search for ``proj.toml`` in the current directory or any parent directory,
+then install dependencies to ``./lib``:
+
+.. prompt:: bash
+
+   fspm
+
+Specify a Manifest File
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Install dependencies from a specific manifest file:
+
+.. prompt:: bash
+
+   fspm --manifest /path/to/my-project/proj.toml
+
+You can also specify a directory containing a ``proj.toml``:
+
+.. prompt:: bash
+
+   fspm --manifest /path/to/my-project
+
+Custom Output Directory
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Install dependencies to a custom directory:
+
+.. prompt:: bash
+
+   fspm --output ./vendor
+   fspm -o /absolute/path/to/libs
+
+Install Optional Dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Install optional dependency groups defined in your manifest:
+
+.. prompt:: bash
+
+   # 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:
+
+.. prompt:: bash
+
+   # 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:
+
+.. prompt:: bash
+
+   # Show INFO level messages
+   fspm -v
+
+   # Show DEBUG level messages
+   fspm -vv
+
+   # Maximum verbosity
+   fspm -vvv
+
+Quiet Mode
+~~~~~~~~~~
+
+Suppress all output except errors:
+
+.. prompt:: bash
+
+   fspm --quiet
+
+Version Information
+~~~~~~~~~~~~~~~~~~~
+
+Display the installed version:
+
+.. prompt:: bash
+
+   fspm --version
+
+Exit Codes
+----------
+
+The ``fspm`` command returns the following exit codes:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 90
+
+   * - 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:
+
+1. **Create a manifest file** (``proj.toml``) in your project root:
+
+   .. code-block:: toml
+
+      [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"
+
+2. **Install dependencies**:
+
+   .. prompt:: bash
+
+      fspm
+
+3. **Include the library** in your simulation by referencing ``lib/library.f``:
+
+   .. code-block:: bash
+
+      vcs -f lib/library.f -f my_project.f
+
+4. **Update dependencies** after modifying the manifest:
+
+   .. prompt:: bash
+
+      fspm --clean
+
+See Also
+--------
+
+- :doc:`index` - General usage guide
+- :doc:`../manifest_reference/index` - Manifest file format reference

docs/source/usage_guide/index.rst

@@ -20,9 +20,45 @@ Or with pip:
    pip install fastsandpm
 
 
-Basic Usage
------------
+Command Line Interface
+----------------------
 
-.. NOTE::
+FastSandPM provides the ``fspm`` command for quick dependency management:
 
-   TODO: Work in progress
+.. code-block:: bash
+
+   # Install dependencies from proj.toml
+   fspm
+
+   # Install to a custom directory
+   fspm --output ./vendor
+
+   # Install with optional dependencies
+   fspm --optional dev,test
+
+See :doc:`cli` for the complete CLI reference.
+
+Python API
+----------
+
+For programmatic usage, fastsandpm provides a Python API:
+
+.. code-block:: python
+
+   import pathlib
+   import fastsandpm
+
+   # Load a manifest
+   manifest = fastsandpm.get_manifest("./my-project")
+
+   # Resolve dependencies
+   resolved = fastsandpm.dependencies.resolve(manifest)
+
+   # Build the library
+   fastsandpm.build_library(resolved, pathlib.Path("lib"))
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   cli

pyproject.toml

@@ -75,6 +75,9 @@ typing=[
     "types-pyyaml>=6.0.12.20250516",
 ]
 
+[project.scripts]
+fspm = "fastsandpm.cli:main"
+
 [project.urls]
 Homepage = "https://github.com/RISC-Lib/fastsandpm"
 Documentation = "https://fastsandpm.readthedocs.io/en/latest/index.html"