melange

To ensure build isolation and prevent pipeline commands from modifying the host system, Melange executes all runs commands inside a virtual container created by bubblewrap (bwrap).

The guest directory serves as the root filesystem for this container. This allows commands to assume standard filesystem locations (like /usr/bin/gcc) while actually interacting with the files laid out in the guest directory (e.g., ${GUEST_DIR}/usr/bin/gcc).

Melange supports cross-architecture builds using the following mechanisms:

• Native Builds: If building for the host architecture (e.g., amd64 on amd64), all runs commands execute natively.
• Cross-Architecture Builds: If building for a different architecture (e.g., arm64 while on amd64), commands are executed via binfmt_misc user-mode emulation.

Requirement: To enable cross-architecture builds, binfmt_misc must be installed on the host system.

The go/bump pipeline supports Go workspace mode (using go.work files). When the work parameter is set to true, the pipeline will use go work vendor instead of go mod vendor for dependency management.

  - uses: go/bump
    with:
      deps: github.com/sirupsen/logrus@v1.9.3
      work: true

You can define test: blocks at the top level (to test the 'main' package) or inside a subpackages definition. Each block can specify an environment (to define required packages) and a pipeline (to define the actual test commands).

If you are decoupling your tests into a separate file from your build file, you must include a mandatory (but empty) pipeline: key at the top level to satisfy the configuration parser.

package:
  name: php-8.2-msgpack
  version: 2.2.0
  epoch: 0
  description: "Tests for PHP extension msgpack"
  copyright:
    - license: BSD-3-Clause

# This is mandatory to avoid config parsing errors
pipeline:

test:
  environment:
    contents:
      packages:
        - wolfi-base
        - apk-tools
  pipeline:
    - runs: |
        # Test commands go here

To use an .apk package built with Melange in an image built with apko, you have two primary options:

1. Package Repository: Upload the built .apk to a standard package repository.
2. Local Repository: Use a "local" repository. This is useful for running both Melange and apko builds in the same directory or GitHub repository without requiring external storage. This pattern allows for seamless integration in CI/CD workflows.

Melange allows you to test packages using a test command. Tests are defined using a test: keyword block, which follows a similar structure to the build pipeline.

There are two distinct environments involved in a test run:

1. Test environment (workspace): A single shared workspace mounted as the CWD (Current Working Directory) for each test run. You can use the --source-dir flag to make external files (like test fixtures) available in this workspace.
2. Execution environment (guest): A fresh container built via apko for each test. This container contains the Package Under Test (PUT) by default, plus any additional packages you specify in test.environment.contents.packages. This ensures tests run in a clean, isolated environment containing only the necessary runtime dependencies.

The Melange build process follows these high-level steps:

1. Dependency Resolution: Evaluates pipeline steps for needs sections and merges them into environment.contents.
2. Environment Setup: Uses apko to create a tar stream of environment.contents packages and lays them out in the guest directory.
3. Workspace Preparation: Creates the workspace directory, copies files from the source directory to it, and bind-mounts the workspace into the guest at /home/build.
4. Execution: Runs each step in the pipeline (either uses or runs) inside the workspace.
5. Output: Emits the final .apk package (and any subpackages) and generates/signs an APKINDEX if requested.
6. Cleanup: Removes the guest and workspace directories.