hx lock

Generate or update the lockfile.

Synopsis

hx lock [OPTIONS]

Description

The lock command generates hx.lock, a lockfile that pins all direct and transitive dependencies to exact versions. This ensures reproducible builds across machines and over time.

Options

    --force             Regenerate from scratch
    --update            Update all dependencies
    --check             Verify lockfile is up-to-date
    --frozen            Fail if lockfile would change
-v, --verbose           Show detailed output

Examples

Generate Lockfile

hx lock

Update All Dependencies

hx lock --update

Verify Lockfile

# Check if lockfile matches configuration
hx lock --check

Frozen Mode (CI)

# Fail if lockfile would change
hx lock --frozen

Force Regeneration

hx lock --force

The Lockfile

hx.lock contains:

Exact versions of all dependencies
Checksums for verification
Dependency graph
Toolchain requirements

Example hx.lock

# Auto-generated by hx. Do not edit manually.
version = 1
generated = 2024-01-15T10:30:00Z

[toolchain]
ghc = "9.8.2"

[[package]]
name = "aeson"
version = "2.1.2.1"
sha256 = "abc123..."
dependencies = ["base", "text", "containers", "vector"]

[[package]]
name = "text"
version = "2.0.2"
sha256 = "def456..."
dependencies = ["base", "bytestring"]

# ... more packages

When to Lock

Generate or update the lockfile when:

Creating a new project
Adding/removing dependencies
Updating dependencies
Before committing to version control
Before deploying

Version Control

Always commit hx.lock to version control:

git add hx.lock
git commit -m "Update dependencies"

This ensures:

Same versions on all machines
Reproducible CI builds
Rollback capability

CI Integration

In CI, verify the lockfile is up-to-date:

- name: Check lockfile
  run: hx lock --frozen

This fails if someone modified dependencies without updating the lockfile.

Lockfile vs Cabal Freeze

hx uses its own lockfile format, but can interoperate with Cabal:

Feature	hx.lock	cabal.project.freeze
Format	TOML	Cabal
Includes checksums	Yes	No
Toolchain pinning	Yes	No
Machine readable	Yes	Less so

Syncing Dependencies

After modifying hx.lock, sync to install pinned versions:

hx sync

Troubleshooting

Lockfile Out of Date

error: hx.lock is out of sync with hx.toml
  Toolchain version changed: ghc 9.6.4 -> 9.8.2

fix: Run `hx lock` to update the lockfile

Solver Conflicts

# See detailed solver output
hx lock --verbose

# Try updating specific packages
hx update conflicting-package
hx lock