### Build Example with Docker

Source: https://github.com/chainguard-dev/melange/blob/main/README.md

Builds an example package using the Melange container image. Mounts the current directory and provides elevated privileges.

```shell
docker run --privileged -v "$PWD":/work cgr.dev/chainguard/melange build examples/gnu-hello.yaml
```

--------------------------------

### Install Melange from Source

Source: https://github.com/chainguard-dev/melange/blob/main/README.md

Installs the Melange CLI tool by compiling it from source using Go.

```shell
go install chainguard.dev/melange@latest
```

--------------------------------

### cmake/install

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/cmake/README.md

Install a CMake project. This step installs the built project artifacts.

```APIDOC
## cmake/install

### Description
Build a CMake project.

### Inputs

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Inputs

- **output-dir** (string) - Optional - The output directory for the CMake build. Default: `output`
```

--------------------------------

### Example: Pop patches for apk-tools

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_source_pop.md

This example demonstrates how to use the melange source pop command with a specific configuration file.

```bash
melange source pop apk-tools.yaml
```

--------------------------------

### Example: Convert libx11 APKBUILD

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_convert_apkbuild.md

This example demonstrates how to convert the APKBUILD file for the 'libx11' package into a melange.yaml configuration. It specifies the package name as an argument.

```bash
convert apkbuild libx11
```

--------------------------------

### Example: Extracting source with melange source get

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_source_get.md

This example demonstrates how to use `melange source get` to extract source code from a `vim.yaml` configuration file into the `./src` directory.

```bash
melange source get vim.yaml -o ./src
```

--------------------------------

### Example: Convert Latest Botocore Python Package

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_convert_python.md

This example demonstrates how to convert the latest available version of the 'botocore' Python package into a melange.yaml configuration.

```bash
# Convert the latest botocore python package
convert python botocore
```

--------------------------------

### Example Melange Build File Pipeline with Substitutions

Source: https://github.com/chainguard-dev/melange/blob/main/README.md

This example demonstrates how to use default substitutions like ${{targets.destdir}} and ${{package.name}} within a build pipeline to create directories dynamically.

```yaml
pipeline:
  - name: 'Create tmp dir'
    runs: mkdir ${{targets.destdir}}/var/lib/${{package.name}}/tmp
```

--------------------------------

### autoconf/make-install

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/autoconf/README.md

Executes the 'make install' command for autoconf projects. Allows specifying the Makefile directory, custom make options, and specific install targets.

```APIDOC
## autoconf/make-install

### Description
Executes the 'make install' command for autoconf projects. Allows specifying the Makefile directory, custom make options, and specific install targets.

### Inputs
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **dir** (string) - Optional - The directory containing the Makefile. Default: `.`
- **opts** (string) - Optional - Options to pass to the `make` command.
- **targets** (string) - Optional - Makefile install targets, space-separated. Default: `install`

### Request Example
```json
{
  "dir": "/path/to/makefile",
  "opts": "-j4",
  "targets": "install install-strip"
}
```

### Response
#### Success Response (200)
- **output** (string) - The standard output from the make install command.
- **error** (string) - Any errors encountered during the make install command execution.

#### Response Example
```json
{
  "output": "Installation complete.",
  "error": null
}
```
```

--------------------------------

### melange package-version Example Usage

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_package-version.md

An example demonstrating how to use the `melange package-version` command with a configuration file. This command is equivalent to running `melange query config.yaml '{{ .Package.Name }}-{{ .Package.Version }}-r{{ .Package.Epoch }}'`.

```bash
melange package-version [config.yaml]
```

--------------------------------

### Install Melange with Homebrew

Source: https://github.com/chainguard-dev/melange/blob/main/README.md

Installs the Melange CLI tool using the Homebrew package manager.

```shell
brew install melange
```

--------------------------------

### Melange Build Directory Structure Example

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-PROCESS.md

Illustrates the relationship between source, workspace, and guest directories during a Melange build, showing how files are copied and bind-mounted.

```text
/home/user/src                <-- source directory
/home/user/src/main.go        <-- original file in source
/home/user/src/go.mod         <-- original file in source
/home/user/src/go.sum         <-- original file in source

/tmp/ws                       <-- workspace directory, bind-mounted to runner:/home/build
/tmp/ws/main.go               <-- copied from source directory
/tmp/ws/go.mod                <-- copied from source directory
/tmp/ws/go.sum                <-- copied from source directory

/tmp/guest                     <-- temporary guest directory created by melange
/tmp/guest/bin                 <-- files and dirs created by apk package dependencies
/tmp/guest/bin/busybox         <-- files and dirs created by apk package dependencies
/tmp/guest/home/build          <-- bind-mounted from workspace at /tmp/ws
/tmp/guest/home/build/main.go  <-- file bind-mounted from workspace at /tmp/ws
/tmp/guest/home/build/go.mod   <-- file bind-mounted from workspace at /tmp/ws
/tmp/guest/home/build/go.sum   <-- file bind-mounted from workspace at /tmp/ws
```

--------------------------------

### Full Melange Test Invocation Example

Source: https://github.com/chainguard-dev/melange/blob/main/docs/TESTING.md

A comprehensive example demonstrating how to run Melange tests with specific source directories, architectures, and appended keyrings/repositories for local development.

```shell
melange test ./py3-pandas-test.yaml py3-pandas \
--source-dir /tmp/testfiles --arch aarch64 \
--keyring-append /Users/vaikas/projects/go/src/github.com/wolfi-dev/os/local-melange.rsa.pub \
--repository-append /Users/vaikas/projects/go/src/github.com/wolfi-dev/os/packages \
--repository-append https://packages.wolfi.dev/os \
--keyring-append https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
```

--------------------------------

### npm/install

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/npm/README.md

Installs a portable npm package with specified configurations.

```APIDOC
## npm/install

### Description
Install a portable npm package.

### Inputs

#### Required Inputs
- **package** (string) - The name of the package to npm install.
- **version** (string) - The version of the package to npm install.

#### Optional Inputs
- **npm-package** (string) - The npm command to run. Defaults to 'npm'.
- **overrides** (string) - Space, comma or newline-separated list of package@version to use in npm overrides, e.g. "yargs@^17.0.0 get-stdin@^9.0.0".
- **prefix** (string) - The -prefix argument to pass to npm install; where /bin and /lib will be copied to. Defaults to "${{targets.contextdir}}/usr/".

```

--------------------------------

### Simple Go Project Compilation with `go/install`

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-GO.md

Use `go/install` for projects that do not require complex interactions with `go build` or control over source code downloading. It simplifies compiling publicly available Go projects by leveraging `go install`.

```yaml
package:
  name: hello
  version: v0.0.1
  epoch: 0
  description: "A project that will greet the world infinitely"
environment:
  contents:
    keyring:
      - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
    repositories:
      - https://packages.wolfi.dev/os
pipeline:
  - uses: go/install
    with:
      package: github.com/puerco/hello
      version: HEAD
```

--------------------------------

### Load Zsh Completion

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_completion.md

To load completions for each session, execute this command once. You may need to start a new shell for this setup to take effect.

```zsh
melange completion zsh > "${fpath[1]}/_melange"
```

--------------------------------

### Python Test Fixture Example

Source: https://github.com/chainguard-dev/melange/blob/main/docs/TESTING.md

Example of creating a Python test fixture file for use with the `--source-dir` option. This file can contain any necessary imports and data structures for your tests.

```python
import numpy as np
import pandas as pd
s = pd.Series([1,3,5,np.nan, 6, 8])
dates = pd.date_range("20130101", periods=6)
df = pd.DataFrame(np.random.randn(6, 4), index=dates, columns=list("ABCD"))
```

--------------------------------

### Melange Build File Example

Source: https://github.com/chainguard-dev/melange/blob/main/README.md

A declarative melange build file defining package metadata, build environment, pipeline steps, and subpackages.

```yaml
package:
  name: hello
  version: 2.12
  epoch: 0
  description: "the GNU hello world program"
  copyright:
    - attestation: |
        Copyright 1992, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2005,
        2006, 2007, 2008, 2010, 2011, 2013, 2014, 2022 Free Software Foundation,
        Inc.
      license: GPL-3.0-or-later
  dependencies:
    runtime:

environment:
  contents:
    repositories:
      - https://dl-cdn.alpinelinux.org/alpine/edge/main
    packages:
      - alpine-baselayout-data
      - busybox
      - build-base
      - scanelf
      - ssl_client
      - ca-certificates-bundle

pipeline:
  - uses: fetch
    with:
      uri: https://ftp.gnu.org/gnu/hello/hello-${{package.version}}.tar.gz
      expected-sha256: cf04af86dc085268c5f4470fbae49b18afbc221b78096aab842d934a76bad0ab
  - uses: autoconf/configure
  - uses: autoconf/make
  - uses: autoconf/make-install
  - uses: strip

subpackages:
  - name: "hello-doc"
    description: "Documentation for hello"
    dependencies:
      runtime:
        - foo
    pipeline:
      - uses: split/manpages
    test:
      pipeline:
        - uses: test/docs

test:
  environment:
    contents:
      packages:
        - bar
  pipeline:
    - runs: |
        hello
        hello --version

```

--------------------------------

### Package Epoch Example

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

An monotonically increasing value starting from 0, indicating changes to the same package version, such as security patches.

```yaml
epoch: 0
```

--------------------------------

### Building Go Projects with `go/build`

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-GO.md

The `go/build` pipeline offers a declarative interface to `go build` for projects with already installed or cloned Go source code. It allows compiling multiple packages, but artifact collection and installation are manual.

```yaml
package:
  name: hello
  version: v0.0.1
  epoch: 0
  description: "A project that will greet the world infinitely"
environment:
  contents:
    keyring:
      - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
    repositories:
      - https://packages.wolfi.dev/os
pipeline:
  - uses: git-checkout
    with:
      repository: https://github.com/uservers/miniprow.git
      destination: build-dir
  - run: |
      git checkout ${{package.version}}
  - uses: go/build
    with:
      modroot: build-dir
      tags: enterprise
      packages: main.go
      output: hello
```

--------------------------------

### Package Description Example

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Provides a human-readable description of the package. This information is displayed when searching for the package.

```yaml
description: "the Python programming language"
```

--------------------------------

### Runtime Dependencies Configuration

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

List packages required at runtime, which will be installed via apk.

```yaml
dependencies:
  runtime:
    - openssl
    - socat
    - curl
```

--------------------------------

### melange source get command options

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_source_get.md

These are the available options for the `melange source get` command, including help and output directory specification.

```bash
  -h, --help   help for get
```

--------------------------------

### Define Post-Deinstallation Scriptlet

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Specify executable scripts to run at various stages of the package lifecycle. This example shows a 'post-deinstall' scriptlet that installs busybox symlinks.

```yaml
scriptlets:
  post-deinstall: |
    #!/bin/busybox sh
    /bin/busybox --install -s
```

--------------------------------

### melange source get command usage

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_source_get.md

This is the basic syntax for the `melange source get` command. It requires a configuration file and accepts flags for options.

```bash
melange source get [config.yaml] [flags]
```

--------------------------------

### Scan a specific APK file

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_scan.md

Example of scanning a specific APK file, 'bash.yaml', to regenerate its .PKGINFO. This is the most common usage.

```bash
melange scan bash.yaml
```

--------------------------------

### Package Name Example

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Defines the unique name for the package. It's recommended to use the same name as the YAML file without the extension for consistency.

```yaml
name: python-3.10
```

--------------------------------

### Specify Packages for Build Environment

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Define the list of packages to be installed in the build environment, including build-time dependencies.

```yaml
environment:
  contents:
    repositories:
      - https://packages.wolfi.dev/os
    keyring:
      - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
    packages:
      - busybox
      - ca-certificates-bundle
      - go
```

--------------------------------

### xcover/profile

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/xcover/README.md

Starts the coverage profile using the xcover tool. This stage requires the executable path and allows configuration of function inclusion/exclusion, log level, scope, verbosity, and wait timeout.

```APIDOC
## xcover/profile

### Description
Starts the coverage profile with the xcover tool.

### Inputs
#### Parameters
- **exclude-functions** (regex) - Optional - The function symbols to exclude from profiling as a regular expression.
- **executable-path** (path) - Required - The path to the executable of the application to test.
- **include-functions** (regex) - Optional - The function symbols to include in profiling as a regular expression. When set, only matching symbols are profiled.
- **log-level** (string) - Optional - The log level of the xcover profile command. Defaults to "info".
- **package** (string) - Optional - The xcover package. Defaults to "xcover".
- **scope** (string) - Optional - The function scope to profile: "binary" (all functions) or "project" (project module only). The "project" scope is only supported by Go binaries and is a no-op for others. Defaults to "project".
- **verbose** (boolean) - Optional - Enable verbosity of the xcover profile command. It prints out all the functions being traced real-time. Defaults to "false".
- **wait-timeout** (seconds) - Optional - The maximum amount of time to wait for the xcover profiler to be ready for profiling, in seconds. Defaults to 60.
```

--------------------------------

### Set Build Timeout

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Configure an optional timeout duration for the build process in seconds. This example sets a timeout of 1 hour (3600 seconds).

```yaml
package:
  timeout: 3600  # 1 hour in seconds
```

--------------------------------

### Package Version Example

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Specifies the version of the package. This field is crucial for identifying the package's release.

```yaml
version: 3.10.12
```

--------------------------------

### Run Melange Version with Docker

Source: https://github.com/chainguard-dev/melange/blob/main/README.md

Checks the installed Melange version using its official Docker image.

```shell
docker run cgr.dev/chainguard/melange version
```

--------------------------------

### Cargo Build Parameters

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-CARGO.md

Configure build parameters for the `cargo/build` pipeline. These options control the output filename, cargo build arguments, module root, and installation prefix.

```yaml
  output:
    description: |
      Filename to use when writing the binary. The final install location inside
      the apk will be in prefix / install-dir / output

  opts:
    description: |
      Options to pass to cargo build. Defaults to release

  modroot:
    description: |
      Top directory of the rust package, this is where the target package lives.
      Before building, the cargo pipeline wil cd into this directory. Defaults
      to current working directory

  prefix:
    description: |
      Installation prefix. Defaults to usr
```

--------------------------------

### Git Checkout with Cherry-Picking

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-GIT.md

This example demonstrates how to use the cherry-picking feature to apply specific commits, useful for addressing security vulnerabilities like CVE-2024-4032. The format for cherry-picks is '[branch/]commit: comment'.

```yaml
pipeline:
  - uses: git-checkout
    with:
      expected-commit: 976ea78599d71f22e9c0fefc2dc37c1d9fc835a4
      repository: https://github.com/python/cpython.git
      tag: v3.10.14
      cherry-picks: |
        3.10/c62c9e518b784fe44432a3f4fc265fb95b651906: CVE-2024-4032

```

--------------------------------

### R/build Pipeline Parameters: Package

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-R.md

Define the R package to be installed. This parameter is required for the `R/build` pipeline.

```yaml
package:
  description: |
    The R package to install
  required: true

```

--------------------------------

### Updating Go Dependencies with `go/bump`

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-GO.md

The `go/bump` pipeline is an interface to the `GoBump` tool for updating Go dependency versions. This example shows how to update `github.com/sirupsen/logrus` to `v1.9.3` before building the project.

```yaml
package:
  name: hello
  version: 0.0.1
  epoch: 0
  description: "A project that will greet the world infinitely"

environment:
  contents:
    keyring:
      - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
    repositories:
      - https://packages.wolfi.dev/os

pipeline:
  - uses: git-checkout
    with:
      repository: https://github.com/puerco/hello.git
      expected-commit: a73c4feb284dc6ed1e5758740f717f99dcd4c9d7
      tag: v${{package.version}}

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

  - uses: go/build
    with:
      tags: enterprise
      packages: .
      output: hello
```

--------------------------------

### Join Regex Match Subgroups with Underscore

Source: https://github.com/chainguard-dev/melange/blob/main/docs/VAR-TRANSFORMS.md

This var-transform example demonstrates joining regex match subgroups using `${1}` and `${2}` for cases where a simple '$' substitution is insufficient, such as converting '1.3.6.8' to '1.3.6_8'.

```yaml
var-transforms:
  - from: ${{package.version}}
    match: ^(\d+\.\d+\.\d+).(\d+).*
    replace: "${1}_${2}"
    to: mangled-version-binary
```

--------------------------------

### Specify Package Versions in Build Environment

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Use version specifiers to install specific versions or ranges of packages in the build environment.

```yaml
environment:
  packages:
    - go>1.21    # install anything newer than 1.21, excluding 1.21
    - foo=~4.5.6 # install any version with a name starting with "4.5.6" (e.g., 4.5.6-r7)
    - python3    # install the latest stable version of python3.
```

--------------------------------

### melange package-version Command Synopsis

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_package-version.md

This is the basic command structure for reporting the package version from a YAML configuration file. Use this command to get the package name, version, and epoch.

```bash
melange package-version [flags]
```

--------------------------------

### Transform Version Strings with Regex

Source: https://github.com/chainguard-dev/melange/blob/main/docs/UPDATE.md

Use regex patterns to transform non-compliant version tags into a format compatible with apk. This example converts 'p' followed by digits to a dot notation.

```yaml
update:
  enabled: true
  version-transform:
    - match: p(\d+)$ 
      replace: .${1}
```

--------------------------------

### Configure Trigger Scriptlet for Directory Monitoring

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Define a 'trigger' scriptlet that monitors specified paths. When new files are added or removed in these directories, the associated script will execute. This example monitors binary directories.

```yaml
scriptlets:
  trigger:
    paths:
      - /bin
      - /sbin
      - /usr/bin
      - /usr/sbin
    script: |
      #!/bin/busybox sh
      /bin/busybox --install -s
```

--------------------------------

### Launch Melange DevEnv

Source: https://github.com/chainguard-dev/melange/blob/main/docs/DEVENV.md

Clone the melange repository, navigate into it, and execute the script to build and launch the development environment. This will drop you into a Wolfi shell with your local code mounted.

```bash
git clone git@github.com:chainguard-dev/melange.git

cd melange

./hack/make-devenv.sh
```

--------------------------------

### Use generated initramfs in a build

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_initramfs.md

Demonstrates how to use a pre-generated initramfs with the `melange build` command by setting the `QEMU_BASE_INITRAMFS` environment variable.

```bash
QEMU_BASE_INITRAMFS=./initramfs.cpio melange build --runner qemu ...
```

--------------------------------

### autoconf/configure

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/autoconf/README.md

Runs the autoconf configure script to prepare the build environment. It accepts build and host triplets, the directory of the configure script, and additional options.

```APIDOC
## autoconf/configure

### Description
Runs the autoconf configure script to prepare the build environment. It accepts build and host triplets, the directory of the configure script, and additional options.

### Inputs
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **build** (string) - Optional - The GNU triplet which describes the build system. Default: `${{host.triplet.gnu}}`
- **dir** (string) - Optional - The directory containing the configure script. Default: `.`
- **host** (string) - Optional - The GNU triplet which describes the host system. Default: `${{host.triplet.gnu}}`
- **opts** (string) - Optional - Options to pass to the `./configure` command.

### Request Example
```json
{
  "build": "x86_64-linux-gnu",
  "dir": "/path/to/configure",
  "host": "aarch64-linux-gnu",
  "opts": "--enable-feature --disable-other"
}
```

### Response
#### Success Response (200)
- **output** (string) - The standard output from the configure script.
- **error** (string) - Any errors encountered during the configure script execution.

#### Response Example
```json
{
  "output": "Configuration successful.",
  "error": null
}
```
```

--------------------------------

### melange source get inherited options

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_source_get.md

These options are inherited from parent commands and can be used with `melange source get`. They control logging level and the output directory for extracted sources.

```bash
      --log-level string    log level (e.g. debug, info, warn, error) (default "INFO")
  -o, --output string       output directory for extracted source (default "./source")
      --source-dir string   directory where patches and other sources are located (defaults to ./package-name/)
```

--------------------------------

### Create Repository Index

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_index.md

Generates a repository index from a list of package files. Use the -o flag to specify the output file name.

```bash
melange index -o APKINDEX.tar.gz *.apk
```

--------------------------------

### cmake/configure

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/cmake/README.md

Configure a CMake project. This step prepares the build environment for the project.

```APIDOC
## cmake/configure

### Description
Configure a CMake project.

### Inputs

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Inputs

- **opts** (string) - Optional - Compile options for the CMake build.
- **output-dir** (string) - Optional - The output directory for the CMake build. Default: `output`
```

--------------------------------

### Enable QEMU virtiofs for Cache Persistence

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-CACHE.md

Set QEMU_USE_VIRTIOFS to 1 to enable virtiofs for the cache directory. This allows cache writes to be persisted to the host filesystem and improves I/O performance. Ensure virtiofsd is available on the host.

```shell
QEMU_USE_VIRTIOFS=1 melange build --runner qemu --cache-dir /path/to/cache ...
```

--------------------------------

### Configure Build Environment Accounts and Run-As User

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Define additional users and groups for the build environment and specify the user to run the build process.

```yaml
environment:
  accounts:
    users:
      - username: user_one
        uid: 2000
        gid: 1500
      - username: user_two
        uid: 2001
        gid: 1500
    groups:
      - groupname: webusers
      - gid 1500
    run-as: user_one
```

--------------------------------

### Build Package from YAML Config

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_build.md

Use this command to build a package. Specify the path to your YAML configuration file as an argument.

```bash
melange build [config.yaml]
```

--------------------------------

### cmake/build

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/cmake/README.md

Build a CMake project. This step compiles the project after configuration.

```APIDOC
## cmake/build

### Description
Build a CMake project.

### Inputs

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Inputs

- **opts** (string) - Optional - Compile options for the CMake build.
- **output-dir** (string) - Optional - The output directory for the CMake build. Default: `output`
```

--------------------------------

### Load Fish Completion

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_completion.md

To load completions for each session, execute this command once. This command pipes the completion script to the source function.

```fish
melange completion fish > ~/.config/fish/completions/melange.fish
```

--------------------------------

### Generate initramfs with custom packages and repositories

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_initramfs.md

Generates an initramfs for the aarch64 architecture, including a custom init package and an additional repository. The output is saved to a specified file.

```bash
melange initramfs \
  --arch aarch64 \
  --output ./custom-initramfs.cpio \
  --init-package my-custom-init \
  --repository https://my.repo.dev/packages
```

--------------------------------

### Generate default initramfs for x86_64

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_initramfs.md

Generates a default initramfs for the x86_64 architecture and saves it to the specified output path.

```bash
melange initramfs --arch x86_64 --output ./initramfs.cpio
```

--------------------------------

### Melange Query Command Help

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_query.md

Displays help information for the melange query command. Use this to understand available flags and options.

```bash
melange query --help
```

--------------------------------

### melange package-version Help Flag

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_package-version.md

Standard help flag for the `melange package-version` command.

```bash
-h, --help   help for package-version
```

--------------------------------

### Sign multiple APK packages

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_sign.md

This command allows signing multiple APK packages at once using a wildcard. Ensure the signing key is correctly specified.

```bash
melange sign [--signing-key=key.rsa] *.apk
```

--------------------------------

### Load Bash Completion

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_completion.md

To load completions for each session, execute this command once. Ensure you have the necessary permissions to write to the specified directory.

```bash
melange completion bash > /etc/bash_completion.d/yourprogram
```

--------------------------------

### autoconf/make

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/autoconf/README.md

Runs the 'make' command for autoconf projects. Users can specify the Makefile directory, custom make options, and build targets.

```APIDOC
## autoconf/make

### Description
Runs the 'make' command for autoconf projects. Users can specify the Makefile directory, custom make options, and build targets.

### Inputs
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **dir** (string) - Optional - The directory containing the Makefile. Default: `.`
- **opts** (string) - Optional - Options to pass to the `make` command.
- **targets** (string) - Optional - Makefile targets to build, space-separated.

### Request Example
```json
{
  "dir": "/path/to/makefile",
  "opts": "-j8",
  "targets": "all"
}
```

### Response
#### Success Response (200)
- **output** (string) - The standard output from the make command.
- **error** (string) - Any errors encountered during the make command execution.

#### Response Example
```json
{
  "output": "Build successful.",
  "error": null
}
```
```

--------------------------------

### Transform Package Version for Tarball Fetch

Source: https://github.com/chainguard-dev/melange/blob/main/docs/VAR-TRANSFORMS.md

Use var-transforms to modify a package version for use in a tarball URI. This example transforms a Java OpenJDK version to include a '+' sign, which is necessary for fetching the correct tarball.

```yaml
var-transforms:
  - from: ${{package.version}}
    match: \.(\d+)$
    replace: +$1
    to: mangled-package-version
```

--------------------------------

### Sign an APK package

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_sign.md

Use this command to sign a single APK package with a specified signing key. The default signing key is 'local-melange.rsa'.

```bash
melange sign [--signing-key=key.rsa] package.apk
```

--------------------------------

### Copyright License and Paths Configuration

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Define licenses for different parts of a package. Defaults to the entire package if paths are not specified.

```yaml
copyright:
  - license: Apache-2.0
    paths:
      - "*"
  - license: BSD-3-Clause
    paths:
      - "vendor/foo/**"
```

--------------------------------

### Build Package with Docker and Volume Mount

Source: https://github.com/chainguard-dev/melange/blob/main/README.md

Builds a melange package using Docker, mounting the current directory and providing elevated privileges for the build process.

```shell
docker run --privileged --rm -v "${PWD}":/work \
  cgr.dev/chainguard/melange build examples/gnu-hello.yaml
```

--------------------------------

### melange convert apkbuild Command Synopsis

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_convert_apkbuild.md

This is the basic command structure for converting an APKBUILD package to a melange.yaml file. Use this to understand the command's entry point.

```bash
melange convert apkbuild [flags]
```

--------------------------------

### Sign APK Index

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_sign-index.md

Use this command to sign an APK index file. You can re-sign an index with the same signature or sign a new one, using the `--force` flag to overwrite.

```bash
melange sign-index [--signing-key=key.rsa] <APKINDEX.tar.gz>
```

```bash
melange sign-index [--signing-key=key.rsa] <APKINDEX.tar.gz> --force
```

--------------------------------

### Go Build Parameters: Tags, LDFLAGS, and Deps

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-GO.md

These parameters can be set in the Melange configuration file to pass specific values to the Go compiler. `tags` and `ldflags` are passed directly to `go build`, while `deps` specifies Go modules to update before building.

```yaml
tags:
  description: |
    A comma-separated list of build tags to pass to the go compiler

ldflags:
  description:
    List of [pattern=]arg to pass to the go compiler with -ldflags

deps:
  description: |
    space separated list of go modules to update before building. example: github.com/foo/bar@v1.2.3
```

--------------------------------

### Build with Composer Cache Directory

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-CACHE.md

Utilize the --cache-dir flag with melange build to point to a local directory for Composer's cache.

```shell
melange build --cache-dir /path/to/your/cache ...
```

```shell
# Create a cache directory
mkdir -p ~/.cache/melange

# Run melange with the cache directory
melange build --cache-dir ~/.cache/melange ...
```

--------------------------------

### Compile YAML Configuration

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_compile.md

Use this command to compile a melange YAML configuration file. Ensure the configuration file path is provided as an argument.

```bash
melange compile [config.yaml]
```

--------------------------------

### Parallel Version Streams with Provides

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Define provides for different version streams of the same package to allow users to select specific major versions.

```yaml
package:
  name: php-8.1
  version: 8.1.23
  epoch: 0
  dependencies:
    provides:
      - php=${{package.full-version}}
```

```yaml
package:
  name: php-8.2
  version: 8.2.10
  epoch: 1
  dependencies:
    provides:
      - php=${{package.full-version}}
```

--------------------------------

### Generate a Package Signing Key

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_keygen.md

Use this command to generate a new cryptographic key for signing packages. Specify the desired output filename for the key.

```bash
melange keygen [key.rsa]
```

--------------------------------

### Configure R Package Build with R/build Pipeline

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-R.md

Use this configuration to build an R package from source using the `R/build` pipeline. It clones the repository, builds the package, and then strips unnecessary symbols.

```yaml
package:
  name: cran-proxy
  version: 0.4_27
  epoch: 0
  description: Distance and similarity measures
  copyright:
    - license: GPL-2.0-or-later

environment:
  contents:
    packages:
      - R
      - R-dev
      - busybox

var-transforms:
  - from: ${{package.version}}
    match: '_'
    replace: '-'
    to: mangled-package-version

pipeline:
  - uses: git-checkout
    with:
      repository: https://github.com/cran/proxy
      tag: ${{vars.mangled-package-version}}
      expected-commit: 311a8569a534460ef04473ffa442dc7b72ba9a41

  - uses: R/build
    with:
      package: proxy
      version: ${{vars.mangled-package-version}}

  - uses: strip

update:
  enabled: true
  version-transform:
    - match: '_'
      replace: '-'
  github:
    identifier: cran/proxy
    use-tag: true

```

--------------------------------

### Define Local Build Environment Contents

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Configure the build environment for local development by specifying package repositories and keyrings.

```yaml
environment:
  contents:
    repositories:
    - https://packages.wolfi.dev/bootstrap/stage3
    - https://packages.wolfi.dev/os
    keyring:
    - https://packages.wolfi.dev/bootstrap/stage3/wolfi-signing.rsa.pub
    - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
```

--------------------------------

### Query Melange YAML with Go Templates

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_query.md

Use this command to query a Melange YAML file. It utilizes Go templates to extract and format information, such as package name, version, and epoch. Ensure the YAML file and the template expression are correctly formatted.

```bash
melange query config.yaml "{{ .Package.Name }}-{{ .Package.Version }}-{{ .Package.Epoch }}"
```

--------------------------------

### R/build Pipeline Parameters: Path

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-R.md

Specify the path to the R package source or source tarball. Defaults to the current directory if not provided.

```yaml
path:
  description: |
    Path to R package source or source tarball
  default: "."

```

--------------------------------

### Build Package with Melange CLI

Source: https://github.com/chainguard-dev/melange/blob/main/README.md

Builds a melange package using the specified YAML configuration file directly from the command line.

```shell
melange build examples/gnu-hello.yaml
```

--------------------------------

### maven/configure-mirror

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/maven/README.md

Configures a GCP Maven Central mirror for accelerated downloads.

```APIDOC
## maven/configure-mirror

### Description
Configure GCP Maven Central mirror for faster downloads

### Inputs
There are no configurable inputs for this pipeline.
```

--------------------------------

### xcover/wait

Source: https://github.com/chainguard-dev/melange/blob/main/pkg/build/pipelines/xcover/README.md

Waits for the xcover profiler to become ready. It accepts an optional package name and a wait timeout in seconds.

```APIDOC
## xcover/wait

### Description
Waits for the xcover profiler to be ready.

### Inputs
#### Parameters
- **package** (string) - Optional - The xcover package. Defaults to "xcover".
- **wait-timeout** (seconds) - Optional - The maximum amount of time to wait for the xcover profiler to be ready for profiling, in seconds. Defaults to 60.
```

--------------------------------

### Specify Build Resources

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Define optional resource specifications for the build environment, such as CPU, memory, and disk. These are used by external schedulers to provision build pods/VMs or by local runners as resource limits.

```yaml
package:
  resources:
    cpu: "8"
    memory: "16Gi"
    disk: "100Gi"
```

--------------------------------

### Package Aliasing with Provides (Pinned Version)

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Create an alias for a package with a specific version.

```yaml
dependencies:
  provides:
    - php=8.1.23
```

--------------------------------

### Copyright License Path Configuration

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Specify a path to a file containing the license text for SBOM embedding. Required for non-SPDX license values.

```yaml
copyright:
  - license: CustomLicense
    license-path: path/to/${{package.version}}/LICENSE
```

--------------------------------

### Package Aliasing with Provides (Floating Version)

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Provide a floating version alias for a package using `${{package.full-version}}` for automatic updates.

```yaml
dependencies:
  provides:
    - php=${{package.full-version}}
```

--------------------------------

### Melange Index Command Synopsis

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_index.md

This is the basic synopsis for the melange index command. It takes no arguments directly but uses flags for configuration.

```bash
melange index [flags]
```

--------------------------------

### Basic Git Checkout Pipeline Usage

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-GIT.md

Use this snippet to checkout a git repository. Ensure you update the repository URL and expected commit hash.

```yaml
  - uses: git-checkout
    with:
      repository: <UPDATE-ME>
      tag: ${{package.version}}
      expected-commit: <UPDATE-ME>

```

--------------------------------

### Build with Pip Cache Directory

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-CACHE.md

Use the --cache-dir flag with melange build to specify a local directory for pip's cache.

```shell
melange build --cache-dir ~/.cache/melange ...
```

--------------------------------

### Build Rust Package with cargo/build Pipeline

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-CARGO.md

Use this pipeline to build a Rust package and embed its dependency tree. Ensure the environment contains necessary build tools and libraries.

```yaml
package:
  name: eza
  version: 0.18.6
  epoch: 1
  description: "A modern, maintained replacement for ls"
  copyright:
    - license: MIT

environment:
  contents:
    keyring:
      - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
    repositories:
      - https://packages.wolfi.dev/os

environment:
  contents:
    packages:
      - build-base
      - busybox
      - ca-certificates-bundle
      - libgit2-dev
      - zlib-dev

pipeline:
  - uses: git-checkout
    with:
      repository: https://github.com/eza-community/eza
      tag: v${{package.version}}
      expected-commit: 1918eb866840486f3ad00a2d89d45f051072b2a9

  - uses: cargo/build
    with:
      output: ${{package.name}}
```

--------------------------------

### Copyright License with Variable Substitution

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-FILE.md

Use variables for license identifiers and paths, useful for dynamic license referencing based on package versions.

```yaml
vars:
  license-version: "2.4"

copyright:
  - license: LicenseRef-SOME-LICENSE-${{vars.some-version}}
    license-path: path/to/LICENSE
```

--------------------------------

### melange convert apkbuild Flags

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_convert_apkbuild.md

These flags customize the APKBUILD conversion process. Use '--base-uri-format' to specify a custom source for APKBUILDs and '--exclude-packages' to prevent certain packages from being auto-generated.

```bash
--base-uri-format string         URI to use for querying APKBUILD for provided package name (default "https://git.alpinelinux.org/aports/plain/main/%s/APKBUILD")
--exclude-packages stringArray   packages to exclude from auto generation of melange configs when detected in APKBUILD files
-h, --help                           help for apkbuild
```

--------------------------------

### Build with Maven Cache Directory

Source: https://github.com/chainguard-dev/melange/blob/main/docs/BUILD-CACHE.md

Provide a cache directory using the --cache-dir flag with melange build to enable Maven dependency caching.

```shell
melange build --cache-dir /path/to/my/cache ...
```

--------------------------------

### Convert a Gem to melange.yaml

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_convert_gem.md

Use this command to convert the latest version of a specified gem into a melange.yaml configuration. Ensure the gem name is provided as an argument.

```bash
melange convert gem fluentd
```

--------------------------------

### Melange Test Command Synopsis

Source: https://github.com/chainguard-dev/melange/blob/main/docs/md/melange_test.md

This is the basic command structure for testing a package using melange. It requires a YAML configuration file as input.

```bash
melange test <test.yaml> [package-name]
```

--------------------------------

### Run Melange Test with Default Package

Source: https://github.com/chainguard-dev/melange/blob/main/docs/TESTING.md

Execute tests defined in a specified test file using the package name derived from the current working directory.

```shell
melange test ./testfile.yaml
```

--------------------------------

### Go Bump Pipeline with Workspace Mode

Source: https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES-GO.md

Enable Go workspace mode for dependency management using `go work vendor`. This is useful for projects that utilize Go workspace files (go.work).

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

--------------------------------

### Test Environment Configuration for Subpackage

Source: https://github.com/chainguard-dev/melange/blob/main/docs/TESTING.md

YAML configuration for a test environment targeting a subpackage. It includes packages for the test execution and a pipeline to verify specific file contents.

```yaml
package:
  name: php-8.2-msgpack
# Again stuff omitted for readability
subpackages:
  - name: ${{package.name}}-dev
    description: PHP 8.2 msgpack development headers
    test:
      environment:
        contents:
          packages:
            - busybox
            - wolfi-base
      pipeline:
        - runs: |
            # Just make sure the expected define is in the expected file
            # location.
            grep PHP_MSGPACK_VERSION /usr/include/php/ext/msgpack/php_msgpack.h
```