Package Management

Raisin includes a powerful package management system that can download, install, and manage pre-compiled C++ packages from GitHub Releases. It provides dependency resolution, version management, and local package indexing.

Overview

The package management system allows you to:

  • Install pre-compiled packages from GitHub Releases

  • Recursively resolve and install package dependencies

  • Specify version constraints (e.g., >=1.2.3, ==2.0.0)

  • List available packages and their versions

  • Validate local package dependencies

Package management integrates with:

  • repositories.yaml - Maps package names to GitHub repository URLs

  • configuration_setting.yaml - Stores GitHub authentication tokens

  • release.yaml - Defines package metadata (version, dependencies)

Install Command

The install command downloads and installs pre-compiled packages and their dependencies.

Command:

python raisin.py install [package_spec ...] [debug|release]

Parameters:

  • package_spec (optional) - One or more package specifications with optional version constraints

  • build_type (optional) - Either debug or release (defaults to release)

Package specification format:

Packages can be specified in several ways:

package_name              # Latest version
package_name==1.2.3       # Exact version
package_name>=1.0.0       # Minimum version
package_name<=2.0.0       # Maximum version
package_name>=1.0,<2.0    # Version range

How it works

The install process follows this workflow:

  1. Package Discovery

    • If no packages are specified, scans src/ for packages with release.yaml files

    • Otherwise, uses the provided package list

  2. Dependency Resolution

    • Recursively reads release.yaml files to discover all dependencies

    • Builds a complete dependency tree

    • Validates version constraints

  3. Installation Priority

    For each package, checks in this order:

    1. Existing pre-compiled package in release/install/<pkg>/<os>/<arch>/<build_type>/

    2. Local source in src/

    3. Download from GitHub Releases if not found locally

  4. Deployment

    • Downloaded packages are extracted to release/install/<pkg>/<os>/<arch>/<build_type>/

    • During setup, packages are deployed to the project-level install/ tree

Installation modes

Mode 1: Install specific packages

Install one or more named packages:

# Install a single package (latest version)
python raisin.py install raisin_core

# Install with version constraint
python raisin.py install raisin_core>=1.2.3

# Install multiple packages
python raisin.py install raisin_core raisin_gui raisin_network

# Install with debug build
python raisin.py install raisin_core debug

Mode 2: Install all local packages

If no packages are specified, automatically installs dependencies for all packages in src/:

# Install all dependencies for local packages
python raisin.py install

# Install debug versions of all dependencies
python raisin.py install debug

This mode is useful when setting up a new development environment.

Version resolution

When multiple version constraints exist for the same package, Raisin uses the most restrictive constraint:

Package A requires: raisin_core>=1.0.0
Package B requires: raisin_core>=1.2.0
Package C requires: raisin_core<2.0.0

Result: raisin_core>=1.2.0,<2.0.0

If constraints are incompatible, installation fails with an error message.

Package structure

Downloaded packages are archived as:

{package_name}-{os}-{arch}-{build_type}-v{version}.zip

For example:

raisin_core-linux-x86_64-release-v1.2.3.zip
raisin_gui-linux-aarch64-debug-v2.0.1.zip

The archive contains the complete install tree structure:

package_name/
├── bin/               # Executables
├── lib/               # Libraries
├── include/           # Headers
├── scripts/           # Helper scripts
├── config/            # Configuration files
├── resource/          # Resources
└── messages/          # Interface definitions

Authentication

Package installation requires GitHub authentication when accessing:

  • Private repositories

  • Release assets from private repos

  • Rate-limited public API endpoints

Configure tokens in configuration_setting.yaml:

gh_tokens:
  your-org: "ghp_xxxxxxxxxxxxxxxxxxxx"
  another-org: "ghp_yyyyyyyyyyyyyyyy"

The system automatically selects the appropriate token based on the repository owner.

Usage examples

Example 1: Fresh workspace setup

# Clone main project
git clone https://github.com/myorg/my-project.git
cd my-project

# Install all dependencies for packages in src/
python raisin.py install

Example 2: Install specific package with dependencies

# Installs raisin_gui and all its dependencies
python raisin.py install raisin_gui

Example 3: Install with version constraints

# Install specific version
python raisin.py install raisin_core==1.5.0

# Install minimum version
python raisin.py install raisin_network>=2.0.0

Example 4: Debug builds

# Install debug version
python raisin.py install raisin_core debug

# Install multiple packages with debug builds
python raisin.py install raisin_core raisin_gui debug

Index Commands

The index commands help you discover available packages and validate dependency graphs.

index local

Command:

python raisin.py index local

Description:

Scans local src/ and release/install/ directories for packages with release.yaml files, validates their dependency graph, and prints a colored status report.

What it does:

  1. Package Discovery

    • Scans src/ for packages with release.yaml

    • Scans release/install/ for downloaded packages

    • Reads version and dependency information from each release.yaml

  2. Dependency Validation

    For each package, checks if all dependencies:

    • Exist (either in src/ or release/install/)

    • Meet version requirements

    • Are properly configured

  3. Status Report

    Displays a color-coded table with:

    • Package name

    • Version

    • Origin (src/ or release/install/)

    • Dependency status

Output format:

📦 Scanning local packages...

Package Name          Version    Origin    Dependencies
─────────────────────────────────────────────────────────
raisin_core           1.2.3      src       ✅ All satisfied
raisin_network        2.0.1      src       ✅ All satisfied
raisin_gui            1.5.0      release   ⚠️  raisin_core>=1.3.0 not satisfied
raisin_plugin         0.9.0      src       ❌ raisin_engine not found

Status indicators:

  • ✅ Green - All dependencies satisfied

  • ⚠️ Yellow - Dependencies found but version constraints not satisfied

  • ❌ Red - Dependencies not found

Use cases:

  • Verify your local environment before building

  • Check which packages need to be installed

  • Diagnose dependency issues

  • Review package versions in your workspace

index release

Command:

python raisin.py index release [<package_name>]

Description:

Lists available packages and versions from GitHub Releases.

Mode 1: List all packages

Without a package name, lists all available packages:

python raisin.py index release

Output:

🔍 Finding all available packages and their latest versions...
ℹ️  Checking for assets compatible with: linux-ubuntu-x86_64

Package Name          Latest Version    Type
───────────────────────────────────────────────────────
raisin_core           1.2.3             release
raisin_network        2.1.0-beta        prerelease
raisin_gui            1.5.2             release
raisin_plugin         1.0.0             release
raisin_vision         0.8.0-alpha       prerelease

Mode 2: List package versions

With a package name, lists all available versions:

python raisin.py index release raisin_core

Output:

🔍 Finding available versions with assets for 'raisin_core'...
ℹ️  Checking for assets compatible with: linux-ubuntu-x86_64

Available versions for 'raisin_core':
────────────────────────────────────────
1.2.3     (release)    ✅ Has compatible asset
1.2.2     (release)    ✅ Has compatible asset
1.2.1     (release)    ✅ Has compatible asset
1.2.0     (release)    ✅ Has compatible asset
1.1.5     (release)    ❌ No compatible asset
1.0.0     (release)    ✅ Has compatible asset

Asset compatibility:

The command only shows versions that have a compatible release asset for your system. Assets are matched by:

  • Operating system (e.g., linux, windows, macos)

  • OS version (e.g., ubuntu, debian)

  • Architecture (e.g., x86_64, aarch64)

  • Build type (e.g., release, debug)

Version types:

  • release - Stable release version

  • prerelease - Beta, alpha, or RC versions

Configuration requirements:

Both index release commands require:

  1. repositories.yaml - Package to repository URL mappings:

    raisin_core:
  url: [email protected]:myorg/raisin_core.git
raisin_gui:
  url: [email protected]:myorg/raisin_gui.git

  2. configuration_setting.yaml - GitHub authentication:

    gh_tokens:
  myorg: "ghp_xxxxxxxxxxxxxxxxxxxx"

Use cases:

  • Discover available packages before installation

  • Check which versions are available for your platform

  • Verify that a package has been released

  • Plan version upgrades

Dependency Management

Understanding dependencies

Raisin uses release.yaml files to define package metadata:

# release.yaml
version: 1.2.3
dependencies:
  - raisin_core>=1.0.0
  - raisin_network>=2.0.0,<3.0.0
  - raisin_gui==1.5.0

Dependency format:

Dependencies follow Python’s version specifier format:

package_name              # Any version
package_name==1.2.3       # Exact version (pinned)
package_name>=1.0.0       # Minimum version
package_name<=2.0.0       # Maximum version
package_name>=1.0,<2.0    # Version range
package_name!=1.5.0       # Exclude specific version

Semantic versioning:

Raisin follows semantic versioning (major.minor.patch):

  • Major - Breaking changes

  • Minor - New features (backward compatible)

  • Patch - Bug fixes (backward compatible)

Best practices:

  • Use >= for minimum compatible version

  • Use < to exclude incompatible major versions

  • Example: raisin_core>=1.2.0,<2.0.0 (compatible with 1.x series)

Dependency resolution algorithm

  1. Breadth-first traversal - Explores all dependencies level by level

  2. Constraint collection - Gathers all version constraints for each package

  3. Constraint merging - Combines constraints using set intersection

  4. Version selection - Chooses the newest version satisfying all constraints

  5. Conflict detection - Fails if constraints are mutually exclusive

Example resolution:

Project depends on:
  - package_a>=1.0
  - package_b>=2.0

package_a depends on:
  - package_c>=1.5,<2.0

package_b depends on:
  - package_c>=1.8

Resolution:
  - package_a: install latest >=1.0
  - package_b: install latest >=2.0
  - package_c: install latest >=1.8,<2.0

Handling missing dependencies

If a dependency is not found:

  1. Check local source - Look in src/

  2. Check installed packages - Look in release/install/

  3. Attempt download - Query GitHub Releases

  4. Fail with error - If none of the above succeed

Error messages indicate:

  • Which package is missing

  • Which package requires it

  • Suggested actions

Circular dependencies

Raisin detects circular dependencies during resolution:

❌ Error: Circular dependency detected!
   package_a -> package_b -> package_c -> package_a

Solution: Refactor packages to break the cycle.

User Types

Raisin supports two user types configured in configuration_setting.yaml:

user_type: devel  # or 'user'

User type: ‘user’

  • Typical end-user or consumer

  • Installs pre-compiled packages

  • Does not build from source (usually)

  • Limited access to development features

User type: ‘devel’

  • Developer or maintainer

  • Can build from source

  • Can create releases

  • Full access to all features

The user type affects:

  • Available commands

  • Installation behavior

  • Build permissions

Advanced Topics

Package caching

Downloaded packages are cached in release/install/:

release/install/
└── raisin_core/
    └── linux/
        └── x86_64/
            ├── release/
            │   ├── bin/
            │   ├── lib/
            │   └── ...
            └── debug/
                ├── bin/
                ├── lib/
                └── ...

Once downloaded, packages are reused for subsequent builds.

Clearing cache:

# Remove all downloaded packages
rm -rf release/install/

# Remove specific package
rm -rf release/install/raisin_core/

Mixed source and binary

You can mix source packages (in src/) with pre-compiled packages (in release/install/):

  • Source packages take priority during setup

  • Pre-compiled packages are used if source is not available

  • This allows partial source builds while using binaries for dependencies

Example workflow:

# Install all dependencies as binaries
python raisin.py install

# Clone source for packages you want to modify
cd src/
git clone https://github.com/myorg/raisin_gui.git

# Build: raisin_gui from source, others use binaries
python raisin.py build release install

Offline mode

If you have all required packages in release/install/:

  1. No network connection needed

  2. install command uses cached packages

  3. setup deploys cached packages

To prepare for offline use:

# While online: download all dependencies
python raisin.py install

# Now you can work offline
python raisin.py setup
python raisin.py build release

Troubleshooting

Problem: “Package not found”

Solutions:

  • Check package name spelling

  • Verify package exists in repositories.yaml

  • Run python raisin.py index release to see available packages

  • Check GitHub repository has releases

Problem: “No compatible asset found”

Solutions:

  • Package may not be released for your OS/architecture

  • Check available versions: python raisin.py index release <package>

  • Build from source instead of using pre-compiled package

  • Contact package maintainer to request your platform

Problem: “Version constraint conflict”

Solutions:

  • Review dependency versions in release.yaml files

  • Update package versions to compatible ranges

  • Use python raisin.py index local to diagnose conflicts

Problem: “Authentication failed”

Solutions:

  • Verify GitHub token in configuration_setting.yaml

  • Check token has required scopes (repo, read:org)

  • Ensure token is not expired

  • Verify token matches repository owner

Problem: “Download failed”

Solutions:

  • Check network connection

  • Verify GitHub is accessible

  • Check disk space

  • Try again (temporary network issues)

Problem: “Extraction failed”

Solutions:

  • Check disk space

  • Verify write permissions in release/install/

  • Check zip file integrity

  • Re-download the package

Best Practices

  1. Pin critical dependencies: Use exact versions (==) for critical dependencies to ensure reproducibility

  2. Use version ranges: Use ranges (>=,<) for flexible compatibility

  3. Cache packages: Keep release/install/ to avoid repeated downloads

  4. Validate before building: Run python raisin.py index local before building

  5. Regular updates: Periodically check for updates with python raisin.py index release

  6. Document dependencies: Keep release.yaml up-to-date in all packages

  7. Test version constraints: Ensure your version constraints are not too restrictive

  8. Security: Keep authentication tokens secure, use read-only tokens when possible