Skip to content

Package Manager

Ferret includes a built-in package manager that handles dependency management, version resolution, and code sharing across projects.

Why a Package Manager?

Section titled “Why a Package Manager?”

The Problem

Section titled “The Problem”

Without a package manager, developers face:

  • Manual dependency tracking - Copy-pasting code between projects
  • Version conflicts - No systematic way to handle incompatible versions
  • No reproducibility - Different team members get different dependency versions
  • Update nightmares - Manually checking and updating each dependency
  • Broken builds - Missing dependencies cause compilation failures

The Solution

Section titled “The Solution”

Ferret’s package manager provides:

  • Automatic resolution - Fetches dependencies and their dependencies recursively
  • Version management - Semantic versioning with flexible constraints
  • Reproducible builds - Lock file ensures everyone gets the same versions
  • Multi-source support - GitHub, GitLab, Bitbucket, and local packages
  • Smart caching - Downloads once, reuses across projects
  • Clean workflows - Simple commands for common tasks

How It Works

Section titled “How It Works”

1. Declare Dependencies

Section titled “1. Declare Dependencies”

Create a fer.ret manifest file:

[package]
name = "myapp"
version = "v1.0.0"
compiler = "<=0.0.3"


[dependencies]
logger = "github.com/user/logger@^v1.0.0"

2. Install Packages

Section titled “2. Install Packages”
Terminal window
ferret get

The package manager:

  • Reads fer.ret
  • Resolves version constraints
  • Downloads packages from Git providers
  • Generates ferret.lock with exact versions
  • Caches packages in .ferret/modules/

3. Use in Code

Section titled “3. Use in Code”
import "github.com/user/logger";


fn main() {
    logger::Info("Hello!");
}

Key Features

Section titled “Key Features”

🚀 Fast & Efficient

Section titled “🚀 Fast & Efficient”
  • Parallel downloads
  • Smart caching
  • Incremental updates

🔒 Reproducible Builds

Section titled “🔒 Reproducible Builds”
  • Lock file tracks exact versions
  • Deterministic resolution
  • Team consistency

🌐 Multi-Provider Support

Section titled “🌐 Multi-Provider Support”
  • GitHub (github.com)
  • GitLab (gitlab.com)
  • Bitbucket (bitbucket.org)
  • Local packages (../path)

📦 Transitive Dependencies

Section titled “📦 Transitive Dependencies”
  • Automatic recursive resolution
  • Conflict detection
  • Orphan cleanup

🎯 Flexible Versioning

Section titled “🎯 Flexible Versioning”
  • Semantic versioning (vX.Y.Z)
  • Constraint operators (^, ~, >=, >, <=, <)
  • Exact pinning
  • Latest tracking

🎨 Developer Experience

Section titled “🎨 Developer Experience”
  • Interactive project initialization
  • Colorful progress indicators
  • Clear error messages
  • Helpful suggestions

Core Concepts

Section titled “Core Concepts”

Manifest File (fer.ret)

Section titled “Manifest File (fer.ret)”

TOML file declaring:

  • Package metadata (name, version, author)
  • Dependencies with version constraints
  • Compiler compatibility
  • Development options

Lock File (ferret.lock)

Section titled “Lock File (ferret.lock)”

JSON file recording:

  • Exact resolved versions
  • Dependency tree
  • Generation timestamp

Always commit to version control.

Package Cache (.ferret/modules/)

Section titled “Package Cache (.ferret/modules/)”

Local directory storing:

  • Downloaded packages
  • Multiple versions
  • Extracted source code

Add to .gitignore.

When to Use

Section titled “When to Use”

✅ Use the package manager when:

  • Importing external packages (non-stdlib)
  • Building multi-file projects
  • Sharing code across projects
  • Working in a team
  • Publishing libraries

❌ Not needed for:

  • Single-file scripts with only stdlib imports
  • Quick prototypes
  • Learning exercises

Getting Started

Section titled “Getting Started”

Ready to use the package manager? Check out: