From 9c1d109d1eb5f93db67ec82536f3fc5af9146966 Mon Sep 17 00:00:00 2001 From: Erika Heidi Date: Fri, 2 Aug 2024 14:40:08 +0200 Subject: [PATCH] Updating melange docs (#1735) This PR brings several updates to the melange docs. - Reference documentation was removed and rules were added to the `nginx.conf` file to redirect to respective doc pages on melange's GitHub repo - FAQ was updated - Overview was simplified - Getting Started guide was fully fixed and updated to use Wolfi. The demo repository was reactivated and updated, guide now follows the content from the repo. Whenever possible, I linked to the official repo. As of today, searching for "melange apk" still brings our Getting Started with melange guide as first result, so I wanted to make sure the guide works, uses Wolfi as reference, and links back to the repo in relevant places. All lastmod dates were updated. This PR addresses [this internal issue](https://github.com/chainguard-dev/internal/issues/4088). --- .../open-source/build-tools/melange/_index.md | 2 +- .../open-source/build-tools/melange/faq.md | 14 +- .../melange/getting-started-with-melange.md | 246 +++++------------- .../melange/melange-pipelines/_index.md | 14 - .../melange-pipelines/autoconf/configure.md | 40 --- .../autoconf/make-install.md | 36 --- .../melange-pipelines/autoconf/make.md | 37 --- .../melange/melange-pipelines/cmake/build.md | 37 --- .../melange-pipelines/cmake/configure.md | 38 --- .../melange-pipelines/cmake/install.md | 37 --- .../melange/melange-pipelines/fetch.md | 44 ---- .../melange/melange-pipelines/git-checkout.md | 42 --- .../melange/melange-pipelines/go/build.md | 41 --- .../melange/melange-pipelines/go/install.md | 41 --- .../melange-pipelines/meson/compile.md | 36 --- .../melange-pipelines/meson/configure.md | 37 --- .../melange-pipelines/meson/install.md | 36 --- .../melange/melange-pipelines/patch.md | 38 --- .../melange/melange-pipelines/ruby/build.md | 36 --- .../melange/melange-pipelines/ruby/clean.md | 31 --- .../melange/melange-pipelines/ruby/install.md | 37 --- .../melange/melange-pipelines/split/dev.md | 32 --- .../melange-pipelines/split/infodir.md | 32 --- .../melange-pipelines/split/locales.md | 32 --- .../melange-pipelines/split/manpages.md | 32 --- .../melange/melange-pipelines/split/static.md | 32 --- .../melange/melange-pipelines/strip.md | 33 --- .../build-tools/melange/overview/index.md | 18 +- .../build-tools/melange/reference.md | 122 --------- nginx.conf | 3 + 30 files changed, 80 insertions(+), 1176 deletions(-) delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/_index.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/autoconf/configure.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/autoconf/make-install.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/autoconf/make.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/cmake/build.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/cmake/configure.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/cmake/install.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/fetch.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/git-checkout.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/go/build.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/go/install.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/meson/compile.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/meson/configure.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/meson/install.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/patch.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/ruby/build.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/ruby/clean.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/ruby/install.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/split/dev.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/split/infodir.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/split/locales.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/split/manpages.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/split/static.md delete mode 100644 content/open-source/build-tools/melange/melange-pipelines/strip.md delete mode 100644 content/open-source/build-tools/melange/reference.md diff --git a/content/open-source/build-tools/melange/_index.md b/content/open-source/build-tools/melange/_index.md index 68cc681024..e7f764de16 100644 --- a/content/open-source/build-tools/melange/_index.md +++ b/content/open-source/build-tools/melange/_index.md @@ -6,7 +6,7 @@ description: "An apk builder tool" lead: "The declarative APK builder" type: "article" date: 2020-10-06T08:49:15+00:00 -lastmod: 2024-05-02T08:49:15+00:00 +lastmod: 2024-08-01T08:49:15+00:00 draft: false images: [] --- diff --git a/content/open-source/build-tools/melange/faq.md b/content/open-source/build-tools/melange/faq.md index ebb09fa8bd..112268d0ff 100644 --- a/content/open-source/build-tools/melange/faq.md +++ b/content/open-source/build-tools/melange/faq.md @@ -6,7 +6,7 @@ type: "article" lead: "Frequently asked questions about melange" description: "Frequently asked questions about melange" date: 2022-10-17T11:07:52+02:00 -lastmod: 2022-10-17T11:07:52+02:00 +lastmod: 2024-08-01T11:07:52+02:00 draft: false tags: ["melange", "FAQ"] images: [] @@ -18,25 +18,23 @@ toc: true --- ## Do I need to understand melange to use Chainguard Images? - No. Chainguard built [melange](https://github.com/chainguard-dev/melange) as part of its open source tooling used for the [Wolfi](/open-source/wolfi) operating system. While you can check out the [project on GitHub](https://github.com/chainguard-dev/melange) and learn more, it’s not a prerequisite for using or working with [Chainguard Images](/chainguard/chainguard-images). ## How are melange packages defined? -melange apks are defined declaratively using a YAML file. +melange apks are defined declaratively using a YAML file. This design feature allows for reproducible builds: run melange twice and you'll get exactly the same binary. -## Are melange apks compatible with Alpine? -Yes, melange apks are built to be compatible with apk-based systems including Alpine. +## Is melange compatible with Alpine? +Yes, melange is built to be compatible with apk-based systems including Alpine. ## Can I mix Alpine and Wolfi package repositories to create my melange build environment? -No, it's not possible to mix Alpine apks with Wolfi apks. If you have unmet dependencies, you'll need to build those first as separate packages. +No, it's not possible to mix Alpine apks with Wolfi apks. ## Is it mandatory to sign packages with a melange key? Signing packages is not mandatory, but it is a recommended practice, because it allows users and automated systems to verify that the package they downloaded was built by the same person who signed it, and that it hasn't been tampered with. ## What happens if I don't provide a key to sign my package(s)? -Some systems may prevent installation of your apk if they can't attest the package provenance. This is the case with apko, which by default will fail any builds that reference unsigned packages. +Some systems may prevent installation of your apk if they can't attest the package provenance. This is the case with [apko](https://github.com/chainguard-dev/apko), which by default will fail any builds that reference unsigned packages. ## Can I create custom pipelines and embed them into my main pipeline? Although melange supports inclusion of sub-pipelines, this feature currently only supports the built-in pipelines (such as `make`, `split` and others) that can be found at the [pkg/build/pipelines](https://github.com/chainguard-dev/melange/tree/main/pkg/build/pipelines) directory on the main project repository. -The ability to embed custom pipelines is on the roadmap, but it's not a priority at the moment. diff --git a/content/open-source/build-tools/melange/getting-started-with-melange.md b/content/open-source/build-tools/melange/getting-started-with-melange.md index 28829b5113..1d956aa48d 100644 --- a/content/open-source/build-tools/melange/getting-started-with-melange.md +++ b/content/open-source/build-tools/melange/getting-started-with-melange.md @@ -7,7 +7,7 @@ lead: "An apk builder tool" type: "article" description: "melange is a declarative apk builder" date: 2022-07-21T15:21:01+02:00 -lastmod: 2024-05-02T15:21:01+02:00 +lastmod: 2024-08-01T15:21:01+02:00 draft: false tags: ["melange", "Procedural"] images: [] @@ -19,17 +19,11 @@ toc: true # terminalImage: melange:latest --- -[melange](https://github.com/chainguard-dev/melange) is an [apk](https://wiki.alpinelinux.org/wiki/Package_management) builder tool that uses declarative pipelines to create apk packages. From a single YAML file, users are able to generate multi-architecture apks that can be injected directly into [apko](https://github.com/chainguard-dev/apko) builds, which renders apko and melange a [powerful combination for any container image factory](https://blog.chainguard.dev/secure-your-software-factory-with-melange-and-apko/). +[melange](https://github.com/chainguard-dev/melange) is an [apk](https://wiki.alpinelinux.org/wiki/Package_management) builder tool that uses declarative pipelines to create apk packages. From a single YAML file, users are able to generate multi-architecture apks that can be injected directly into [apko](https://github.com/chainguard-dev/apko) builds. -Understanding melange can help you better understand the [Wolfi](/open-source/wolfi) operating system and how [Chainguard Images](/chainguard/chainguard-images) are made to be minimal and secure, but it is not necessary to have a background in melange in order to use Chainguard Images. +Understanding melange can help you better understand the [Wolfi](/open-source/wolfi) operating system and how [Chainguard Images](/chainguard/chainguard-images) are made to be minimal and secure, but it is not necessary to have a background in melange in order to use Chainguard Images. -## Why melange - -Software supply chain threats have been growing exponentially in the last few years, according to [industry leaders and security researchers (PDF)](https://www.usenix.org/system/files/login/articles/login_winter20_17_geer.pdf). With the popularization of automated workflows and cloud native deployments, it is more important than ever to provide users with the ability to attest the provenance of all relevant software artifacts. - -Instead of building your application together with your components and system dependencies, you can build your application once and compose it into different architectures and distributions using melange, as if they were any other component of an image. - -In this guide, you'll learn how to build a software package with melange. To demonstrate the versatile combination of melange and apko builds, we'll package a small command-line PHP script and build a minimalist container image with the generated apk. All files used in this demo are open source and available at the [melange-php-demos](https://github.com/chainguard-dev/melange-php-demos/tree/main/hello-minicli) repository. +In this guide, you'll learn how to build a software package with melange. To demonstrate the versatile combination of melange and apko builds, we'll package a small command-line PHP script and build a minimalist container image based on Wolfi with the generated apk. All files used in this demo are open source and available at the [melange-php-demos](https://github.com/chainguard-dev/melange-php-demos/tree/main/hello-minicli) repository. ## Requirements @@ -39,7 +33,7 @@ You won't need PHP or Composer installed on your system, since we'll be using Do ### Note for Linux Users -In order to be able to build apks for multiple architectures using Docker, you'll need to register additional QEMU headers within your kernel. This is done automatically for Docker Desktop users, so if you are on macOS you don't need to run this additional step. +In order to be able to build apks for multiple architectures using Docker, you may need to register additional QEMU headers within your kernel. This is done automatically for Docker Desktop users, so if you are on macOS you don't need to run this additional step. Run the following command to register the necessary handlers within your kernel, using the [multiarch/qemu-user-static](https://github.com/multiarch/qemu-user-static) image. @@ -47,17 +41,17 @@ Run the following command to register the necessary handlers within your kernel, docker run --rm --privileged multiarch/qemu-user-static --reset -p yes ``` -You should now be able to build apks for all architectures that melange supports. +You should now be able to build apks for all architectures supported by melange. -## Step 1 — Downloading the melange Image +## 1 — Downloading the melange Image -The fastest way to get melange up and running on your system is by using the [official melange image](https://images.chainguard.dev/directory/image/melange/versions) with Docker. Start by pulling the official melange image into your local system: +The fastest way to get melange up and running on your system is by using the [official melange image](https://images.chainguard.dev/directory/image/melange/versions) with Docker. Start by pulling the melange image into your local system: ```shell docker pull cgr.dev/chainguard/melange:latest ``` -This will download the latest version of the distroless melange image, which is rebuilt every night for extra freshness. +This will download the latest version of the melange image, which is rebuilt every night for extra freshness. Check that you're able to run melange with `docker run`. @@ -75,122 +69,33 @@ You should get output similar to the following: |_| |_| |_____| |_____| /_/ \_\ |_| \_| \____| |_____| melange -GitVersion: v0.1.0-67-g108fd6a -GitCommit: 108fd6a5e400bd100ef6db813380de44516de6e6 +GitVersion: v0.11.1 +GitCommit: a52edcc075ebf1dc89aea87893e3821944171ee3 GitTreeState: clean -BuildDate: 2022-08-01T13:36:41 -GoVersion: go1.18.5 +BuildDate: '2024-07-19T16:04:17Z' +GoVersion: go1.22.5 Compiler: gc Platform: linux/amd64 -``` - -With melange installed, you’re ready to proceed. - -## Step 2 — Preparing the Demo App - -To demonstrate melange's features with a minimalist application that has real-world functionality, we'll create a PHP command line app that queries the [Slip advice](https://api.adviceslip.com/) API and outputs a random piece of advice. The app is a single-file script built with [Minicli](https://github.com/minicli). - -Create a folder in your home directory to place your demo files, then `cd` into it: - -```shell -mkdir ~/hello-minicli && cd $_ -``` - -Run the following command, which will use the official Composer image to generate a `composer.json` file and download `minicli/minicli`: - -```shell -docker run --rm -it -v "${PWD}":/app composer require minicli/minicli -``` - -Once you receive confirmation that the download was completed, we'll need a second dependency to query the advice slip API. Run the following command to include `minicli/curly`, a simple curl wrapper for Minicli: - -```shell -docker run --rm -it -v "${PWD}":/app composer require minicli/curly -``` - -Next, create a new file called `minicli` using your text editor of choice. This will be the executable we'll ship with our apk package. -```shell -nano minicli ``` -The following code will set up a new Minicli application and define a single command called `advice`. This will make a GET query to the advice slip API, check the return code, and print the resulting quote when the query is successful. - -Because our app will be built into an apk and later on embedded on a container image, we'll check for the right location of the vendor folder before requiring the `autoload.php` file. This file must be included before the application is instantiated. The `MINICLI_HOME` environment variable can be used to customize the vendor location, which is by default set to `/usr/share/minicli`. - -Place the following code in your `minicli` file: - -```php -#!/usr/bin/env php - - true -]); - -$app->setSignature('Usage: ./minicli advice'); - -$app->registerCommand('advice', function () use ($app) { - $client = new Client(); - - $response = $client->get('https://api.adviceslip.com/advice'); - if ($response['code'] !== 200) { - $app->getPrinter()->error('An API error has occurred.'); - return; - } - - $advice = json_decode($response['body'], true); - $app->getPrinter()->info($advice['slip']['advice']); -}); - -try { - $app->runCommand($argv); -} catch (CommandNotFoundException $notFoundException) { - $app->getPrinter()->error("Command Not Found."); - return 1; -} catch (Exception $exception) { - if ($app->config->debug) { - $app->getPrinter()->error("An error occurred:"); - $app->getPrinter()->error($exception->getMessage()); - } - return 1; -} - -return 0; +With melange installed, you’re ready to proceed. -``` +## 2 — Cloning the Demo Repository -Save and close the file when you're done. If you're using `nano`, you can do that by typing `CTRL+X`, then `Y` and `ENTER` to confirm. +To demonstrate melange's features with a minimalist application that has real-world functionality, our demo consists of a PHP command line app that queries the [Slip advice](https://api.adviceslip.com/) API and outputs a random piece of advice. The app is a single-file script built with [Minicli](https://github.com/minicli). -Set the script as executable with: +Start by cloning the demo repository to your local machine and navigating to the `melange-php-demos/hello-minicli` directory: ```shell -chmod +x minicli +git clone git@github.com:chainguard-dev/melange-php-demos.git +cd melange-php-demos/hello-minicli ``` -Now you can run the application to make sure it's functional. We'll also use Docker for that: +Now you can run the application to make sure it's functional. You can do that using Docker and Chainguard's PHP image: ```shell -docker run --rm -it -v "${PWD}":/app php:8.1-cli php /app/minicli advice +docker run --rm -it -v "${PWD}":/app cgr.dev/chainguard/php /app/minicli advice ``` You should get a random piece of advice such as: @@ -201,14 +106,8 @@ Gratitude is said to be the secret to happiness. With the application ready, you can start building your package. -## Step 3 — Creating the melange YAML File -The `melange.yaml` file is where you'll declare the details and specifications of your apk package. For code that generates self-contained binaries, this is typically where you'll build your application artifacts with compiler tools. In the case of interpreted languages, you'll likely build your application by downloading vendor dependencies, setting up relevant paths, and setting the environment up for production. - -Create a new file in your `hello-minicli` folder called `melange.yaml`: - -```shell -nano melange.yaml -``` +## 3 — The melange YAML File +The `melange.yaml` file is where you declare the details and specifications of your apk package. For code that generates self-contained binaries, this is typically where you'll build your application artifacts with compiler tools. In the case of interpreted languages, you'll likely build your application by downloading vendor dependencies, setting up relevant paths, and setting the environment up for production. The melange specification file contains three main sections: @@ -216,9 +115,9 @@ The melange specification file contains three main sections: - **environment**: defines how the environment should be prepared for the build, including required packages and their source repositories. Anything that is only required at build time goes here, and shouldn't be part of the runtime dependencies. - **pipeline**: defines the build pipeline for this package. -One of the best advantages of using melange is to be able to control all steps of your build pipeline, and include only what's absolutely necessary. This way, you'll be able to build smaller and more secure container images by removing unnecessary dependencies. +One of the best advantages of using melange is to be able to control all steps of your build pipeline, and include only what's necessary. This way, you'll be able to build smaller and more secure container images by removing unnecessary dependencies. -Place the following content in your `melange.yaml` file: +This is what the `melange.yaml` included in our demo looks like, for your reference: ```yaml package: @@ -228,29 +127,29 @@ package: target-architecture: - all copyright: - - license: Apache-2.0 - paths: - - "*" + - license: MIT dependencies: runtime: - - php81 - - php81-common - - php81-curl - - php81-openssl + - php + - php-curl environment: contents: + keyring: + - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub + - ./melange.rsa.pub repositories: - - https://dl-cdn.alpinelinux.org/alpine/edge/main - - https://dl-cdn.alpinelinux.org/alpine/edge/community + - https://packages.wolfi.dev/os packages: - - alpine-baselayout-data - ca-certificates-bundle + - busybox - curl - - php81 - - php81-common - - php81-curl - - php81-openssl + - git + - php + - php-phar + - php-iconv + - php-openssl + - php-curl - composer pipeline: @@ -266,15 +165,11 @@ pipeline: ``` -Save and close the file when you're done. - Our build pipeline will set up two distinct directories, separating the application dependencies from its executable entry point. The executable `minicli` script will be copied into `/usr/bin`, while the vendor files will be located at `/usr/share/minicli`. -## Step 4 — Building your apk +## 4 — Building the minicli apk with melange -First make sure you're at the `~/hello-minicli` directory. - -To get started, create a temporary keypair to sign your melange packages: +Before building the package, you'll need to create a temporary keypair to sign it. You can use the following command for that: ```shell docker run --rm -v "${PWD}":/work cgr.dev/chainguard/melange keygen @@ -282,9 +177,9 @@ docker run --rm -v "${PWD}":/work cgr.dev/chainguard/melange keygen This will generate a `melange.rsa` and `melange.rsa.pub` files in the current directory. ``` -2022/08/05 14:46:05 generating keypair with a 4096 bit prime, please wait... -2022/08/05 14:46:08 wrote private key to melange.rsa -2022/08/05 14:46:08 wrote public key to melange.rsa.pub +2024/08/01 16:55:31 INFO generating keypair with a 4096 bit prime, please wait... +2024/08/01 16:55:33 INFO wrote private key to melange.rsa +2024/08/01 16:55:33 INFO wrote public key to melange.rsa.pub ``` Next, build the apk defined in the `melange.yaml` file with the following command: @@ -292,57 +187,49 @@ Next, build the apk defined in the `melange.yaml` file with the following comman ```shell docker run --privileged --rm -v "${PWD}":/work \ cgr.dev/chainguard/melange build melange.yaml \ - --arch x86,amd64,aarch64,armv7 \ + --arch amd64,aarch64 \ --signing-key melange.rsa ``` -This will set up a volume sharing your current folder with the location `/work` inside the container. We'll build packages for `x86`, `amd64`, `aarch64`, and `armv7` platforms and sign them using the `melange.rsa` key. +This will set up a volume sharing your current folder with the location `/work` inside the container. We'll build packages for `amd64` and `aarch64` platforms and sign them using the `melange.rsa` key created in the previous command. When the build is finished, you should be able to find a `packages` folder containing the generated apks (and associated apk index files): ``` packages ├── aarch64 +│   ├── APKINDEX.json │   ├── APKINDEX.tar.gz -│ └── hello-minicli-0.1.0-r0.apk -├── armv7 -│   ├── APKINDEX.tar.gz -│ └── hello-minicli-0.1.0-r0.apk -├── x86 -│   ├── APKINDEX.tar.gz -│ └── hello-minicli-0.1.0-r0.apk +│   └── hello-minicli-0.1.0-r0.apk └── x86_64 -│   ├── APKINDEX.tar.gz + ├── APKINDEX.json + ├── APKINDEX.tar.gz └── hello-minicli-0.1.0-r0.apk -4 directories, 8 files +3 directories, 6 files ``` You have successfully built a multi-architecture software package with melange! -## Step 5 — Building a Container Image with apko +## 5 — Building a Container Image with apko With the apk packages and apk index in place, you can now build a container image and have your apk(s) installed within it. -Create a new file called `apko.yaml` in your `~/hello-minicli` directory: - -```shell -nano apko.yaml -``` - -The following apko specification will create a container image tailored to the application we built in the previous steps. Because we defined the PHP dependencies as runtime dependencies within the apk, you don't need to require these packages again here. The container entrypoint command will be set to `/usr/bin/minicli`, where the application executable is located. +The following `apko.yaml` file will create a container image tailored to the application we built in the previous steps. Because we defined the PHP dependencies as runtime dependencies within the apk, you don't need to require these packages again here. The container entrypoint command will be set to `/usr/bin/minicli`, where the application executable is located. One important thing to note is how we reference the `hello-minicli` apk as a local package within the `repositories` section of the YAML file. The `@local` notation tells apko to search for apks in the specified directory, in this case `/work/packages`. -Place the following text in your `apko.yaml` file: +This is what the `apko.yaml` file included in our demo looks like, for your reference: ```yaml contents: + keyring: + - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub + - ./melange.rsa.pub repositories: - - https://dl-cdn.alpinelinux.org/alpine/edge/main - - https://dl-cdn.alpinelinux.org/alpine/edge/community + - https://packages.wolfi.dev/os - '@local /work/packages' packages: - - alpine-baselayout-data + - wolfi-base - ca-certificates-bundle - hello-minicli@local accounts: @@ -357,22 +244,17 @@ entrypoint: command: /usr/bin/minicli advice ``` -Save and close the file when you're done. You are now ready to build your container image. - The following command will set up a volume sharing your current folder with the location `/work` in the apko container, running the `apko build` command to generate an image based on your `apko.yaml` definition file. ```shell docker run --rm --workdir /work -v ${PWD}:/work cgr.dev/chainguard/apko \ - build apko.yaml hello-minicli:test hello-minicli.tar \ - --arch host \ - -k melange.rsa.pub + build apko.yaml hello-minicli:test hello-minicli.tar --arch host ``` This will build an OCI image based on your host system's architecture (specified by the `--arch host` flag). If you receive warnings at this point, those are likely related to the types of SBOMs being uploaded and can be safely ignored. The command will generate a few new files in the app's directory: - `hello-minicli.tar` — the packaged OCI image that can be imported with a `docker load` command -- `sbom-%host-architecture%.cdx` — an SBOM file for your host architecture in `cdx` format - `sbom-%host-architecture%.spdx.json` — an SBOM file for your host architecture in `spdx-json` format Next, load your image within Docker: @@ -381,11 +263,11 @@ Next, load your image within Docker: docker load < hello-minicli.tar ``` ``` -10f951ac3cd2: Loading layer [==================================================>] 7.764MB/7.764MB +7cbaefdf1c30: Loading layer 13.7MB/13.7MB Loaded image: hello-minicli:test-%host-architecture% ``` -Note that the `%host-architecture%` will vary, and there may be multiple images loaded into your Docker daemon. Be sure to edit the variable in the following `docker run` command to match your target architecture. You can also click to edit it inline on this page. +Note that the `%host-architecture%` will vary, and there may be multiple images loaded into your Docker daemon. Be sure to edit the variable in the following `docker run` command to match your target architecture. Now you can run your Minicli program with: @@ -402,6 +284,6 @@ You have successfully built a minimalist container image with your apk package i ## Conclusion -In this guide, we built a demo command line application and packaged it with melange. We also built a container image to install and run our custom apk, using the apko tool. For more information about apko, check our [Getting Started with apko](/open-source/apko/getting-started-with-apko/) guide. +In this guide, we packaged a PHP command-line app with melange. We also built a container image to install and run our custom apk, using the apko tool. For more information about apko, check our [Getting Started with apko](/open-source/apko/getting-started-with-apko/) guide. -The demo files are available at the repository [melange-php-demos](https://github.com/chainguard-dev/melange-php-demos), in the `hello-minicli` subfolder. For more information on how to debug your builds, please refer to the demo's [README](https://github.com/chainguard-dev/melange-php-demos/tree/main/hello-minicli) file and check the official documentation for [melange](https://github.com/chainguard-dev/melange) and [apko](https://github.com/chainguard-dev/apko). +The demo files are available at the [melange-php-demos](https://github.com/chainguard-dev/melange-php-demos) repository, in the `hello-minicli` subfolder. For additional information on how to debug your builds and other features, check the [melange](https://github.com/chainguard-dev/melange) and [apko](https://github.com/chainguard-dev/apko) repositories on GitHub. diff --git a/content/open-source/build-tools/melange/melange-pipelines/_index.md b/content/open-source/build-tools/melange/melange-pipelines/_index.md deleted file mode 100644 index e61b8f40f1..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/_index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "melange Pipelines" -aliases: -- /open-source/melange/melange-pipelines/ -description: "Built-in melange pipelines reference" -lead: "The declarative APK builder" -type: "article" -date: 2022-11-28T08:49:15+00:00 -lastmod: 2022-11-28T08:49:15+00:00 -draft: false -images: [] ---- - -melange has several built-in pipelines to facilitate repeating common tasks. diff --git a/content/open-source/build-tools/melange/melange-pipelines/autoconf/configure.md b/content/open-source/build-tools/melange/melange-pipelines/autoconf/configure.md deleted file mode 100644 index c9387eb98b..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/autoconf/configure.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "autoconf/configure" -aliases: -- /open-source/melange/melange-pipelines/autoconf/configure -type: "article" -description: "Reference docs for the autoconf/configure melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Run the autoconf configure script - -### Dependencies -None - -### Reference -| Input | Description | -|-------|----------------------------------------------------------------------| -| `dir` | The directory containing the configure script. Default is set to `.` | - - -### Example -```yaml -- uses: autoconf/configure - with: - opts: | - PYTHON=/usr/bin/python3 \ - --with-lzma \ - --with-zlib - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/autoconf/make-install.md b/content/open-source/build-tools/melange/melange-pipelines/autoconf/make-install.md deleted file mode 100644 index f22e1f5e5f..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/autoconf/make-install.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "autoconf/make-install" -aliases: -- /open-source/melange/melange-pipelines/autoconf/make-install -type: "article" -description: "Reference docs for the autoconf/make-install melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Run autoconf make install - -### Dependencies -- make - - -### Reference -| Input | Description | -|-------|--------------------------------------------------------------| -| `dir` | The directory containing the Makefile. Default is set to `.` | - - -### Example -```yaml -- uses: autoconf/make-install - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/autoconf/make.md b/content/open-source/build-tools/melange/melange-pipelines/autoconf/make.md deleted file mode 100644 index e4482bf806..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/autoconf/make.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "autoconf/make" -aliases: -- /open-source/melange/melange-pipelines/autoconf/make -type: "article" -description: "Reference docs for the autoconf/make melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Run autoconf make - -### Dependencies -- make - - -### Reference -| Input | Description | -|--------|--------------------------------------------------------------| -| `dir` | The directory containing the Makefile. Default is set to `.` | -| `opts` | Options to pass to the make command. Default is set to `` | - - -### Example -```yaml -- uses: autoconf/make - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/cmake/build.md b/content/open-source/build-tools/melange/melange-pipelines/cmake/build.md deleted file mode 100644 index f3334d2b2a..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/cmake/build.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "cmake/build" -aliases: -- /open-source/melange/melange-pipelines/cmake/build -type: "article" -description: "Reference docs for the cmake/build melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Build a CMake project - -### Dependencies -- cmake -- ninja - - -### Reference -| Input | Description | -|--------------|----------------------------------------------------------------------| -| `output-dir` | The output directory for the CMake build. Default is set to `output` | - - -### Example -```yaml -uses: cmake/build - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/cmake/configure.md b/content/open-source/build-tools/melange/melange-pipelines/cmake/configure.md deleted file mode 100644 index 7e44f2f2e3..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/cmake/configure.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "cmake/configure" -aliases: -- /open-source/melange/melange-pipelines/cmake/configure -type: "article" -description: "Reference docs for the cmake/configure melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Configure a CMake project - -### Dependencies -- cmake -- ninja - - -### Reference -| Input | Description | -|--------------|----------------------------------------------------------------------| -| `output-dir` | The output directory for the CMake build. Default is set to `output` | -| `opts` | Compile options for the CMake build. | - - -### Example -```yaml -uses: cmake/configure - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/cmake/install.md b/content/open-source/build-tools/melange/melange-pipelines/cmake/install.md deleted file mode 100644 index 183a68ba70..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/cmake/install.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "cmake/install" -aliases: -- /open-source/melange/melange-pipelines/cmake/install -type: "article" -description: "Reference docs for the cmake/install melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Build a CMake project - -### Dependencies -- cmake -- ninja - - -### Reference -| Input | Description | -|--------------|----------------------------------------------------------------------| -| `output-dir` | The output directory for the CMake build. Default is set to `output` | - - -### Example -```yaml -uses: cmake/install - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/fetch.md b/content/open-source/build-tools/melange/melange-pipelines/fetch.md deleted file mode 100644 index ba2f2270fe..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/fetch.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "fetch" -aliases: -- /open-source/melange/melange-pipelines/fetch -type: "article" -description: "Reference docs for the fetch melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Fetch and extract external object into workspace - -### Dependencies -- wget - - -### Reference -| Input | Description | -|--------------------|------------------------------------------------------------------------------------------| -| `strip-components` | The number of path components to strip while extracting. Default is set to `1` | -| `extract` | Whether to extract the downloaded artifact as a source tarball. Default is set to `true` | -| `expected-sha256` | The expected SHA256 of the downloaded artifact. | -| `expected-sha512` | The expected SHA512 of the downloaded artifact. | -| `uri`* | The URI to fetch as an artifact. | - - -### Example -```yaml -pipeline: - - uses: fetch - with: - uri: https://www.php.net/distributions/php-${{package.version}}.tar.gz - expected-sha256: 3660e8408321149f5d382bb8eeb9ea7b12ea8dd7ea66069da33f6f7383750ab2 - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/git-checkout.md b/content/open-source/build-tools/melange/melange-pipelines/git-checkout.md deleted file mode 100644 index bee4710655..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/git-checkout.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "git-checkout" -aliases: -- /open-source/melange/melange-pipelines/git-checkout -type: "article" -description: "Reference docs for the git-checkout melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Check out sources from git - -### Dependencies -- git - - -### Reference -| Input | Description | -|---------------|-------------------------------------------------------------| -| `repository`* | The repository to check out sources from. | -| `destination` | The path to check out the sources to. Default is set to `.` | -| `depth` | The depth to use when cloning. Default is set to `50` | -| `branch` | The branch to check out, otherwise HEAD is checked out. | - - -### Example -```yaml -- uses: git-checkout - with: - repository: https://github.com/envoyproxy/envoy - branch: v${{package.version}} - destination: envoy -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/go/build.md b/content/open-source/build-tools/melange/melange-pipelines/go/build.md deleted file mode 100644 index bb773b8f72..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/go/build.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "go/build" -aliases: -- /open-source/melange/melange-pipelines/go/build -type: "article" -description: "Reference docs for the go/build melange pipeline" -date: 2023-04-06T11:07:52+02:0 -lastmod: 2023-04-06T11:07:52+02:0 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Run a build using the go compiler - -### Dependencies -- go -- busybox -- ca-certificates-bundle - - -### Reference -| Input | Description | -|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `packages`* | List of space-separated packages to compile. Files con also be specified.This value is passed as an argument to go build. All paths are relativeto inputs.modroot. | -| `tags` | A comma-separated list of build tags to pass to the go compiler | -| `output`* | Filename to use when writing the binary. The final install location inside the apk will be in prefix / install-dir / output | -| `modroot` | Top directory of the go module, this is where go.mod lives. Before buidingthe go pipeline wil cd into this directory. Default is set to `.` | -| `prefix` | Prefix to relocate binaries Default is set to `usr` | -| `ldflags` | List of [pattern=]arg to pass to the go compiler with -ldflags | -| `install-dir` | Directory where binaries will be installed Default is set to `bin` | - - -### Example -There are no examples available. diff --git a/content/open-source/build-tools/melange/melange-pipelines/go/install.md b/content/open-source/build-tools/melange/melange-pipelines/go/install.md deleted file mode 100644 index 38f22b31a4..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/go/install.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "go/install" -aliases: -- /open-source/melange/melange-pipelines/go/install -type: "article" -description: "Reference docs for the go/install melange pipeline" -date: 2023-04-06T11:07:52+02:00 -lastmod: 2023-04-06T11:07:52+02:0 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Run a build using the go compiler - -### Dependencies -- go -- busybox -- ca-certificates-bundle -- git - - -### Reference -| Input | Description | -|---------------|-------------------------------------------------------------------------------------------------------------------| -| `package`* | Import path to the package | -| `version` | Package version to install. This can be a version tag (v1.0.0), a commit hash or another ref (eg latest or HEAD). | -| `prefix` | Prefix to relocate binaries Default is set to `usr` | -| `install-dir` | Directory where binaries will be installed Default is set to `bin` | -| `ldflags` | List of [pattern=]arg to pass to the go compiler with -ldflags | -| `tags` | A comma-separated list of build tags to pass to the go compiler | - - -### Example -There are no examples available. diff --git a/content/open-source/build-tools/melange/melange-pipelines/meson/compile.md b/content/open-source/build-tools/melange/melange-pipelines/meson/compile.md deleted file mode 100644 index 5a2b58183e..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/meson/compile.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "meson/compile" -aliases: -- /open-source/melange/melange-pipelines/meson/compile -type: "article" -description: "Reference docs for the meson/compile melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Compile project with meson - -### Dependencies -- meson - - -### Reference -| Input | Description | -|--------------|----------------------------------------------------------------------| -| `output-dir` | The output directory for the Meson build. Default is set to `output` | - - -### Example -```yaml -uses: meson/compile - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/meson/configure.md b/content/open-source/build-tools/melange/melange-pipelines/meson/configure.md deleted file mode 100644 index 7395c5f9bb..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/meson/configure.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "meson/configure" -aliases: -- /open-source/melange/melange-pipelines/meson/configure -type: "article" -description: "Reference docs for the meson/configure melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Configure project with meson - -### Dependencies -- meson - - -### Reference -| Input | Description | -|--------------|----------------------------------------------------------------------| -| `output-dir` | The output directory for the Meson build. Default is set to `output` | -| `opts` | Compile options for the Meson build. | - - -### Example -```yaml -uses: meson/configure - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/meson/install.md b/content/open-source/build-tools/melange/melange-pipelines/meson/install.md deleted file mode 100644 index 98e40573a5..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/meson/install.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "meson/install" -aliases: -- /open-source/melange/melange-pipelines/meson/install -type: "article" -description: "Reference docs for the meson/install melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Install project with meson - -### Dependencies -- meson - - -### Reference -| Input | Description | -|--------------|----------------------------------------------------------------------| -| `output-dir` | The output directory for the Meson build. Default is set to `output` | - - -### Example -```yaml -uses: meson/install - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/patch.md b/content/open-source/build-tools/melange/melange-pipelines/patch.md deleted file mode 100644 index 82118850a3..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/patch.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "patch" -aliases: -- /open-source/melange/melange-pipelines/patch -type: "article" -description: "Reference docs for the patch melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Apply patches - -### Dependencies -- patch - - -### Reference -| Input | Description | -|--------------------|--------------------------------------------------------------------------------| -| `strip-components` | The number of path components to strip while extracting. Default is set to `1` | -| `patches`* | A list of patches to apply, as a whitespace delimited string. | - - -### Example -```yaml -- uses: patch - with: - patches: libtool-fix-cross-compile.patch -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/ruby/build.md b/content/open-source/build-tools/melange/melange-pipelines/ruby/build.md deleted file mode 100644 index 56aa18ef53..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/ruby/build.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "ruby/build" -aliases: -- /open-source/melange/melange-pipelines/ruby/build -type: "article" -description: "Reference docs for the ruby/build melange pipeline" -date: 2023-04-06T11:07:52+02:0 -lastmod: 2023-04-06T11:07:52+02:0 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Build a ruby gem - -### Dependencies -- busybox -- ca-certificates-bundle - - -### Reference -| Input | Description | -|----------|------------------------------| -| `gem`* | Gem name | -| `output` | Gem output filename | -| `opts` | Options to pass to gem build | - - -### Example -There are no examples available. diff --git a/content/open-source/build-tools/melange/melange-pipelines/ruby/clean.md b/content/open-source/build-tools/melange/melange-pipelines/ruby/clean.md deleted file mode 100644 index 1d804b0a9c..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/ruby/clean.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "ruby/clean" -aliases: -- /open-source/melange/melange-pipelines/ruby/clean -type: "article" -description: "Reference docs for the ruby/clean melange pipeline" -date: 2023-04-06T11:07:52+02:0 -lastmod: 2023-04-06T11:07:52+02:0 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Clean a ruby gem - -### Dependencies -- busybox -- ca-certificates-bundle - - -### Reference -This pipeline doesn't expect any input arguments. - -### Example -There are no examples available. diff --git a/content/open-source/build-tools/melange/melange-pipelines/ruby/install.md b/content/open-source/build-tools/melange/melange-pipelines/ruby/install.md deleted file mode 100644 index 9ed3ed6021..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/ruby/install.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "ruby/install" -aliases: -- /open-source/melange/melange-pipelines/autoconf/configure -type: "article" -description: "Reference docs for the ruby/install melange pipeline" -date: 2023-04-06T11:07:52+02:0 -lastmod: 2023-04-06T11:07:52+02:0 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Install a ruby gem - -### Dependencies -- busybox -- ca-certificates-bundle - - -### Reference -| Input | Description | -|------------|-----------------------------------------------------------------| -| `gem` | Gem name | -| `gem-file` | The full filename of the gem to build | -| `version`* | Gem version to install. This can be a version tag (1.0.0) | -| `opts` | Options to pass to the gem install command Default is set to `` | - - -### Example -There are no examples available. diff --git a/content/open-source/build-tools/melange/melange-pipelines/split/dev.md b/content/open-source/build-tools/melange/melange-pipelines/split/dev.md deleted file mode 100644 index 569da1fa31..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/split/dev.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "split/dev" -aliases: -- /open-source/melange/melange-pipelines/split/dev -type: "article" -description: "Reference docs for the split/dev melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Split development files - -### Dependencies -None - -### Reference -This pipeline doesn't expect any input arguments. - -### Example -```yaml -uses: split/dev - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/split/infodir.md b/content/open-source/build-tools/melange/melange-pipelines/split/infodir.md deleted file mode 100644 index f61fc7e3cc..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/split/infodir.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "split/infodir" -aliases: -- /open-source/melange/melange-pipelines/split/infodir -type: "article" -description: "Reference docs for the split/infodir melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Split GNU info pages - -### Dependencies -None - -### Reference -This pipeline doesn't expect any input arguments. - -### Example -```yaml -uses: split/infodir - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/split/locales.md b/content/open-source/build-tools/melange/melange-pipelines/split/locales.md deleted file mode 100644 index 510a70abc7..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/split/locales.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "split/locales" -aliases: -- /open-source/melange/melange-pipelines/split/locales -type: "article" -description: "Reference docs for the split/locales melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Split locales - -### Dependencies -None - -### Reference -This pipeline doesn't expect any input arguments. - -### Example -```yaml -uses: split/locales - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/split/manpages.md b/content/open-source/build-tools/melange/melange-pipelines/split/manpages.md deleted file mode 100644 index a86c7755cd..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/split/manpages.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "split/manpages" -aliases: -- /open-source/melange/melange-pipelines/split/manpages -type: "article" -description: "Reference docs for the split/manpages melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Split manpages - -### Dependencies -None - -### Reference -This pipeline doesn't expect any input arguments. - -### Example -```yaml -uses: split/manpages - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/split/static.md b/content/open-source/build-tools/melange/melange-pipelines/split/static.md deleted file mode 100644 index bde312fdf1..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/split/static.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "split/static" -aliases: -- /open-source/melange/melange-pipelines/split/static -type: "article" -description: "Reference docs for the split/static melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Split static library files - -### Dependencies -None - -### Reference -This pipeline doesn't expect any input arguments. - -### Example -```yaml -uses: split/static - -``` diff --git a/content/open-source/build-tools/melange/melange-pipelines/strip.md b/content/open-source/build-tools/melange/melange-pipelines/strip.md deleted file mode 100644 index 15ab8292a7..0000000000 --- a/content/open-source/build-tools/melange/melange-pipelines/strip.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "strip" -aliases: -- /open-source/melange/melange-pipelines/strip -type: "article" -description: "Reference docs for the strip melange pipeline" -date: 2022-11-01T11:07:52+02:00 -lastmod: 2022-11-01T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 600 -toc: true ---- - - -Strip binaries - -### Dependencies -- binutils -- scanelf - - -### Reference -This pipeline doesn't expect any input arguments. - -### Example -```yaml -uses: strip -``` diff --git a/content/open-source/build-tools/melange/overview/index.md b/content/open-source/build-tools/melange/overview/index.md index 732380ed32..928cc3680b 100644 --- a/content/open-source/build-tools/melange/overview/index.md +++ b/content/open-source/build-tools/melange/overview/index.md @@ -5,7 +5,7 @@ aliases: type: "article" description: "melange Overview" date: 2022-10-17T11:07:52+02:00 -lastmod: 2024-05-02T11:07:52+02:00 +lastmod: 2024-08-01T11:07:52+02:00 draft: false tags: ["melange", "Overview"] images: [] @@ -15,18 +15,12 @@ menu: weight: 10 toc: true --- -[melange](https://github.com/chainguard-dev/melange) is an [apk](https://wiki.alpinelinux.org/wiki/Package_management) builder tool that uses declarative pipelines to create apk packages. It is part of the open source tooling used for [Wolfi](/open-source/wolfi), which is the operating system used to power [Chainguard Images](/chainguard/chainguard-images). +[melange](https://github.com/chainguard-dev/melange) is an [apk](https://wiki.alpinelinux.org/wiki/Package_management) builder tool that uses declarative pipelines to create apk packages. It is part of the open source tooling used for [Wolfi](/open-source/wolfi), which is the operating system used to power [Chainguard Images](/chainguard/chainguard-images). -From a single YAML file, users are able to generate multi-architecture apks that can be injected directly into [apko](https://github.com/chainguard-dev/apko) builds. This renders apko and melange a [good combination for container image factories](https://blog.chainguard.dev/secure-your-software-factory-with-melange-and-apko/). +From a single YAML file, users are able to generate multi-architecture apks that can be injected directly into [apko](https://github.com/chainguard-dev/apko) builds. -The following diagram contains an overview of the apko and melange ecosystem and how they work together to compose apk-based images, using either Alpine or Wolfi as base system. +The following diagram contains an overview of the apko and melange ecosystem and how they work together to compose apk-based images, using either Wolfi or Alpine as base system. -![The diagram shows an overview of the apko and melange ecosystem and their relationships. melange apks can be used to compose both Alpine-based and Wolfi-based container images using apko.](apko_melange_ecosystem.png) +![The diagram shows an overview of the apko and melange ecosystem and their relationships. melange apks can be used to compose both Wolfi-based and Alpine-based container images using apko.](apko_melange_ecosystem.png) -melange offers the following features: - -- **Fully reproducible by default.** Run melange twice and you will get exactly the same binary. -- **Pipeline-oriented builds.** Every step of the build pipeline is defined and controlled by you, unlike traditional package managers which have distinct phases. -- **Multi-architecture by default.** QEMU is used to emulate various architectures, avoiding the need for cross-compilation steps. - -apko and [melange](/open-source/melange) are part of the open source toolkit developed by Chainguard to build [Wolfi](/open-source/wolfi) and [Chainguard Images](/chainguard/chainguard-images). +For more information and up-to-date examples on how to use melange, please refer to the [melange repository on GitHub](http://github.com/chainguard-dev/melange). diff --git a/content/open-source/build-tools/melange/reference.md b/content/open-source/build-tools/melange/reference.md deleted file mode 100644 index 8b5ee630a2..0000000000 --- a/content/open-source/build-tools/melange/reference.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: "melange YAML Reference" -aliases: -- /open-source/melange/reference -type: "article" -description: "A reference guide for writing YAML for melange" -date: 2022-10-17T11:07:52+02:00 -lastmod: 2022-10-17T11:07:52+02:00 -draft: false -tags: ["melange", "Reference"] -images: [] -menu: - docs: - parent: "melange" -weight: 150 -toc: true ---- - -This page provides a reference for melange's YAML specification. - -## package -This section defines metadata about the apk package being built. - - -| Directive | Expects | -|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------| -| `name` | (String) Name of the package. | -| `version` | (String) Version of the package. | -| `epoch` | (String) Useful to force the package to be seen as newer than any previous version with a lower epoch. | -| `description` | (String) A description of the package. | -| `target-architecture` | (Array) Architectures for which the package will be built. Use 'all' for all available architectures. | -| `copyright` | (Array) License and copyright information. | -| `dependencies` | (Array) List of runtime dependencies for this package. These will get pulled via apk as system dependencies when the package is installed. | - -#### Example - -```yaml -package: - name: hello - version: 2.12 - epoch: 0 - description: 'the GNU hello world program' - target-architecture: - - all - copyright: - - paths: - - '*' - 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 -This section defines the build environment, specifying dependencies that need to be present at build time. - -| Directive | Expects | -|------------|----------------------------------------------------------------------------------------------------------------------------------| -| `contents` | (Array) Defines the packages that will be installed for running the build pipeline, and the repositories where to download them. | - -#### Example - -```yaml -environment: - contents: - repositories: - - 'https://dl-cdn.alpinelinux.org/alpine/edge/main' - packages: - - alpine-baselayout-data - - busybox - - build-base - - scanelf - - ssl_client - - ca-certificates-bundle - -``` -_NOTE: do not mix Alpine apk repositories with Wolfi apk repositories when defining your software sources._ - -## pipeline -Defines the build steps. - -| Directive | Expects | -|-----------|---------------------------------------------------| -| `uses` | (String) Uses a built-in pipeline. | -| `with` | (Array) Provide parameters to a "uses" directive. | - -#### Example - -```yaml -- 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 -Creates subpackages for documentation and additional (dev) headers, which may not be necessary at runtime. - - -| Directive | Expects | -|------------|----------| -| `name` | (String) | -| `pipeline` | (Array) | - - -#### Example - -```yaml -subpackages: - - name: hello-doc - pipeline: - - uses: split/manpages - -``` diff --git a/nginx.conf b/nginx.conf index a1c0928e4e..590f2b5d28 100644 --- a/nginx.conf +++ b/nginx.conf @@ -79,6 +79,9 @@ http { "~^/chainguard/chainguard-images/reference/?$" https://images.chainguard.dev/directory; # apko reference redirect "~^/open-source/build-tools/apko/reference/?$" https://github.com/chainguard-dev/apko/blob/main/docs/apko_file.md; + # melange reference redirect + "~^/open-source/build-tools/melange/reference/?$" https://github.com/chainguard-dev/melange/blob/main/docs/md/melange.md; + "~^/open-source/build-tools/melange/melange-pipelines/?$" https://github.com/chainguard-dev/melange/blob/main/docs/PIPELINES.md; } server {