OpenSPM
OpenSPM
Documentation

OpenSPM - Open Source Package Manager

OpenSPM is a lightweight, cross-platform package manager designed for easy distribution and installation of binary and source packages. It provides a simple YAML-based repository format and supports dependency management, platform-specific packages, and tag-based compatibility.

Features Installation Usage Creating a Repo Configuration Development Platform Support Troubleshooting

Features

Installation

Prerequisites

OpenSPM requires the following dependencies:

Ubuntu/Debian

sudo apt-get install cmake g++ libarchive-dev libzstd-dev pkg-config

Fedora/RHEL

sudo dnf install cmake gcc-c++ libarchive-devel libzstd-devel pkgconfig

macOS (Homebrew)

brew install cmake libarchive zstd pkg-config

Usage

Initial Configuration

Before using OpenSPM, run the configuration wizard (requires administrator/root privileges):

sudo openspm configure

This will guide you through setting up data and target directories and color output preferences.

Managing Repositories

Adding a Repository

sudo openspm add-repo https://example.com/repository

Short form: sudo openspm ar https://example.com/repository

Creating Your Own Repository

A repository consists of two main YAML files hosted on a web server:

  1. repository.yaml - Repository metadata
  2. pkg-list.yaml - Package index

Configuration

OpenSPM stores its configuration in /etc/openspm/config.yaml and uses an archive-based data store in <dataDir>/data.bin.

Development

Project structure, build steps, and tests are included in the repository. Use CMake to build and run tests with ctest.

Platform Support

Supported platforms: Linux, macOS, Windows. See platform-specific notes in the full docs.

Troubleshooting

Permission Denied

OpenSPM requires administrator/root privileges for most operations. Prefix commands with sudo where necessary.

OpenSPM - Open Source Package Manager

OpenSPM is a lightweight, cross-platform package manager designed for easy distribution and installation of binary and source packages. It provides a simple YAML-based repository format and supports dependency management, platform-specific packages, and tag-based compatibility.

Features

Installation

Prerequisites

OpenSPM requires the following dependencies:

On Ubuntu/Debian:

sudo apt-get install cmake g++ libarchive-dev libzstd-dev pkg-config

On Fedora/RHEL:

sudo dnf install cmake gcc-c++ libarchive-devel libzstd-devel pkgconfig

On macOS (using Homebrew):

brew install cmake libarchive zstd pkg-config

On Windows (using vcpkg):

# Install vcpkg if not already installed
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

# Install dependencies
.\vcpkg install libarchive:x64-windows zstd:x64-windows

Building from Source

Linux and macOS

  1. Clone the repository:

    git clone https://github.com/ghillie575/Openspm.git
cd Openspm

  2. Create a build directory and compile:

    mkdir build
cd build
cmake ..
make

  3. Install (requires administrator/root privileges):

    sudo make install

Alternatively, you can run the binary directly from the build directory:

./openspm --version

Windows

  1. Clone the repository:

    git clone https://github.com/ghillie575/Openspm.git
cd Openspm

  2. Install dependencies with vcpkg (if not already done):

    vcpkg install libarchive:x64-windows zstd:x64-windows

  3. Create a build directory and compile:

    mkdir build
cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE="[path-to-vcpkg]/scripts/buildsystems/vcpkg.cmake"
cmake --build . --config Release

  4. Run the binary (requires administrator privileges):

    .\Release\openspm.exe --version

Usage

Initial Configuration

Before using OpenSPM, run the configuration wizard (requires administrator/root privileges):

sudo openspm configure

This will guide you through setting up:

Managing Repositories

Adding a Repository

Add a package repository by providing its URL:

sudo openspm add-repo https://example.com/repository

Short form:

sudo openspm ar https://example.com/repository

Example with the official testing repository:

sudo openspm add-repo https://testing.openspm.org

Listing Repositories

View all configured repositories:

sudo openspm list-repos

Short form:

sudo openspm lr

Removing a Repository

Remove a repository:

sudo openspm rm-repo https://example.com/repository

Short form:

sudo openspm rr https://example.com/repository

Updating Repository Metadata

Sync metadata from all configured repositories:

sudo openspm update-repos

Short form:

sudo openspm ur

Managing Packages

Listing Available Packages

List all packages compatible with your system:

sudo openspm list-packages

Short form:

sudo openspm lp

Updating Package Index

Update the package index from all repositories:

sudo openspm update

Short form:

sudo openspm up

Command-Line Options

Global Flags

Example:

sudo openspm --debug --data-dir /tmp/openspm list-packages

Getting Help

Display help information:

openspm help

Or:

openspm --help

Creating Your Own Repository

Repository Structure

A repository consists of two main YAML files hosted on a web server:

  1. repository.yaml - Repository metadata
  2. pkg-list.yaml - Package index

Step 1: Create repository.yaml

Create a file named repository.yaml with your repository information:

name: My Package Repository
description: A collection of useful packages
mantainer: your-name

Note: Despite the typo in the field name, use mantainer (not "maintainer") for compatibility.

Step 2: Create pkg-list.yaml

Create a file named pkg-list.yaml listing your packages:

# Optional: Depend on other repositories
# Point directley to pkg list yaml file
depend:
  - https://another-repo.example.com/repository/pkg-list.yaml

# Package list
packages:
  - name: "my-package"
    version: "1.0.0"
    description: "Description of my package"
    maintainer: "your-name"
    dependencies: []
    tags: "bin;linux-x86_64"
    url: "https://your-server.com/packages/my-package-1.0.tar.gz"

  - name: "another-package"
    version: "2.1.0"
    description: "Another useful package"
    maintainer: "your-name"
    dependencies:
      - "my-package"
    tags: "bin;linux-x86_64;gcc"
    url: "https://your-server.com/packages/another-package-2.1.tar.gz"

Step 3: Understanding Tags

Tags determine package compatibility with different systems. Common tags include:

A package is compatible only if the target system supports all of the package's tags.

Examples:

Step 4: Package Format

Packages should be distributed as .tar.gz archives. The archive structure is flexible, but typically includes:

package.tar.gz
├── install.sh
├── pkg.yaml
└── TARGET
    ├── etc
    │   └── test.conf
    └── usr
        └── bin
            └── hello

All files that does not require setup and can be directly copied are placed in TARGET/subdir/file. TARGET folder represents target instalation directory. install.sh is executed after copying files from TARGET folder. The folowing enviroment vairables are provided: $PKG_NAME $PKG_VERSION $PKG_MAINTAINER $PKG_DESCRIPTION $PKG_TAGS $PKG_INSTALL_DIR $PKG_SOURCE_DIR

Step 5: Host Your Repository

Upload both YAML files to a web server at the same directory level:

https://your-server.com/repository/
├── repository.yaml
└── pkg-list.yaml

Your repository URL is: https://your-server.com/repository

Step 6: Test Your Repository

Add your repository to OpenSPM:

sudo openspm add-repo https://your-server.com/repository
sudo openspm update
sudo openspm list-packages

Example Repository

See the examples/ directory for a complete example:

Configuration

Configuration File

OpenSPM stores its configuration in /etc/openspm/config.yaml:

dataDir: /etc/openspm/
targetDir: /usr/local/
colorOutput: true
platform: linux-x86_64
supported_tags: bin;linux-x86_64;gcc;gcc-11;non-bin;
supported: true
unsupported_msg: ""

Data Storage

OpenSPM uses an archive file for storing metadata:

Log Files

Logs are written to /var/log/openspm/openspm.log by default. Change this with the --logfile flag.

Development

Project Structure

Openspm/
├── include/          # Header files
│   ├── archive.hpp
│   ├── config.hpp
│   ├── logger.hpp
│   ├── openspm_cli.hpp
│   ├── package_manager.hpp
│   ├── repository_manager.hpp
│   └── utils.hpp
├── src/              # Implementation files
│   ├── archive.cpp
│   ├── config.cpp
│   ├── logger.cpp
│   ├── openspm_cli.cpp
│   ├── package_manager.cpp
│   ├── repository_manager.cpp
│   └── utils.cpp
├── main.cpp          # Entry point
├── tests/            # Test files
├── examples/         # Example repository and packages
├── Doxyfile          # Doxygen configuration
├── USAGE.md          # Detailed command-line usage guide
└── CMakeLists.txt    # Build configuration

Building for Development

For development builds with debug symbols:

mkdir build-debug
cd build-debug
cmake -DCMAKE_BUILD_TYPE=Debug ..
make

Generating Documentation

OpenSPM uses Doxygen for API documentation. Documentation is automatically generated during Release builds.

Prerequisites

Install Doxygen and Graphviz:

Ubuntu/Debian:

sudo apt-get install doxygen graphviz

Fedora/RHEL:

sudo dnf install doxygen graphviz

macOS:

brew install doxygen graphviz

Generate Documentation Manually

# From the project root
doxygen Doxyfile

This generates HTML documentation in the docs/html/ directory. Open docs/html/index.html in a web browser to view it.

Automatic Documentation Generation

Documentation is automatically generated:

Running Tests

cd build
ctest

Or run tests with verbose output:

ctest --verbose

Code Overview

For detailed API documentation, see the generated Doxygen documentation.

For detailed command-line usage, see USAGE.md.

Platform Support

Linux

Fully supported. Requires root privileges for system-wide installation.

macOS

Fully supported. Requires administrator privileges.

Windows

Fully supported. Requires administrator privileges.

Note: On Windows, package installation scripts can be either:

Troubleshooting

Permission Denied

OpenSPM requires administrator/root privileges for most operations:

# Linux/macOS
sudo openspm <command>

# Windows (run Command Prompt as Administrator)
openspm <command>

No Repositories Found

If you see "No repositories found", you need to add at least one repository:

sudo openspm add-repo https://example.com/repository

Color Output Issues

If colors don't display correctly in your terminal, disable them:

openspm --no-color <command>

Or configure during setup:

sudo openspm configure

Debug Information

Enable debug logging to troubleshoot issues:

sudo openspm --debug <command>

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues on GitHub.

License

This project is open source. See the repository for license details.

Author

Created by ghillie575

Version

Current version: 0.1.0

For the latest version information, run:

openspm --version