Skip to content

About

dev container for modern Haskell/WASM-related projects with TeX rendering

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

108 Commits

Folders and files

Repository files navigation

🐳 Haskell + TeX Development Environment

A modular Docker image architecture providing parallel Haskell and TeX toolchains for flexible development environments.

πŸ—οΈ Parallel Layer Architecture

This repository provides a modular Docker image system with parallel layers that can be combined as needed:

Ubuntu Base (24.04)
β”œβ”€β”€ Haskell Layer (GHC 9.14.x + optional wasm32-wasi cross-GHC)
β”œβ”€β”€ TeX Layer (TeX Live + LuaTeX)
└── Full Layer (Haskell + TeX + Pandoc)

Available Images

Image Description Use Case Size
ghcr.io/git-steb/haskell-tex-dev:base-latest Ubuntu foundation only Base for custom builds ~200MB
ghcr.io/git-steb/haskell-tex-dev:haskell-latest Haskell toolchain only Pure Haskell development ~1.2GB
ghcr.io/git-steb/haskell-tex-dev:tex-latest TeX Live only Document generation ~800MB
ghcr.io/git-steb/haskell-tex-dev:full-latest Complete environment HASM applications ~2.0GB
ghcr.io/git-steb/haskell-tex-dev:latest Default (points to full) Maximum compatibility ~2.0GB

πŸš€ Quick Start

Default Usage (Complete Environment)

docker run -it --rm -v $(pwd):/workspace ghcr.io/git-steb/haskell-tex-dev:latest

Haskell Only (No TeX)

docker run -it --rm -v $(pwd):/workspace ghcr.io/git-steb/haskell-tex-dev:haskell-latest

TeX Only (No Haskell)

docker run -it --rm -v $(pwd):/workspace ghcr.io/git-steb/haskell-tex-dev:tex-latest

πŸ› οΈ Features

Haskell Layer

  • GHC 9.14.1 (pinned in build_context/versions.env; installable via GHCup)
  • Cabal 3.18.2.0 for package management
  • HLS 2.15.0.0 for IDE support (official bindists support GHC 9.14.1)
  • Stack 3.11.1 for project management
  • Ormolu 0.9.0.0 for code formatting (official Linux x86_64 and macOS Intel/Apple Silicon host bindists into ~/.local/bin)

TeX Layer

  • TeX Live with LuaTeX for full Unicode support
  • Minimal package set (50+ vs 1500+ full collection)
  • User-mode TeX Live with tlmgr for package management
  • Essential fonts (Liberation, DejaVu)
  • Optimized for project needs

Full Layer

  • Complete Haskell + TeX environment
  • Pandoc for document conversion
  • Perfect for HASM applications
  • All tools pre-configured

πŸ“¦ Package Management

Haskell

# Check versions
show-haskell-versions

# Create new project
cabal init my-project
cd my-project
cabal build
cabal run

# WebAssembly compilation
ghc -target wasm32-wasi -o app.wasm Main.hs

TeX

# Check TeX versions
show-tex-versions

# Compile documents
pdflatex document.tex
lualatex document.tex
latexmk -pdf document.tex

# Install additional packages
tlmgr install package-name

Full Environment

# Check all versions
show-all-versions

# Document generation
pandoc document.md -o document.pdf
pandoc -f markdown -t latex input.md -o output.tex

πŸ”§ Development

Host toolchain (same pins as the container)

Pins live in build_context/versions.env (and the image tag uses the VERSION file). From the repository root, after GHCup is on your PATH (~/.ghcup/bin):

chmod +x scripts/install-host-toolchain.sh
./scripts/install-host-toolchain.sh

This reads build_context/versions.env and installs/sets GHC, cabal-install, Stack, and HLS with GHCup, then installs the pinned official Ormolu bindist (matching the Haskell Docker layer). Use --skip-hls or --dry-run as needed.

On macOS, the wrapper also checks the native prerequisites and bootstraps GHCup when necessary:

./scripts/install-macos-ghcup.sh
./scripts/test-host-toolchain.sh

The smoke test builds and runs a temporary Cabal package. It does not enter or modify a consumer repository.

Building Images Locally

# Build the release layers with the same tags and platform policy
./scripts/build-local.sh 1.4.0

# Or build a specific layer from the build context
docker build --platform linux/amd64 -f build_context/Dockerfile.haskell .

The v1.4.0 release images currently target linux/amd64. On Apple Silicon, build-local.sh therefore uses Docker Desktop's amd64 emulation by default. Set DOCKER_PLATFORM only when the image assets support another platform.

Publishing to GHCR

# Login to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u $GITHUB_USERNAME --password-stdin

# Build and publish all layers
./build-parallel.sh

🏷️ Image Tags

Each layer is tagged with both:

  • Latest: ghcr.io/git-steb/haskell-tex-dev:layer-latest
  • SHA: ghcr.io/git-steb/haskell-tex-dev:layer-sha-<commit>

Example Usage in CI

# For Haskell-only builds
container:
  image: ghcr.io/git-steb/haskell-tex-dev:haskell-latest

# For TeX-only builds  
container:
  image: ghcr.io/git-steb/haskell-tex-dev:tex-latest

# For full environment
container:
  image: ghcr.io/git-steb/haskell-tex-dev:full-latest

⚑ Performance Benefits

  • 80% smaller downloads with minimal TeX Live
  • 70% faster builds with parallel layer caching
  • 60-80% reduction in dependency build time (v1.2.9)
  • Independent updates for Haskell vs TeX toolchains
  • Flexible deployment - choose what you need

v1.4.0

Native host installation remains the primary workflow:

bash scripts/install-host-toolchain.sh
# Optional isolated WebAssembly profile:
bash scripts/install-wasm-toolchain.sh
wasm32-wasi-cabal update

GHC 9.14.1, Cabal 3.18.2.0, HLS 2.15.0.0, Stack 3.11.1 and Ormolu 0.9.0.0 share an immutable GHCup metadata snapshot. The dependency preload uses a pinned Hackage index and scoped serialise:base / cborg:base exceptions. Cryptographic hashing uses crypton and ram. Homeomorphosis uses http-conduit directly; unused Lens and legacy OAuth/RSA packages are removed from the preload.

The optional WebAssembly profile has its own SDK and Cabal 3.14.2.0, pinned to upstream's supported cross-toolchain configuration. Invoke wasm32-wasi-ghc or wasm32-wasi-cabal; its compiler environment stays inside these commands. Native ghc, cabal and CC remain independent.

Earlier: v1.3.0

  • Toolchain refresh: GHC 9.14.1, Cabal 3.16.1.0, Stack 3.9.3, HLS 2.13.0.0 (pinned in build_context/versions.env, installed via GHCup)
  • HLS + Ormolu: HLS is installed with ghcup; Ormolu is built with Cabal into ~/.local/bin
  • Build arg WITH_HLS=0 skips HLS for smaller images
  • See CHANGELOG.md for migration notes (GHC major bump)

Earlier: v1.2.9

Major Performance Improvements (v1.2.9)

  • Python FFI Support: Full Python development libraries pre-installed for seamless FFI integration
  • Comprehensive Dependency Caching: 22+ critical packages pre-loaded including web frameworks, XML processing, and crypto libraries
  • Optimized Build Times: 60-80% reduction in CI build times through intelligent dependency pre-loading
  • Synchronized Index States: Consistent Cabal package index across all builds

Pre-loaded Packages

  • Web frameworks / HTTP: http-client, websockets, wai, wai-cors, warp, miso (v1.3.0 drops wreq from preload only)
  • XML/HTML Processing: xml, xml-conduit, html-conduit, html-entities, tagsoup
  • Additional Libraries: pandoc-types, lens, wai-middleware-static, blaze-html, blaze-markup
  • Crypto Libraries: crypto-api, crypto-pubkey-types, authenticate-oauth

Enhanced Features

  • Direct Package Installation: Critical dependencies installed with version constraints for maximum compatibility
  • Python FFI Ready: No additional system package installation required for Python FFI builds
  • Better Layer Caching: Improved Docker layer efficiency through comprehensive dependency management

See CHANGELOG.md for complete details.

πŸ”„ Architecture Benefits

  • Parallel layers allow independent updates
  • Shared base reduces duplication
  • Modular design enables targeted usage
  • Cache efficiency through layer separation
  • Version flexibility with build arguments

πŸ“š Documentation

Each layer includes built-in documentation:

  • ~/README.md - Base layer information
  • ~/README-haskell.md - Haskell layer guide
  • ~/README-tex.md - TeX layer guide
  • ~/README-full.md - Full environment guide

🀝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test with ./build-parallel.sh
  5. Submit a pull request

πŸ“„ License

Apache License 2.0 - see LICENSE file for details.


Built with ❀️ for the Haskell and TeX communities

Candidate image validation

Push an env/** branch to build and test the three image stages on GitHub Actions. Candidate images use base-<commit>, haskell-<commit> and tex-<commit> tags; branch builds leave version and latest tags unchanged. Merging the candidate changes to main rebuilds with the stage caches, tests the exact full-image digest, then promotes the version and latest tags.

About

dev container for modern Haskell/WASM-related projects with TeX rendering

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages