native-packages 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ac048cc41a4da6fce8d7fb71973cac33e9f8590eea8e78c0817d4a5edf09b78f
4
- data.tar.gz: 04222cbfdc2f7fbf432506bf5d68d752a3bee15b158e95d42ec6ce70f869b039
3
+ metadata.gz: b0bd80674a1e85d0ea267ea482d110043051ad942fbb8e0b618b3acaf3cb16eb
4
+ data.tar.gz: 05c74949fd067cf2b8b81adf7ac8a148a16c2620c5b9fdf4dea0af78f02457c6
5
5
  SHA512:
6
- metadata.gz: 569d551cc59851f81449c32d4e92afcc1729902fea9aa3cff7ce68ca88957ce996b29465ccfd255af9b598cb50de413b885d5189039d091e46174607e9a3fc0a
7
- data.tar.gz: 0fcbae8d5b81e151f4fdbea78e29323f22220670fe0e6f28920512cb4355346c762f48e066b6f34e30576212ccc1d9ba81fafadaa05929333451c72e00903878
6
+ metadata.gz: 8d8301d54fa95ee34b3c80ab34657b44cd1e2a09d751039d97e437115537ae5224bc4a42f936becd4cb5e6c42e4594f54af4adc925d6b5a4e74c07693bc5e3ea
7
+ data.tar.gz: 64d8dfa8a953385b61f4a12377fdf810b497571c28f859ab11615995f2093193e128650735a304771f2235a5f287a06aeb0c6e3790ed2232715d351fbce25a2c
data/CONTRIBUTING.md CHANGED
@@ -18,7 +18,7 @@ To check the packaged gem and standalone command:
18
18
 
19
19
  ```sh
20
20
  gem build native-packages.gemspec
21
- ruby test/gem_install.rb native-packages-0.11.0.gem
21
+ ruby test/gem_install.rb native-packages-0.12.0.gem
22
22
  ```
23
23
 
24
24
  See [Releasing the gem](docs/releasing.md) for publication and
data/README.md CHANGED
@@ -50,7 +50,7 @@ record. Local builds work without a GitHub release or credentials.
50
50
 
51
51
  | Platform | Outputs |
52
52
  | --- | --- |
53
- | Linux | DEB, RPM, AppImage, Arch Linux packages, Alpine APK, IPK, and source RPM |
53
+ | Linux | DEB, RPM, AppImage, Flatpak bundles, snaps, Arch Linux packages, Alpine APK, IPK, and source RPM |
54
54
  | macOS | DMG, using your packaging script; optional Apple signing and notarization |
55
55
  | Windows | MSIX, or MSI and Inno Setup installers using your packaging script; optional Azure Artifact Signing |
56
56
 
@@ -69,6 +69,7 @@ Start with [getting started](docs/_guides/getting-started.md).
69
69
  - [Apple signing and notarization](docs/_guides/apple-notarization.md) — prepare macOS downloads for distribution.
70
70
  - [Windows code signing](docs/_guides/windows-signing.md): sign Windows executables and installers with Azure Artifact Signing.
71
71
  - [Release signatures and attestations](docs/_guides/release-signing.md): authorize updater downloads and identify their build workflow.
72
+ - [Hosted package repositories](docs/_guides/hosted-repositories.md): publish signed repositories that users update through their package manager.
72
73
  - [AUR, Homebrew, and other repositories](docs/_guides/distribution-recipes.md) — generate and publish recipes.
73
74
  - [Omarchy packages](docs/_guides/omarchy.md): write a first Omarchy recipe that Omarchy's bot then keeps updated.
74
75
 
@@ -130,6 +130,11 @@ Add `appimage` to a Linux target's formats for a single file that runs without
130
130
  installation. It needs one desktop entry and its icon among the contents; see
131
131
  [AppImage](../_reference/platforms.md#appimage).
132
132
 
133
+ Add `flatpak` for a Flatpak bundle of the same files, with a top-level
134
+ `flatpak` section naming the app ID, runtime and sandbox permissions; see
135
+ [Flatpak](../_reference/platforms.md#flatpak). Add `snap` for a snap, with a
136
+ top-level `snap` section; see [Snap](../_reference/platforms.md#snap).
137
+
133
138
  Use a separate musl or static build for Alpine. Changing `formats` alone
134
139
  does not change which systems a binary can run on.
135
140
 
@@ -17,7 +17,7 @@ own compiled executable, or build the tiny example below.
17
17
  You need Ruby 3.2 or later. Install the version used by these guides:
18
18
 
19
19
  ```sh
20
- gem install native-packages --version 0.11.0
20
+ gem install native-packages --version 0.12.0
21
21
  ```
22
22
 
23
23
  For Linux packages, install **nFPM 2.47.0**, the helper native-packages uses to
@@ -79,7 +79,7 @@ Open the generated `native-packages.yaml` and replace its contents with:
79
79
  ```yaml
80
80
  schema: 1
81
81
  tool:
82
- version: '0.11.0'
82
+ version: '0.12.0'
83
83
  nfpm: '2.47.0'
84
84
 
85
85
  nfpm:
@@ -24,7 +24,7 @@ packaging:
24
24
  needs: release
25
25
  permissions:
26
26
  contents: write
27
- uses: crmne/native-packages/.github/workflows/package.yml@v0.11.0
27
+ uses: crmne/native-packages/.github/workflows/package.yml@v0.12.0
28
28
  with:
29
29
  version: ${{ github.ref_name }}
30
30
  publish: true
@@ -39,7 +39,7 @@ The configuration must include `release.repository` and a `release_asset`
39
39
  for each selected target. See [Publishing a release](publishing.md).
40
40
 
41
41
  Use the same native-packages release for the workflow and `tool.version`.
42
- For an immutable workflow reference, replace `v0.11.0` with that release's
42
+ For an immutable workflow reference, replace `v0.12.0` with that release's
43
43
  full commit SHA.
44
44
 
45
45
  ## Build without publishing
@@ -57,7 +57,7 @@ permissions:
57
57
  contents: read
58
58
  jobs:
59
59
  packaging:
60
- uses: crmne/native-packages/.github/workflows/package.yml@v0.11.0
60
+ uses: crmne/native-packages/.github/workflows/package.yml@v0.12.0
61
61
  ```
62
62
 
63
63
  Validation does not compile the app or check that future release inputs exist.
@@ -72,7 +72,7 @@ packaging:
72
72
  needs: build
73
73
  permissions:
74
74
  contents: write
75
- uses: crmne/native-packages/.github/workflows/package.yml@v0.11.0
75
+ uses: crmne/native-packages/.github/workflows/package.yml@v0.12.0
76
76
  with:
77
77
  version: '1.2.3'
78
78
  source-artifact: linux-binaries
@@ -0,0 +1,170 @@
1
+ ---
2
+ title: Hosted package repositories
3
+ description: Publish signed APT, DNF and Flatpak repositories that users add once and update with their package manager.
4
+ nav_order: 13
5
+ ---
6
+
7
+ # Hosted package repositories
8
+
9
+ A package attached to a GitHub release is installed once and then forgotten.
10
+ Users who add your repository instead get every update through their own
11
+ package manager. native-packages writes these repositories as static files
12
+ into a directory you choose, such as a checkout of a GitHub Pages site, and
13
+ signs them with your OpenPGP key. It only writes files: your release job
14
+ commits and pushes the directory afterwards, as it would any website change.
15
+
16
+ ## 1. Make a signing key
17
+
18
+ Use a key for this repository alone, without an expiry date you might miss,
19
+ and keep its secret half out of every repository:
20
+
21
+ ```sh
22
+ gpg --quick-gen-key 'Hello packages <packages@example.org>' ed25519 sign never
23
+ gpg --list-keys --with-colons packages@example.org | awk -F: '/^fpr/ { print $10; exit }'
24
+ ```
25
+
26
+ The second command prints the key's full fingerprint, which goes into the
27
+ configuration. Locally, native-packages signs with the key your GnuPG agent
28
+ already holds. In CI, export the secret key and store it as a secret:
29
+
30
+ ```sh
31
+ gpg --armor --export-secret-keys FINGERPRINT
32
+ ```
33
+
34
+ Pass it to the publish step as `NATIVE_PACKAGES_GPG_KEY`, and the key's
35
+ passphrase, if it has one, as `NATIVE_PACKAGES_GPG_PASSPHRASE`.
36
+ native-packages removes both from its environment before running any other
37
+ program, imports the key into a temporary keyring that it deletes
38
+ afterwards, and checks every signature against the configured fingerprint
39
+ before writing it.
40
+
41
+ ## 2. Configure the repositories
42
+
43
+ ```yaml
44
+ apt:
45
+ directory: ../hello-site/apt
46
+ url: https://example.org/apt
47
+ signing_key: 0123456789ABCDEF0123456789ABCDEF01234567
48
+ keep: 3
49
+ dnf:
50
+ directory: ../hello-site/rpm
51
+ url: https://example.org/rpm
52
+ signing_key: 0123456789ABCDEF0123456789ABCDEF01234567
53
+ flatpak:
54
+ # The app's id, runtime, command and permissions, as for any Flatpak.
55
+ repository:
56
+ directory: ../hello-site/flatpak
57
+ url: https://example.org/flatpak
58
+ title: Hello
59
+ signing_key: 0123456789ABCDEF0123456789ABCDEF01234567
60
+ ```
61
+
62
+ | Field | Purpose |
63
+ | --- | --- |
64
+ | `directory` | Required. Where the repository is written, relative to the configuration file. |
65
+ | `url` | Required. The `https://` URL at which that directory is served. |
66
+ | `signing_key` | Required. The signing key's full fingerprint. |
67
+ | `keep` | APT and DNF only. How many versions of each package and architecture to keep. Defaults to `3`. |
68
+ | `suite`, `component` | APT only. Default to `stable` and `main`. |
69
+ | `title`, `homepage` | Flatpak only. The repository's name in software centers (defaults to the package name) and an `https://` homepage. |
70
+
71
+ ## 3. Publish
72
+
73
+ Build as usual, then publish the build to the repositories:
74
+
75
+ ```sh
76
+ native-packages build --version 1.2.3
77
+ native-packages publish --from dist/packages/1.2.3 --to github,apt,dnf,flatpak
78
+ ```
79
+
80
+ Each publication adds the build's packages to what the directory already
81
+ holds, removes versions beyond `keep`, and rewrites and signs the indexes. A
82
+ file that is already published can only be published again unchanged. Then
83
+ commit and push the directory.
84
+
85
+ ## APT
86
+
87
+ `publish --to apt` copies each `.deb` into `pool/main/h/hello/` and writes
88
+ `dists/stable/` with `Packages` and `Packages.gz` for every architecture,
89
+ `Release`, a clearsigned `InRelease` and a detached `Release.gpg`. These are
90
+ written by native-packages itself, so no Debian tools are needed. Beside them
91
+ go the public key as `hello.gpg` and a `hello.sources` file. Users install
92
+ with:
93
+
94
+ ```sh
95
+ sudo install -d -m 0755 /etc/apt/keyrings
96
+ sudo curl -fsSLo /etc/apt/keyrings/hello.gpg https://example.org/apt/hello.gpg
97
+ sudo curl -fsSLo /etc/apt/sources.list.d/hello.sources https://example.org/apt/hello.sources
98
+ sudo apt update && sudo apt install hello
99
+ ```
100
+
101
+ The `.sources` file trusts this key for this repository alone. Use it on
102
+ apt 1.1 and later (Debian 9, Ubuntu 16.04 and newer).
103
+
104
+ ## DNF
105
+
106
+ `publish --to dnf` copies each `.rpm` into `packages/`, runs `createrepo_c`
107
+ to write `repodata/`, and signs `repodata/repomd.xml` as
108
+ `repodata/repomd.xml.asc`. Beside them go the public key as `hello.asc` and
109
+ a `hello.repo` file. Users install with:
110
+
111
+ ```sh
112
+ sudo curl -fsSLo /etc/yum.repos.d/hello.repo https://example.org/rpm/hello.repo
113
+ sudo dnf install hello
114
+ ```
115
+
116
+ dnf asks once whether to trust the key, then checks the metadata's signature
117
+ on every update (`repo_gpgcheck=1`). The packages themselves are signed only
118
+ if you sign them, with nFPM's `rpm.signature`; `hello.repo` turns on
119
+ `gpgcheck` when every published RPM carries a signature. The same file works
120
+ for Zypper (`zypper addrepo https://example.org/rpm/hello.repo`). Install
121
+ `createrepo_c` (in the `createrepo-c` package on Debian and Ubuntu) on the
122
+ machine that publishes.
123
+
124
+ ## Flatpak
125
+
126
+ `publish --to flatpak` imports each Flatpak bundle into an OSTree
127
+ repository in the directory, signing its commits, then updates the
128
+ repository's summary and static deltas with `flatpak build-update-repo`.
129
+ Each bundle's commit stands alone, without the previous version as its
130
+ parent, so the repository serves each app's newest commit and prunes the
131
+ rest; users cannot roll back to an older version through it. Beside it go
132
+ `hello.flatpakrepo`, for adding the repository, and `ID.flatpakref`, for
133
+ installing the app, both carrying the public key. Users install with:
134
+
135
+ ```sh
136
+ flatpak install --user https://example.org/flatpak/org.example.Hello.flatpakref
137
+ ```
138
+
139
+ and get updates from `flatpak update`. If `flatpak.runtime_repo` is set, a
140
+ missing runtime comes from there. Publishing needs `flatpak` and `ostree`.
141
+
142
+ This is your own repository, not Flathub. native-packages does not write or
143
+ submit Flathub manifests, because Flathub does not accept AI-assisted
144
+ manifests or submissions.
145
+
146
+ ## GitHub Pages
147
+
148
+ Serve the site from a branch or folder, and add an empty `.nojekyll` file
149
+ at its root so GitHub publishes the repository's files as they are. A
150
+ release job can check out the site beside the app:
151
+
152
+ ```yaml
153
+ - uses: actions/checkout@v7
154
+ with:
155
+ repository: example/hello-site
156
+ path: hello-site
157
+ token: ${{ secrets.SITE_TOKEN }}
158
+ - run: native-packages publish --from dist/native-packages --to apt,dnf,flatpak
159
+ env:
160
+ NATIVE_PACKAGES_GPG_KEY: ${{ secrets.PACKAGES_GPG_KEY }}
161
+ - run: |
162
+ cd hello-site
163
+ git add -A
164
+ git commit -m "Publish hello $VERSION"
165
+ git push
166
+ ```
167
+
168
+ With directories such as `hello-site/apt` in the configuration, the
169
+ repositories land in that checkout. GitHub Pages serves sites of up to 1 GB, so keep `keep` low
170
+ for large packages.
@@ -31,7 +31,7 @@ Here is a complete configuration for an ARM64 Mac app and an x86-64 Windows app:
31
31
  ```yaml
32
32
  schema: 1
33
33
  tool:
34
- version: '0.11.0'
34
+ version: '0.12.0'
35
35
  nfpm: '2.47.0'
36
36
  nfpm:
37
37
  name: hello
@@ -115,6 +115,25 @@ To combine builds from several jobs, follow
115
115
  [Building across platforms](multi-platform.md). Builds with deferred recipes
116
116
  must be finalized before publication.
117
117
 
118
+ ## Upload snaps to the Snap Store
119
+
120
+ Register the snap's name in the Snap Store, set `snap.store.channels`, and
121
+ export a login for the release job:
122
+
123
+ ```sh
124
+ snapcraft export-login --snaps hello --acls package_upload,package_release credentials.txt
125
+ ```
126
+
127
+ Store that file's contents as a secret and pass it to the publish step as
128
+ `SNAPCRAFT_STORE_CREDENTIALS`. With `snapcraft` installed:
129
+
130
+ ```sh
131
+ native-packages publish --from dist/packages/1.2.3 --to snapcraft
132
+ ```
133
+
134
+ Each snap in the build is uploaded and released to the configured channels.
135
+ See [Snap](../_reference/platforms.md#snap).
136
+
118
137
  ## Update distribution recipes
119
138
 
120
139
  For AUR, Homebrew, or another downstream repository, first configure its
@@ -67,7 +67,7 @@ Package publication's separate `packaging-checksums.txt` is also unchanged.
67
67
 
68
68
  ## Attest in the application's build job
69
69
 
70
- The examples use `v0.11.0` for readability. For release workflows, replace it
70
+ The examples use `v0.12.0` for readability. For release workflows, replace it
71
71
  with that release's reviewed full commit SHA, not a mutable branch.
72
72
  After producing the final package, before uploading it, add this step to the
73
73
  job that built it:
@@ -79,7 +79,7 @@ permissions:
79
79
  attestations: write
80
80
  steps:
81
81
  # Existing checkout, build, platform signing and packaging steps go here.
82
- - uses: crmne/native-packages/.github/actions/attest@v0.11.0
82
+ - uses: crmne/native-packages/.github/actions/attest@v0.12.0
83
83
  with:
84
84
  subject-path: dist/*.tar.gz
85
85
  ```
@@ -108,7 +108,7 @@ and install Ruby 3.2 or later with Ed25519-capable OpenSSL before the signing
108
108
  step. Then call:
109
109
 
110
110
  ```yaml
111
- - uses: crmne/native-packages/.github/actions/sign-release@v0.11.0
111
+ - uses: crmne/native-packages/.github/actions/sign-release@v0.12.0
112
112
  with:
113
113
  directory: dist/release
114
114
  public-key: assets/update-public-key.hex
@@ -150,7 +150,7 @@ jobs:
150
150
  - uses: ruby/setup-ruby@v1
151
151
  with:
152
152
  ruby-version: '4.0'
153
- - run: gem install native-packages --version 0.11.0 --no-document
153
+ - run: gem install native-packages --version 0.12.0 --no-document
154
154
  - run: cargo build --locked --release --target x86_64-pc-windows-msvc
155
155
  - name: Sign in to Azure for code signing
156
156
  if: vars.AZURE_SIGNING_PROFILE != ''
@@ -97,8 +97,9 @@ native-packages publish --from dist/linux --to github --target linux-amd64
97
97
  ```
98
98
 
99
99
  `--from` selects the build directory; `--to` lists destinations separated by
100
- commas. `github` uploads release assets. Other names select entries or groups
101
- in `repositories`.
100
+ commas. `github` uploads release assets, `snapcraft` uploads snaps to the
101
+ Snap Store, and `apt`, `dnf` and `flatpak` write the signed repositories configured under
102
+ `apt`, `dnf` and `flatpak.repository`. Other names select entries or groups in `repositories`.
102
103
 
103
104
  The build must be complete and its recorded files unmodified. Repeated
104
105
  `--target` options require exactly those targets, with all their formats.
@@ -221,7 +222,7 @@ If several gem versions are installed, RubyGems lets you select the one required
221
222
  by the configuration:
222
223
 
223
224
  ```sh
224
- native-packages _0.11.0_ build --version 1.2.3
225
+ native-packages _0.12.0_ build --version 1.2.3
225
226
  ```
226
227
 
227
228
  Bundler also works if you prefer to manage the gem in a Gemfile.
@@ -28,7 +28,7 @@ expressions. Use the replacement values listed below.
28
28
  | Field | Purpose |
29
29
  | --- | --- |
30
30
  | `schema` | Required. Set to `1`. |
31
- | `tool.version` | Required. Exact native-packages version, such as `'0.11.0'`. |
31
+ | `tool.version` | Required. Exact native-packages version, such as `'0.12.0'`. |
32
32
  | `tool.nfpm` | Required. Set to `'2.47.0'`, including in native-only configurations. |
33
33
  | `nfpm` | Shared package metadata and installed-file mappings, or a relative YAML filename. Requires `name`. |
34
34
  | `targets` | Required. Named build targets; use `{}` for recipe-only projects. |
@@ -41,6 +41,10 @@ expressions. Use the replacement values listed below.
41
41
  | `version_file` | Cargo manifest checked by `check-version`. |
42
42
  | `version_section` | Cargo section to check; defaults to `package`. |
43
43
  | `windows` | Optional. `windows.signing` turns on [Windows code signing](#windows-signing). |
44
+ | `flatpak` | Required by `flatpak` targets: the app ID, runtime, command and permissions. See [Flatpak](platforms.md#flatpak). |
45
+ | `snap` | Required by `snap` targets: the base, confinement and apps, and the Snap Store channels. See [Snap](platforms.md#snap). |
46
+ | `apt` | Optional signed APT repository for `publish --to apt`. See [Hosted package repositories](../_guides/hosted-repositories.md). |
47
+ | `dnf` | Optional signed DNF repository for `publish --to dnf`. See [Hosted package repositories](../_guides/hosted-repositories.md). |
44
48
 
45
49
  Quote tool versions so they remain strings. A version mismatch reports the
46
50
  command needed to install and select the configured gem.
@@ -99,8 +103,8 @@ letters, digits, and hyphens, starting with a letter or digit.
99
103
  | `native` | Required for DMG, MSI and Inno. Contains `command` and `output`. |
100
104
  | `appimage` | Optional for AppImage targets: `update_information`, embedded with a `.zsync` file beside the AppImage. See [AppImage](platforms.md#update-information). |
101
105
 
102
- Formats are `deb`, `rpm`, `archlinux`, `apk`, `ipk`, `appimage`, `srpm`,
103
- `msix`, `dmg`, `msi`, and `inno`. See [Supported platforms](platforms.md) for their requirements.
106
+ Formats are `deb`, `rpm`, `archlinux`, `apk`, `ipk`, `appimage`, `flatpak`,
107
+ `snap`, `srpm`, `msix`, `dmg`, `msi`, and `inno`. See [Supported platforms](platforms.md) for their requirements.
104
108
 
105
109
  Windows targets select only `[msix]`, `[msi]` or `[inno]`; macOS targets select `[dmg]`.
106
110
  DMG, MSI and Inno each require a separate binary target. SRPM requires a separate
@@ -14,12 +14,14 @@ libraries.
14
14
 
15
15
  | Format | Target | What you supply | Packaging tools |
16
16
  | --- | --- | --- | --- |
17
- | `deb` | Linux | Compatible Linux files and package metadata. | nFPM, `readelf` for binaries. |
18
- | `rpm` | Linux | Compatible Linux files and RPM-specific dependencies. | nFPM, `readelf` for binaries. |
17
+ | `deb` | Linux | Compatible Linux files and package metadata. | nFPM, `readelf` for binaries; `gpg` for a hosted APT repository. |
18
+ | `rpm` | Linux | Compatible Linux files and RPM-specific dependencies. | nFPM, `readelf` for binaries; `createrepo_c` and `gpg` for a hosted DNF repository. |
19
19
  | `archlinux` | Linux | Arch-compatible files and explicit dependencies. | nFPM, `readelf` for binaries. |
20
20
  | `apk` | Linux | Suitable Alpine files, usually musl or static binaries, and dependencies. | nFPM, `readelf` for binaries. |
21
21
  | `ipk` | Linux | Files for the device/distribution baseline, dependencies, and an `abi` label. | nFPM, `readelf` for binaries. |
22
22
  | `appimage` | Linux | The same files as the DEB/RPM, including one desktop entry and its icon. | `mksquashfs` (squashfs-tools), `curl`, `readelf`; `zsyncmake` (zsync) with update information. |
23
+ | `flatpak` | Linux | The same files as the DEB/RPM, under `/usr`, and a top-level `flatpak` section. | `flatpak`, `readelf`; `ostree` and `gpg` to publish a repository. |
24
+ | `snap` | Linux | The same files as the DEB/RPM and a top-level `snap` section. | `mksquashfs` (squashfs-tools), `readelf`; `snapcraft` to upload to the Snap Store. |
23
25
  | `srpm` | Linux source target | RPM spec and source files. | nFPM; native RPM tooling for rebuild tests. |
24
26
  | `msix` | Windows | Windows binaries, identity, application assets, and capabilities. | nFPM; Windows tools for signing and installation tests. |
25
27
  | `dmg` | macOS | Complete app and a DMG script. | macOS, `lipo`, and your script's tools, such as `hdiutil`. |
@@ -123,6 +125,120 @@ pattern. An `after_package` hook must leave the AppImage as it is, or the
123
125
  Running an AppImage needs FUSE on the user's system, or
124
126
  `./App.AppImage --appimage-extract-and-run`.
125
127
 
128
+ ## Flatpak
129
+
130
+ Add `flatpak` to a Linux binary target's `formats` (`amd64` or `arm64`) and
131
+ describe the app once, at the top level:
132
+
133
+ ```yaml
134
+ flatpak:
135
+ id: org.example.Hello
136
+ runtime: org.freedesktop.Platform
137
+ runtime_version: '24.08'
138
+ sdk: org.freedesktop.Sdk
139
+ command: hello
140
+ metainfo: packaging/org.example.Hello.metainfo.xml
141
+ runtime_repo: https://dl.flathub.org/repo/flathub.flatpakrepo
142
+ finish_args:
143
+ - --socket=wayland
144
+ - --socket=fallback-x11
145
+ - --share=ipc
146
+ - --share=network
147
+ ```
148
+
149
+ | Field | Purpose |
150
+ | --- | --- |
151
+ | `id` | Required. The reverse-DNS application ID. |
152
+ | `runtime`, `runtime_version` | Required. The runtime the app runs on, such as `org.freedesktop.Platform` `24.08`. |
153
+ | `sdk` | Optional. Recorded for `flatpak run --devel`; nothing is built with it. |
154
+ | `command` | Required. A program in `/usr/bin` (which becomes `/app/bin`), or an absolute `/app` path. |
155
+ | `finish_args` | The app's sandbox permissions, as `flatpak build-finish` options. |
156
+ | `metainfo` | Optional AppStream file, installed as `ID.metainfo.xml`. It must declare `<id>ID</id>`. |
157
+ | `branch` | Defaults to `stable`. |
158
+ | `runtime_repo` | Optional `.flatpakrepo` URL from which `flatpak install` fetches a missing runtime. |
159
+ | `repository` | Optional [self-hosted Flatpak repository](../_guides/hosted-repositories.md#flatpak) for `publish --to flatpak`. |
160
+
161
+ The bundle holds the same `contents` as the other formats, with `/usr`
162
+ becoming `/app`; a file installed anywhere else fails the build. A contents
163
+ entry with `packager: flatpak` is included only in the Flatpak. Flatpak
164
+ exports only files named after the app ID, so the package's one desktop entry
165
+ becomes `ID.desktop`, its `Icon` becomes the ID, and the icon files it names
166
+ are renamed to match.
167
+
168
+ The output is `NAME-VERSION-ARCH.flatpak` (`x86_64` or `aarch64`), a
169
+ single-file bundle users install with `flatpak install --user FILE`. The app
170
+ is already built, so native-packages writes the metadata and runs
171
+ `flatpak build-finish`, `build-export` and `build-bundle` on the staged
172
+ files. No flatpak-builder, SDK or network is needed, and nothing is compiled
173
+ in the sandbox. Runtimes installed on the build host are hidden from
174
+ `build-finish`, so they cannot add permissions. The same inputs and
175
+ `SOURCE_DATE_EPOCH` give the same OSTree commit, which `build.json` records;
176
+ the bundle file around it also records when it was written, so its hash
177
+ changes between builds.
178
+
179
+ **Libraries come from the runtime.** The binary must run against the
180
+ runtime's libraries, or the package must install the others under `/usr/lib`.
181
+ Test the app in the sandbox with the permissions you declared.
182
+
183
+ native-packages does not write Flathub manifests or submit apps to Flathub,
184
+ because Flathub does not accept AI-assisted manifests or submissions. Write
185
+ and submit a Flathub manifest yourself if you want to publish there.
186
+
187
+ ## Snap
188
+
189
+ Add `snap` to a Linux binary target's `formats` and describe the snap once,
190
+ at the top level. The fields follow `snap.yaml`:
191
+
192
+ ```yaml
193
+ snap:
194
+ base: core24
195
+ confinement: strict
196
+ grade: stable
197
+ icon: /usr/share/icons/hicolor/scalable/apps/hello.svg
198
+ apps:
199
+ hello:
200
+ command: usr/bin/hello
201
+ desktop: usr/share/applications/hello.desktop
202
+ plugs: [wayland, x11, opengl, network, audio-playback]
203
+ store:
204
+ channels: [stable]
205
+ ```
206
+
207
+ | Field | Purpose |
208
+ | --- | --- |
209
+ | `name` | Defaults to `nfpm.name`. 2 to 40 lowercase letters, digits and hyphens. |
210
+ | `base` | Required, such as `core24`. |
211
+ | `confinement` | `strict` (default), `classic` or `devmode`. |
212
+ | `grade` | `stable` (default) or `devel`. |
213
+ | `summary`, `description`, `license`, `title` | Default to the first line of `nfpm.description`, the description and `nfpm.license`. The summary has at most 78 characters. |
214
+ | `apps` | Required. Each app's `command` is a path inside the snap, such as `usr/bin/hello`, and may also set `plugs`, `slots`, `environment`, `daemon` and the other `snap.yaml` app fields. |
215
+ | `apps.APP.desktop` | Optional desktop entry the package installs. It is copied to `meta/gui/APP.desktop`, launching the app. |
216
+ | `icon` | Optional `.png` or `.svg` the package installs; it becomes `meta/gui/icon` and the desktop entries' `Icon`. |
217
+ | `plugs`, `slots`, `layout`, `environment` | Optional top-level `snap.yaml` sections, passed through. |
218
+ | `store.channels` | Channels for `publish --to snapcraft`, such as `stable` or `latest/edge`. |
219
+
220
+ The package's `contents` become the snap's root (`/usr/bin/hello` is
221
+ `$SNAP/usr/bin/hello`), beside a generated `meta/snap.yaml`. A contents entry
222
+ with `packager: snap` is included only in the snap. The output is
223
+ `NAME_VERSION_ARCH.snap` with Snap's architecture names (`amd64`, `arm64`,
224
+ `armhf`, `ppc64el`, `s390x`, `riscv64`). It is an xz SquashFS image owned by
225
+ root, packed with mksquashfs as `snap pack` packs a prime directory. No
226
+ snapcraft, LXD or network is involved, and the same inputs and
227
+ `SOURCE_DATE_EPOCH` give the same bytes.
228
+
229
+ **Libraries come from the base snap or the package.** A strictly confined
230
+ snap does not see the host's libraries, and no snapcraft extension (such as
231
+ `gnome` or `kde-neon`) is applied, so a dynamically linked desktop app needs
232
+ its libraries among the contents and an `environment` that points at them.
233
+ Static binaries need nothing more. Install the snap with
234
+ `snap install --dangerous FILE` and test it under its confinement before
235
+ uploading.
236
+
237
+ `publish --to snapcraft` uploads each snap in the build with
238
+ `snapcraft upload --release=CHANNELS`. The Snap Store login comes from
239
+ `SNAPCRAFT_STORE_CREDENTIALS` (from `snapcraft export-login`), never the
240
+ configuration, and the snap's name must already be registered.
241
+
126
242
  ## MSIX
127
243
 
128
244
  MSIX targets use `platform: windows`, `formats: [msix]`, and PE binaries with
@@ -163,9 +279,10 @@ An Arch package file and an AUR recipe are separate outputs: the former can
163
279
  be installed directly; the latter tells Arch tooling how to obtain and package
164
280
  your app.
165
281
 
166
- There is no Flatpak or Snap build/publication adapter, no NSIS adapter, and no
167
- hosted APT/DNF index service. Keep those workflows in your app's release
168
- process if you need them.
282
+ native-packages can also write signed APT, DNF and Flatpak repositories from
283
+ your DEB, RPM and Flatpak packages, served as static files; see
284
+ [Hosted package repositories](../_guides/hosted-repositories.md). There is no
285
+ NSIS adapter. Keep that workflow in your app's release process if you need it.
169
286
 
170
287
  ## What validation establishes
171
288
 
@@ -23,8 +23,8 @@ working on with `doctor --target ID` and `build --target ID --dry-run`.
23
23
  Install and select the version named in the error:
24
24
 
25
25
  ```sh
26
- gem install native-packages --version 0.11.0
27
- native-packages _0.11.0_ doctor
26
+ gem install native-packages --version 0.12.0
27
+ native-packages _0.12.0_ doctor
28
28
  ```
29
29
 
30
30
  `tool.version` is an exact match. In CI, use the matching released reusable
data/docs/index.md CHANGED
@@ -25,7 +25,7 @@ features:
25
25
  details: Describe your app's files, package metadata, and build targets in a single YAML file.
26
26
  - icon: 🐧
27
27
  title: Linux packages
28
- details: Create DEB, RPM, AppImage, Arch, Alpine, and IPK packages from your compatible Linux builds.
28
+ details: Create DEB, RPM, AppImage, Flatpak, Snap, Arch, Alpine, and IPK packages from your compatible Linux builds.
29
29
  - icon: 🖥️
30
30
  title: Native installers
31
31
  details: Connect your macOS DMG script and your Windows MSI or Inno Setup script, or package Windows apps as MSIX.
data/docs/releasing.md CHANGED
@@ -23,7 +23,7 @@ Update the gemspec, `NativePackages::VERSION`, example/version references and ch
23
23
  Create a GitHub release for that commit:
24
24
 
25
25
  ```sh
26
- gh release create v0.11.0 --target main --title 'native-packages 0.11.0' --notes-file release-notes.md
26
+ gh release create v0.12.0 --target main --title 'native-packages 0.12.0' --notes-file release-notes.md
27
27
  ```
28
28
 
29
29
  Adding `--draft` permits review before publication and does not trigger the publisher. The tag must match the exact gem version and point to a commit on `main`. Set `--prerelease` only for a prerelease gem version.
@@ -36,7 +36,7 @@ If the workflow itself needs a correction, fix it on `main` and dispatch the
36
36
  corrected release workflow against the existing published tag:
37
37
 
38
38
  ```sh
39
- gh workflow run release.yml --ref main -f tag=v0.11.0
39
+ gh workflow run release.yml --ref main -f tag=v0.12.0
40
40
  ```
41
41
 
42
42
  Validation resolves the original tag to an exact commit, requires it to be on
@@ -1,7 +1,7 @@
1
1
  # Supply the listed build outputs before running this example.
2
2
  schema: 1
3
3
  tool:
4
- version: '0.11.0'
4
+ version: '0.12.0'
5
5
  nfpm: '2.47.0'
6
6
  nfpm:
7
7
  name: example-app