hx init

Initialize hx in an existing project.

Synopsis

hx init [OPTIONS]

Description

The init command initializes hx in an existing Haskell project by creating an hx.toml configuration file. It detects existing Cabal configuration and toolchain settings.

Options

    --force             Overwrite existing hx.toml
    --ghc <VERSION>     Specify GHC version
    --backend <BACKEND> Compiler backend [ghc, bhc]
    --detect            Auto-detect settings from existing configuration
-v, --verbose           Show detailed output

Examples

Basic Initialization

cd existing-project
hx init

With Auto-Detection

# Detect GHC version from cabal.project or stack.yaml
hx init --detect

Force Overwrite

hx init --force

Specify GHC Version

hx init --ghc 9.8.2

Initialize with BHC Backend

hx init --backend bhc

This sets [compiler].backend = "bhc" in the generated hx.toml with sensible defaults for the BHC profile.

What It Does

  1. Detects existing configuration

    • Reads .cabal files for package info
    • Checks cabal.project for GHC settings
    • Checks stack.yaml if present

  2. Creates hx.toml

    • Generates configuration based on detected settings
    • Sets up toolchain pinning

  3. Does NOT modify

    • Existing .cabal files
    • cabal.project
    • stack.yaml
    • Source files

Generated hx.toml

Based on detection:

[project]
name = "detected-name"
version = "detected-version"

[toolchain]
ghc = "9.8.2"    # Detected or specified

[build]
ghc-options = ["-Wall"]

# If cabal.project exists with freeze file
[dependencies]
lock-strategy = "cabal-freeze"

Detection Sources

hx looks for settings in:

SourceDetects
*.cabalPackage name, version
cabal.projectGHC version, packages
cabal.project.freezePinned dependencies
stack.yamlResolver, extra-deps
System PATHActive GHC version

Migrating from Stack

If you have a Stack project:

cd stack-project
hx init --detect

hx will:

  • Read resolver from stack.yaml
  • Map to equivalent GHC version
  • Create hx.toml with settings

You can then use hx alongside or instead of Stack.

Migrating from Cabal

If you have a Cabal-only project:

cd cabal-project
hx init --detect

hx will:

  • Read settings from cabal.project
  • Create hx.toml with configuration
  • Respect existing cabal.project.freeze

After Initialization

After hx init:

# Verify environment
hx doctor

# Build
hx build

# Generate lockfile
hx lock

See Also