Getting Started

Weld belongs in the root project that owns packaging and release work for a multi-project Elixir repo.

1. Add The Dependency

def deps do
  [
    {:weld, "~> 0.7.1", runtime: false}
  ]
end

2. Add A Repo-Local Manifest

Create a manifest such as packaging/weld/my_bundle.exs:

[
  workspace: [
    root: "../..",
    project_globs: ["core/*", "runtime/*"]
  ],
  dependencies: [
    external_lib: [
      requirement: "~> 1.2",
      opts: []
    ]
  ],
  artifacts: [
    my_bundle: [
      roots: ["runtime/local"],
      package: [
        name: "my_bundle",
        otp_app: :my_bundle,
        version: "0.1.0"
      ],
      output: [
        docs: ["README.md", "guides/architecture.md"]
      ],
      verify: [
        artifact_tests: ["packaging/weld/my_bundle/test"],
        hex_build: true,
        hex_publish: true
      ]
    ]
  ]
]

workspace.root is resolved relative to the manifest file. In packaging/weld/..., "../.." points back to the repo root.

Use dependencies when a selected workspace project depends on an external package through a local :path, :git, or :github declaration that cannot ship in the welded artifact as-is. weld will rewrite that dependency to the canonical requirement you declare here.

3. Inspect Before You Project

mix weld.inspect
mix weld.graph --format dot

Use these commands to confirm project discovery, classifications, and graph shape before generating output.

If the repo uses one of Weld's standard manifest locations, you can omit the manifest path entirely. Explicit paths are still useful when a repo carries more than one manifest.

4. Generate The Welded Package

mix weld.project

Package-projection mode (the default, mode: :package_projection) creates a standalone Mix project under dist/hex/<package>/ with a component-preserving layout.

Monolith mode (mode: :monolith) creates a merged flat project under dist/monolith/<package>/, combining sources, tests, config, migrations, and priv from all selected packages into a single project tree.

If selected projects publish OTP application modules, the generated package also gets a merged lib/<otp_app>/application.ex. In monolith mode this module also bootstraps per-package config at startup via Config.Reader.

If monolith tests need source-only support from non-selected workspace projects, keep that policy explicit with monolith_opts[:test_support_projects].

5. Verify The Welded Package

mix weld.verify

Package-projection mode runs:

• mix deps.compile
• mix compile --warnings-as-errors --no-compile-deps
• mix test
• mix docs --warnings-as-errors
• mix hex.build
• mix hex.publish --dry-run --yes
• optional smoke verification when configured

Set verify: [hex_build: false] for internal artifacts that intentionally depend on non-Hex git dependencies, and verify: [hex_publish: false] when you want package verification without the dry-run publish step.

Monolith mode runs:

• per-package test baseline (each selected package's own test suite)
• mix deps.get
• mix compile --warnings-as-errors
• mix test (asserts test count is not lower than the baseline sum)
• mix docs --warnings-as-errors
• mix hex.build

Monolith artifacts can also disable hex.build with verify: [hex_build: false] when they are intentionally not Hex-packagable.

6. Prepare, Track, And Archive Releases

mix release.prepare
mix release.track
mix hex.publish --yes
mix release.archive

The prepared bundle always contains the projected project tree, lockfile, and release metadata. It also contains the tarball when verify.hex_build is enabled. That means internal-only artifacts can still use prepare, track, and archive without pretending they are Hex-buildable.

mix release.track updates projection/<package_name> from the prepared bundle and creates the first projection branch as an orphan by default.