native-packages 0.6.0 → 0.7.0

data/docs/_guides/distribution-recipes.md

@@ -0,0 +1,192 @@
+---
+title: Distribution recipes
+description: Generate AUR and Homebrew recipes with release checksums, review downstream changes, and publish repository updates.
+nav_order: 7
+---
+
+# Distribution recipes
+
+A distribution recipe tells a package manager where to get your app and how
+to install or build it. Examples include an AUR `PKGBUILD`, a Homebrew formula
+or cask, and a Gentoo ebuild.
+
+native-packages fills in versions, download URLs, and checksums in templates
+you keep with the app. It can then stage those files in a downstream Git
+repository for review and publication.
+
+This guide uses an AUR package as an example. The same asset and template
+settings work for other recipe formats.
+
+## 1. Declare the release asset
+
+Add an asset for the archive your recipe downloads:
+
+```yaml
+release:
+  repository: your-name/hello
+assets:
+  AMD64:
+    file: hello_@VERSION@_linux_amd64.tar.gz
+    local: dist/hello_@VERSION@_linux_amd64.tar.gz
+```
+
+For local builds, native-packages hashes `local`. In release mode, it downloads
+`file` from the configured release and verifies its entry in `checksums.txt`.
+An explicit `url` can point elsewhere.
+
+Each asset provides three values for templates: `@AMD64_FILE@`,
+`@AMD64_URL@`, and `@AMD64_SHA256@`. Use uppercase names such as `AMD64`
+or `MACOS` for asset keys.
+
+## 2. Write a template
+
+Create `packaging/arch/hello-bin/PKGBUILD.in`:
+
+```sh
+pkgname=hello-bin
+pkgver=@VERSION@
+pkgrel=@PKGREL@
+pkgdesc='A small greeting application'
+arch=('x86_64')
+url='@UPSTREAM@'
+license=('MIT')
+depends=('glibc')
+provides=('hello')
+conflicts=('hello')
+source=('@AMD64_URL@')
+sha256sums=('@AMD64_SHA256@')
+
+package() {
+  install -Dm755 hello "$pkgdir/usr/bin/hello"
+  install -Dm644 LICENSE "$pkgdir/usr/share/licenses/hello/LICENSE"
+}
+```
+
+This example expects the archive to contain `hello` and `LICENSE` at its root.
+Use dependencies and metadata appropriate to your actual app.
+
+Map the generated path to the template in `native-packages.yaml`:
+
+```yaml
+templates:
+  arch/hello-bin/PKGBUILD: packaging/arch/hello-bin/PKGBUILD.in
+```
+
+The left side is a path under the build's `recipes/` directory. The right side
+is a source path relative to your configuration.
+
+For paths matching `arch/<package>/PKGBUILD`, native-packages also generates
+`.SRCINFO`, the package metadata used by AUR. This needs `makepkg` or working
+Docker. Recipe archives need `tar` and `xz`.
+
+## 3. Generate and test the recipe
+
+Build with your existing package targets and the new settings:
+
+```sh
+native-packages build --version 1.2.3 --output dist/with-recipes
+```
+
+Look in `dist/with-recipes/recipes/arch/hello-bin/` for `PKGBUILD` and `.SRCINFO`.
+Review the rendered URLs, version, checksum, dependencies, and installation
+paths. Test the recipe with the destination's normal tooling on a suitable
+machine before publishing it.
+
+A project that only generates recipes can use `targets: {}`. It still needs
+`schema`, `tool`, `nfpm.name`, and the asset/template configuration.
+
+## 4. Configure a destination
+
+Add the existing downstream repository under `repositories`:
+
+```yaml
+repositories:
+  aur-bin:
+    group: aur
+    url: https://aur.archlinux.org/hello-bin.git
+    push_url: ssh://aur@aur.archlinux.org/hello-bin.git
+    branch: master
+    package_path: .
+    files:
+      arch/hello-bin/PKGBUILD: PKGBUILD
+      arch/hello-bin/.SRCINFO: .SRCINFO
+    version_file: PKGBUILD
+    version_pattern: '^pkgver=(\S+)'
+    publish: push
+```
+
+Use your actual package repository and configure credentials for it. `files`
+maps generated paths under `recipes/` to paths in the downstream repository.
+`version_pattern` extracts the existing version so the tool can detect updates
+and downgrades.
+
+The `group` lets you operate on related destinations together. For example,
+`aur` can select both a binary package and a source package.
+
+## 5. Stage, review, and publish
+
+```sh
+native-packages repositories
+native-packages stage aur dist/with-recipes/recipes
+native-packages diff aur
+native-packages publish aur
+```
+
+`stage` prepares the update in an independent checkout under
+`.cache/packaging/repos/`. `diff` shows what will change. `publish` commits and
+pushes the staged update. Add `.cache/` to your application's `.gitignore`.
+
+Each destination has its own checkout. Your app needs no Git submodules or
+additional remotes. Updates touch the mapped package paths and preserve other
+files; Gentoo updates also preserve older ebuilds and Manifest entries.
+
+Check downstream state with:
+
+```sh
+native-packages status
+native-packages status aur --offline --json
+```
+
+The offline form uses cached information. Normal status checks query upstream
+repositories and open requests.
+
+## Homebrew formulae and casks
+
+Keep a formula or cask template in your app, then map it through `templates`
+and `repositories.files` just like the AUR example. A tap you own typically
+uses `publish: push` and a destination named `homebrew`.
+
+Use a formula for the appropriate command-line package or a cask for a native
+app download. Your template owns the package manager's installation logic.
+If a cask refers to a DMG created by this release, use
+[deferred recipe generation](multi-platform.md#generate-recipes-after-packages-are-built)
+so its checksum comes from the completed, signed image.
+
+## Submit a pull request or merge request
+
+Use `publish: github-pr` or `publish: gitlab-mr` for a repository that accepts
+contributions through review. Create the fork first and supply its URLs and
+submission settings. The [repository reference](../_reference/configuration.md#repositories)
+lists these fields.
+
+Staging writes a starting description to `.cache/packaging/submissions/` and
+prints its path. Edit it to describe the update and the checks you ran, then
+publish that destination by name:
+
+```sh
+native-packages diff community
+native-packages publish community --body-file .cache/packaging/submissions/community.md
+```
+
+The tool can reuse an existing open request. Successful submission means the
+request exists; the upstream project still reviews and accepts it.
+
+Use `publish: manual` with `notes` for destinations that need an external
+process. The CLI reports those instructions rather than submitting an update.
+
+## Next steps
+
+Once the process is tested, enable destination publication in
+[GitHub Actions](github-actions.md#enable-aur-or-homebrew-publication).
+For package files themselves, use [Publishing a release](publishing.md).
+This tool does not host APT or DNF package indexes.

data/docs/_guides/getting-started.md

@@ -0,0 +1,184 @@
+---
+title: Getting started
+description: Install native-packages and build a DEB and RPM from a compiled Linux application.
+nav_order: 1
+---
+
+# Getting started
+
+By the end of this guide, you will have a DEB and an RPM containing your app,
+ready to test on Linux.
+
+We will package an application called `hello`. You can follow along with your
+own compiled executable, or build the tiny example below.
+
+## 1. Install the tools
+
+You need Ruby 3.2 or later. Install the version used by these guides:
+
+```sh
+gem install native-packages --version 0.7.0
+```
+
+For Linux packages, install **nFPM 2.47.0**, the helper native-packages uses to
+write package files. Download the matching build from the
+[nFPM release](https://github.com/goreleaser/nfpm/releases/tag/v2.47.0)
+and put `nfpm` on your `PATH`. If you already use Go, you can install it with:
+
+```sh
+go install github.com/goreleaser/nfpm/v2/cmd/nfpm@v2.47.0
+export PATH="$(go env GOPATH)/bin:$PATH"
+```
+
+You also need `readelf` to inspect Linux binaries and `bsdtar` to unpack
+archives. On Debian or Ubuntu:
+
+```sh
+sudo apt-get install binutils libarchive-tools
+```
+
+Other distributions provide these through their binutils and libarchive
+packages. The [reusable GitHub Actions workflow](github-actions.md) installs
+the packaging tools for you.
+
+## 2. Prepare your application
+
+Start in your application's root directory. This example expects a Linux
+x86-64 executable at `dist/hello`, built against glibc.
+
+If you have a C compiler on an x86-64 Linux system using glibc, you can create
+a sample in a new directory:
+
+```sh
+mkdir hello-packaging
+cd hello-packaging
+mkdir dist
+cat > hello.c <<'C'
+#include <stdio.h>
+int main(void) {
+  puts("Hello from a native package!");
+  return 0;
+}
+C
+cc -o dist/hello hello.c
+```
+
+For your own app, run its usual build command instead and note where it puts
+the executable. Packaging starts from those built files.
+
+## 3. Create a configuration
+
+Generate a starting point:
+
+```sh
+native-packages init --name hello --formats deb,rpm
+```
+
+Open the generated `native-packages.yaml` and replace its contents with:
+
+```yaml
+schema: 1
+tool:
+  version: '0.7.0'
+  nfpm: '2.47.0'
+
+nfpm:
+  name: hello
+  description: A small greeting application
+  maintainer: Your Name <you@example.com>
+  license: MIT
+  contents:
+    - src: '@PAYLOAD@/hello'
+      dst: /usr/bin/hello
+      file_info:
+        mode: 0755
+
+targets:
+  linux-amd64:
+    platform: linux
+    arch: amd64
+    libc: glibc
+    formats: [deb, rpm]
+    input:
+      kind: file
+      local: dist/hello
+```
+
+Use your own maintainer details and your app's actual license. There are three
+parts to understand:
+
+- **`tool`** selects the tool versions, so everyone builds with the same setup.
+- **`nfpm`** describes the package: its name, metadata, and installed files.
+  `src` is the file to include; `dst` is where it will be installed.
+- **`targets`** describes the build inputs and output formats. `amd64` means
+  x86-64, and `glibc` is the C library used by this example's executable.
+
+`@PAYLOAD@` is a temporary copy of your input. Here, it contains `hello`.
+The destination `/usr/bin/hello` is inside the package; building does not
+install it on your machine.
+
+The default generated configuration expects an archive. We set `kind: file`
+because this example supplies one executable. For ARM64, use `arch: arm64`
+and an ARM64 build of your app. See [input types and targets](building-packages.md).
+
+## 4. Check and build
+
+Check the configuration and tools:
+
+```sh
+native-packages doctor
+```
+
+If anything is missing, the command reports what to fix. Once it succeeds,
+build version 1.2.3:
+
+```sh
+native-packages build --version 1.2.3
+```
+
+The command checks your executable's architecture and linked libraries, then
+creates both packages. You should see:
+
+```text
+dist/packages/1.2.3/
+  packages/
+    linux-amd64/
+      deb/                 # your .deb file
+      rpm/                 # your .rpm file
+  recipes/
+    release.json
+  build.json
+  packaging-checksums.txt
+```
+
+`build.json` records the inputs, outputs, and checks performed.
+`packaging-checksums.txt` lists file hashes so changes can be detected.
+Keep the whole directory if you plan to publish the build later.
+
+To try again after changing your app or configuration, choose a new output
+directory:
+
+```sh
+native-packages build --version 1.2.3 --output dist/second-build
+```
+
+## 5. Test the package
+
+On a disposable Debian or Ubuntu machine, copy the DEB there and install it:
+
+```sh
+sudo apt install ./hello_1.2.3_amd64.deb
+hello
+sudo apt remove hello
+```
+
+Use the filename produced by your build. For the sample, `hello` prints
+`Hello from a native package!`. For your own app, also test startup, upgrades,
+and removal on each distribution you support. A successful package build
+checks the files; installation testing checks how the app behaves.
+
+## Where to go next
+
+Continue with [Building packages](building-packages.md) to add icons,
+configuration files, dependencies, and more architectures. When your package
+is ready, follow [Publishing a release](publishing.md).

data/docs/_guides/github-actions.md

@@ -0,0 +1,146 @@
+---
+title: GitHub Actions
+description: Add package building and optional publication to your application's GitHub Actions workflow.
+nav_order: 4
+---
+
+# GitHub Actions
+
+The reusable workflow installs the tools, builds your packages, and saves the
+result as an Actions artifact. It can also upload packages to an existing
+GitHub release.
+
+Before adding it, commit `native-packages.yaml` and check that you can
+[build locally](getting-started.md).
+
+## Package an existing release
+
+Add this job under `jobs` in your application's release workflow. In this
+example, the existing `release` job uploads the application's binary archives
+and `checksums.txt` to a release matching the Git tag.
+
+```yaml
+packaging:
+  needs: release
+  permissions:
+    contents: write
+  uses: crmne/native-packages/.github/workflows/package.yml@v0.7.0
+  with:
+    version: ${{ github.ref_name }}
+    publish: true
+  secrets: inherit
+```
+
+Set `needs` to your actual release job's name. Use this example in a tag-based
+release workflow, where `github.ref_name` is a version such as `v1.2.3`.
+For other triggers, pass the release version explicitly.
+
+The configuration must include `release.repository` and a `release_asset`
+for each selected target. See [Publishing a release](publishing.md).
+
+Use the same native-packages release for the workflow and `tool.version`.
+For an immutable workflow reference, replace `v0.7.0` with that release's
+full commit SHA.
+
+## Build without publishing
+
+Set `publish: false` to build and upload the `native-packages` Actions
+artifact without attaching anything to the GitHub release. This is useful
+while you test the workflow.
+
+With no `version`, the reusable workflow only validates the configuration:
+
+```yaml
+name: Check packaging
+on: [pull_request]
+permissions:
+  contents: read
+jobs:
+  packaging:
+    uses: crmne/native-packages/.github/workflows/package.yml@v0.7.0
+```
+
+Validation does not compile the app or check that future release inputs exist.
+
+## Use files from an Actions artifact
+
+If a preceding job uploads your compiled app as an Actions artifact, use
+`source-artifact` instead of downloading inputs from a GitHub release:
+
+```yaml
+packaging:
+  needs: build
+  permissions:
+    contents: write
+  uses: crmne/native-packages/.github/workflows/package.yml@v0.7.0
+  with:
+    version: '1.2.3'
+    source-artifact: linux-binaries
+    source-directory: dist
+    publish: false
+```
+
+Here, the existing `build` job must upload an artifact named `linux-binaries`.
+The workflow extracts it under `dist`. Its filenames and directory structure
+must match your targets' `input.local` paths. This uses local build mode,
+which runs any configured `before_build` hook.
+
+## Select Linux targets in a shared configuration
+
+The reusable workflow runs on Linux. If your configuration also has DMG or
+Inno targets, select the Linux targets explicitly:
+
+```yaml
+with:
+  version: ${{ github.ref_name }}
+  targets: linux-amd64,linux-arm64
+  publish: true
+```
+
+The workflow passes the same target selection to build and publication.
+It requires every format declared for those targets. An empty selection
+means all configured targets.
+
+Build DMG and Inno targets in your own macOS and Windows jobs with the CLI.
+See [Building across platforms](multi-platform.md) for combining their outputs
+and generating recipes after all packages are available.
+
+## Workflow inputs
+
+| Input | Default | Purpose |
+| --- | --- | --- |
+| `version` | Empty | App version or tag. Empty means validate only. |
+| `publish` | `false` | Upload packages to the existing release; enable configured downstream publishing. |
+| `targets` | Empty | Comma-separated target IDs. Empty selects all targets. |
+| `config` | Auto-discovered | Path to the configuration file. |
+| `source-artifact` | Empty | Artifact containing local inputs. Empty uses GitHub release assets. |
+| `source-directory` | `dist` | Where to download that artifact, relative to the checkout. |
+
+## Enable AUR or Homebrew publication
+
+First set up and test the [downstream destination](distribution-recipes.md).
+Then configure these repository variables and secrets in your application's
+GitHub repository:
+
+| Destination | Repository variable | Secrets |
+| --- | --- | --- |
+| AUR group `aur` | `PUBLISH_AUR=true` | `AUR_SSH_KEY`, `AUR_KNOWN_HOSTS` |
+| Destination or group `homebrew` | `PUBLISH_HOMEBREW=true` | `HOMEBREW_TAP_GITHUB_TOKEN` |
+
+These steps run only with `publish: true`. The Homebrew token needs write
+access to your tap; the AUR key needs access to the configured repositories.
+Use `secrets: inherit` as in the release example, or pass the named secrets
+explicitly. If another tool already publishes a destination, keep one
+publisher responsible for it.
+
+## Multiple jobs and configurations
+
+The reusable workflow gives different configuration paths and target
+selections separate concurrency groups. If you are still using the old
+`v0.5.0` workflow, serialize calls with `needs` or upgrade to avoid calls
+interfering with one another.
+
+When downloading build outputs from native jobs, preserve the entire build
+directory, including hidden files in generated recipes. See
+[Building across platforms](multi-platform.md) for the shared timestamp and
+checkout requirements.

data/docs/_guides/multi-platform.md

@@ -0,0 +1,153 @@
+---
+title: Building across platforms
+description: Build targets on their required hosts, combine the results, and generate distribution recipes once all packages are ready.
+nav_order: 8
+---
+
+# Building across platforms
+
+When a release includes Linux packages, a DMG, and a Windows installer, each
+build job can produce its own directory. **Aggregation** combines those
+verified directories into one result you can publish.
+
+This guide assumes your configuration already declares the targets. Use
+[Building packages](building-packages.md) for Linux and
+[macOS and Windows installers](native-recipes.md) for native targets.
+
+## Use the same release inputs
+
+Every job must use the same configuration, app version, and build timestamp.
+Check out the same commit with the same Git history depth on every host.
+Set `SOURCE_DATE_EPOCH` to the same Unix timestamp in each job, normally the
+release commit's timestamp.
+
+For example, in a shell on Linux or macOS:
+
+```sh
+export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
+```
+
+In PowerShell on Windows:
+
+```powershell
+$env:SOURCE_DATE_EPOCH = git show -s --format=%ct HEAD
+```
+
+In GitHub Actions, use `fetch-depth: 0` on each checkout so Git-derived recipe
+values agree. Native packaging scripts should respect the shared timestamp
+where their tools support it.
+
+## Build each target on its host
+
+For a project with exactly these three targets, run the corresponding command
+in each job:
+
+```sh
+# Linux
+native-packages build --version 1.2.3 --target linux-amd64 --output dist/linux
+
+# macOS
+native-packages build --version 1.2.3 --target macos-arm64 --output dist/macos
+
+# Windows
+native-packages build --version 1.2.3 --target windows-amd64 --output dist/windows
+```
+
+Transfer the complete build directories to the machine that will combine
+and publish them. Keep `build.json`, the package subdirectories, and any
+recipes. Preserve hidden files such as `.SRCINFO` when uploading CI artifacts.
+
+Then run from a checkout with the same configuration:
+
+```sh
+native-packages aggregate dist/linux dist/macos dist/windows --output dist/complete
+```
+
+The command checks hashes and rejects overlapping target/format outputs,
+conflicting recipe files, and missing targets. The destination must be new.
+The original build directories are preserved.
+
+After your app's package tests pass:
+
+```sh
+native-packages publish --from dist/complete --to github
+```
+
+## Generate recipes after packages are built
+
+A Homebrew cask may need the checksum of the DMG produced by this very release.
+In that case, **defer recipes**: build the packages first and render recipes
+once the final files are available.
+
+On each host, add `--defer-recipes`:
+
+```sh
+native-packages doctor --target linux-amd64 --defer-recipes
+native-packages build --version 1.2.3 --target linux-amd64 --defer-recipes --output dist/linux
+native-packages build --version 1.2.3 --target macos-arm64 --defer-recipes --output dist/macos
+native-packages build --version 1.2.3 --target windows-amd64 --defer-recipes --output dist/windows
+```
+
+Each job still checks its selected targets and runs signing hooks, but skips
+global recipe assets and recipe tools. AUR tooling is therefore needed only
+on the finalization host.
+
+Collect the results on Linux, along with any additional recipe assets, and run:
+
+```sh
+native-packages aggregate dist/linux dist/macos dist/windows \
+  --finalize-recipes --output dist/complete
+```
+
+The command verifies all targets, resolves asset hashes, generates the recipes
+and recipe archive, and writes a completed build. You can then test and publish:
+
+```sh
+native-packages publish --from dist/complete --to github,aur,homebrew
+```
+
+Only name destinations you have configured. A deferred build cannot be
+published directly, and ordinary and deferred build directories cannot be
+mixed in one aggregate.
+
+## Connect a recipe asset to a built package
+
+Declare the asset's `file` to match the native package's output filename:
+
+```yaml
+assets:
+  MACOS:
+    file: hello-@TAG@-macos-arm64.dmg
+```
+
+For version 1.2.3, the finalizer finds the verified package named
+`hello-v1.2.3-macos-arm64.dmg`. Its hash includes signing and notarization.
+A recipe can then use `@MACOS_URL@` and `@MACOS_SHA256@`.
+
+A matching package takes precedence over an asset's `local` path. Package
+filenames must be unique. Other assets, such as source or portable archives,
+need their configured `local` files on the finalization host. Finalization
+does not download those assets, even when the target builds used `--release`.
+
+## Requirements for finalization
+
+All input directories must defer recipes and agree on configuration, version,
+timestamp, tool versions, and recipe metadata. Include every configured target
+and format. The finalizer needs `tar` and `xz` for recipe archives, and
+`makepkg` or working Docker for AUR metadata.
+
+A deferred target can use asset filenames and URLs, but it cannot use an
+unknown asset hash such as `@MACOS_SHA256@` in its own input, package definition,
+or hooks. Such a target needs an ordinary build with that asset already
+available. Release downloads still require checksums when recipes are deferred.
+
+Prerelease recipes cannot be finalized. See [Prereleases](prereleases.md)
+for using a shared native configuration with stable recipes.
+
+## Publish Linux targets separately
+
+If your app's own jobs already upload the native installers, you can use the
+[reusable Linux workflow](github-actions.md#select-linux-targets-in-a-shared-configuration)
+with `targets: linux-amd64,linux-arm64`. That workflow builds and publishes
+exactly those complete targets. This is useful when you do not need a combined
+release directory or deferred recipe finalization.