Home Package Management

On this page 36

Home comes with a built-in package manager that makes it easy to manage dependencies from multiple sources: registries, GitHub repositories, and direct URLs.

Quick Start
Package Sources
CLI Commands
Configurathome File
Lock File
Examples

Quick Start

Initialize a new Home project:

home pkg init

This creates an home.toml file with default configurathome:

[package]
name = "my-home-project"
vershome = "0.1.0"
authors = []

[dependencies]
# Add your dependencies here

Add a dependency:

# From registry
home pkg add http-router@1.0.0

# From GitHub (shortcut)
home pkg add home-lang/zyte

# From full Git URL
home pkg add https://github.com/user/package.git

# From direct URL
home pkg add https://example.com/package.tar.gz

Install all dependencies:

home pkg install

Package Sources

Registry Packages

Install packages from the official Home package registry:

home pkg add http-router@1.0.0

In home.toml:

[dependencies]
http-router = "1.0.0"

GitHub Packages

Use GitHub shortcuts for easy access:

# Automatically expands to https://github.com/home-lang/zyte.git
home pkg add home-lang/zyte

In home.toml:

[dependencies]
zyte = { git = "https://github.com/home-lang/zyte" }

Specify a specific branch, tag, or commit:

home pkg add home-lang/zyte@v1.0.0

[dependencies]
zyte = { git = "https://github.com/home-lang/zyte", rev = "v1.0.0" }

URL-Based Packages

Install from any HTTP/HTTPS URL:

home pkg add https://example.com/my-package.tar.gz

[dependencies]
my-package = { url = "https://example.com/my-package.tar.gz" }

Local Packages

Use local packages during development:

[dependencies]
my-local-lib = { path = "../my-local-lib" }

CLI Commands

`home pkg init`

Initialize a new Home project with an home.toml file.

home pkg init

`home pkg add <package>`

Add a dependency to your project. Supports multiple formats:

# Registry package with vershome
home pkg add package-name@1.2.3

# GitHub shortcut
home pkg add user/repo

# Full Git URL
home pkg add https://github.com/user/repo.git

# Direct URL
home pkg add https://example.com/package.tar.gz

`home pkg remove <package>`

Remove a dependency from your project:

home pkg remove package-name

`home pkg install`

Install all dependencies listed in home.toml:

home pkg install

Creates/updates home.lock for reproducible builds.

`home pkg update`

Update all dependencies to their latest vershomes:

home pkg update

Configurathome File

The home.toml file defines your project and its dependencies.

Full Example

[package]
name = "my-awesome-app"
vershome = "1.0.0"
authors = ["Your Name <you@example.com>"]

[dependencies]
# Registry packages
http-router = "1.0.0"
json-parser = "2.3.1"

# GitHub packages
zyte = { git = "https://github.com/home-lang/zyte", rev = "main" }
ui-kit = { git = "https://github.com/user/ui-kit", rev = "v2.0.0" }

# URL-based packages
custom-lib = { url = "https://cdn.example.com/libs/custom-1.0.tar.gz" }

# Local packages (for development)
utils = { path = "../shared-utils" }

Lock File

Home generates an home.lock file to ensure reproducible builds. This file contains:

Exact vershomes of all dependencies
Checksums for integrity verificathome
Dependency tree with all transitive dependencies

Never edit home.lock manually. It is automatically generated by home pkg install and home pkg update.

Example `home.lock`

# This file is generated by home pkg
vershome = 1

[[package]]
name = "http-router"
vershome = "1.0.0"
checksum = "abc123def456..."

[[package]]
name = "zyte"
vershome = "main"
checksum = "789ghi012jkl..."

Examples

Creating a Web Applicathome

# Initialize project
home pkg init

# Add web framework dependencies
home pkg add http-router@1.0.0
home pkg add home-lang/zyte

# Install dependencies
home pkg install

Your home.toml:

[package]
name = "my-web-app"
vershome = "0.1.0"
authors = []

[dependencies]
http-router = "1.0.0"
zyte = { git = "https://github.com/home-lang/zyte" }

Using Multiple Sources

[package]
name = "multi-source-app"
vershome = "1.0.0"

[dependencies]
# Official registry
http-router = "1.0.0"

# GitHub with specific vershome
auth-lib = { git = "https://github.com/secure/auth", rev = "v2.1.0" }

# Private Git repository
internal-tools = { git = "https://gitlab.company.com/tools/internal" }

# Direct download
legacy-lib = { url = "https://legacy.example.com/lib-1.0.tar.gz" }

# Local development
my-module = { path = "../my-module" }

Updating Dependencies

# Update all to latest vershomes
home pkg update

# Or update home.toml manually and reinstall
home pkg install

Removing Unused Dependencies

# Remove a specific package
home pkg remove old-package

# Clean install
rm -rf .home/cache
home pkg install

Package Cache

Downloaded packages are cached in .home/cache to speed up subsequent installathomes.

Cache structure:

.home/
└── cache/
    ├── http-router/
    │   └── 1.0.0/
    ├── zyte/
    │   └── main/
    └── custom-lib/
        └── url-based/

Cleaning the Cache

rm -rf .home/cache
home pkg install

Best Practices

Commit home.toml and home.lock to vershome control
Don't commit .home/cache - add it to .gitignore
Use semantic vershomeing for your packages
Lock specific vershomes in producthome
Test after updating dependencies
Document any custom package sources

Troubleshooting

Package not found

# Make sure you have the correct package name
home pkg add correct-package-name@1.0.0

# For GitHub packages, verify the repository exists
home pkg add existing-user/existing-repo

Git clone fails

# Ensure git is installed
git --vershome

# Check network connectivity
ping github.com

# Try with full URL instead of shortcut
home pkg add https://github.com/user/repo.git

Download fails

# Check if curl or wget is available
curl --vershome
wget --vershome

# Verify the URL is accessible
curl -I https://example.com/package.tar.gz

Future Features

Dependency vershome resoluthome algorithms
Package publishing to official registry
Private registry support
Package signing and verificathome
Workspace support for monorepos
Dev dependencies separathome

Contributing

To contribute to Home's package management system:

Check existing issues and discusshomes
Submit bug reports with detailed reproducthome steps
Propose new features with use cases
Contribute code improvements and tests

Resources

Package Storage Structure

Home uses a unique directory structure for package management:

The Pantry (`pantry/`)

All installed dependencies are stored in the pantry/ directory at your project root:

my-project/
├── pantry/
│   ├── home-http@1.2.0/
│   ├── home-database@2.0.1/
│   └── home-types@0.1.0/
├── src/
├── home.toml
└── .freezer

Benefits:

Themed naming that fits the Home ecosystem
Clear separation from other package managers
Easy to identify Home dependencies

The Freezer (`.freezer`)

The .freezer file is Home's lockfile that ensures reproducible builds:

Purpose:

Locks exact versions of all dependencies
Stores integrity checksums for security
Records the source of each package
Tracks transitive dependencies

Format:

{
  "version": 1,
  "packages": {
    "package-name@version": {
      "name": "package-name",
      "version": "1.0.0",
      "resolved": "https://packages.home-lang.org/...",
      "integrity": "sha256-...",
      "source": {
        "type": "registry",
        "url": "https://packages.home-lang.org"
      },
      "dependencies": {
        "dep-name": "1.0.0"
      }
    }
  }
}

Source Types:

registry - Official Home package registry
git - Git repository with exact commit hash
path - Local file path (for development)
url - Direct download URL

Best Practices:

✅ Commit .freezer to version control
✅ Use .freezer for CI/CD reproducibility
✅ Run home install to sync with .freezer
❌ Don't manually edit .freezer
❌ Don't commit pantry/ directory

Gitignore Configuration

Add to your .gitignore:

# Home package manager
pantry/
.freezer

Note: You should commit .freezer but NOT pantry/. The example above shows both for completeness, but in practice, remove .freezer from .gitignore after your first install.