From 43589d719451c3c8392f404c26aec1a48124ef65 Mon Sep 17 00:00:00 2001 From: Mirko Maischberger Date: Fri, 23 Oct 2026 23:14:26 +0200 Subject: [PATCH] Add cargo-dist release pipeline with deb/rpm/apk packaging Pushing a v* tag now builds and publishes a GitHub Release carrying: - fully static musl tarballs for x86_64 and aarch64, each holding the binary, README, both license files and the embedded font's license; - macOS tarballs for Intel and Apple Silicon; - a curl | sh installer; - native .deb, .rpm and .apk packages built from the static binaries; - sha256.sum and mapshoot-packages.sha256 checksums, a CycloneDX SBOM and SLSA build provenance attestations. cargo-dist has no built-in deb/rpm/apk support, so packaging/build-packages.sh runs as an extra-artifacts step in the global build phase, where the local artifacts are already staged in target/distrib/. It fetches a pinned, checksum-verified nfpm and drives packaging/nfpm.yaml for both architectures. The Linux binaries are statically linked against musl, so one artifact per architecture runs on glibc distributions and Alpine alike. The packages therefore declare no runtime dependencies and there are no -gnu builds. Also adds a man page (docs/mapshoot.1) installed by all three package formats, a Debian machine-readable copyright covering the dual license and the marker font's OFL-1.1, and repository/homepage metadata. --- .github/workflows/release.yml | 325 ++++++++++++++++++++++++++++++++++ Cargo.toml | 6 + README.md | 40 +++++ dist-workspace.toml | 55 ++++++ docs/mapshoot.1 | 310 ++++++++++++++++++++++++++++++++ packaging/build-packages.sh | 123 +++++++++++++ packaging/copyright | 21 +++ packaging/nfpm.yaml | 72 ++++++++ 8 files changed, 952 insertions(+) create mode 100644 .github/workflows/release.yml create mode 100644 dist-workspace.toml create mode 100644 docs/mapshoot.1 create mode 100755 packaging/build-packages.sh create mode 100644 packaging/copyright create mode 100644 packaging/nfpm.yaml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..195d4d9 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,325 @@ +# This file was autogenerated by dist: https://axodotdev.github.io/cargo-dist +# +# Copyright 2022-2024, axodotdev +# SPDX-License-Identifier: MIT or Apache-2.0 +# +# CI that: +# +# * checks for a Git Tag that looks like a release +# * builds artifacts with dist (archives, installers, hashes) +# * uploads those artifacts to temporary workflow zip +# * on success, uploads the artifacts to a GitHub Release +# +# Note that the GitHub Release will be created with a generated +# title/body based on your changelogs. + +name: Release +permissions: + "contents": "write" + +# This task will run whenever you push a git tag that looks like a version +# like "1.0.0", "v0.1.0-prerelease.1", "my-app/0.1.0", "releases/v1.0.0", etc. +# Various formats will be parsed into a VERSION and an optional PACKAGE_NAME, where +# PACKAGE_NAME must be the name of a Cargo package in your workspace, and VERSION +# must be a Cargo-style SemVer Version (must have at least major.minor.patch). +# +# If PACKAGE_NAME is specified, then the announcement will be for that +# package (erroring out if it doesn't have the given version or isn't dist-able). +# +# If PACKAGE_NAME isn't specified, then the announcement will be for all +# (dist-able) packages in the workspace with that version (this mode is +# intended for workspaces with only one dist-able package, or with all dist-able +# packages versioned/released in lockstep). +# +# If you push multiple tags at once, separate instances of this workflow will +# spin up, creating an independent announcement for each one. However, GitHub +# will hard limit this to 3 tags per commit, as it will assume more tags is a +# mistake. +# +# If there's a prerelease-style suffix to the version, then the release(s) +# will be marked as a prerelease. +on: + pull_request: + push: + tags: + - '**[0-9]+.[0-9]+.[0-9]+*' + +jobs: + # Run 'dist plan' (or host) to determine what tasks we need to do + plan: + runs-on: "ubuntu-22.04" + outputs: + val: ${{ steps.plan.outputs.manifest }} + tag: ${{ !github.event.pull_request && github.ref_name || '' }} + tag-flag: ${{ !github.event.pull_request && format('--tag={0}', github.ref_name) || '' }} + publishing: ${{ !github.event.pull_request }} + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + submodules: recursive + - name: Install dist + # we specify bash to get pipefail; it guards against the `curl` command + # failing. otherwise `sh` won't catch that `curl` returned non-0 + shell: bash + run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.33.0/cargo-dist-installer.sh | sh" + - name: Cache dist + uses: actions/upload-artifact@v7 + with: + name: cargo-dist-cache + path: ~/.cargo/bin/dist + # sure would be cool if github gave us proper conditionals... + # so here's a doubly-nested ternary-via-truthiness to try to provide the best possible + # functionality based on whether this is a pull_request, and whether it's from a fork. + # (PRs run on the *source* but secrets are usually on the *target* -- that's *good* + # but also really annoying to build CI around when it needs secrets to work right.) + - id: plan + run: | + dist ${{ (!github.event.pull_request && format('host --steps=create --tag={0}', github.ref_name)) || 'plan' }} --output-format=json > plan-dist-manifest.json + echo "dist ran successfully" + cat plan-dist-manifest.json + echo "manifest=$(jq -c "." plan-dist-manifest.json)" >> "$GITHUB_OUTPUT" + - name: "Upload dist-manifest.json" + uses: actions/upload-artifact@v7 + with: + name: artifacts-plan-dist-manifest + path: plan-dist-manifest.json + + # Build and packages all the platform-specific things + build-local-artifacts: + name: build-local-artifacts (${{ join(matrix.targets, ', ') }}) + # Let the initial task tell us to not run (currently very blunt) + needs: + - plan + if: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix.include != null && (needs.plan.outputs.publishing == 'true' || fromJson(needs.plan.outputs.val).ci.github.pr_run_mode == 'upload') }} + strategy: + fail-fast: false + # Target platforms/runners are computed by dist in create-release. + # Each member of the matrix has the following arguments: + # + # - runner: the github runner + # - dist-args: cli flags to pass to dist + # - install-dist: expression to run to install dist on the runner + # + # Typically there will be: + # - 1 "global" task that builds universal installers + # - N "local" tasks that build each platform's binaries and platform-specific installers + matrix: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix }} + runs-on: ${{ matrix.runner }} + container: ${{ matrix.container && matrix.container.image || null }} + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BUILD_MANIFEST_NAME: target/distrib/${{ join(matrix.targets, '-') }}-dist-manifest.json + permissions: + "attestations": "write" + "contents": "read" + "id-token": "write" + steps: + - name: enable windows longpaths + run: | + git config --global core.longpaths true + - uses: actions/checkout@v6 + with: + persist-credentials: false + submodules: recursive + - name: Install Rust non-interactively if not already installed + if: ${{ matrix.container }} + run: | + if ! command -v cargo > /dev/null 2>&1; then + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y + echo "$HOME/.cargo/bin" >> $GITHUB_PATH + fi + - name: Install dist + run: ${{ matrix.install_dist.run }} + # Get the dist-manifest + - name: Fetch local artifacts + uses: actions/download-artifact@v8 + with: + pattern: artifacts-* + path: target/distrib/ + merge-multiple: true + - name: Install cargo-auditable + run: ${{ matrix.install_cargo_auditable.run }} + - name: Install dependencies + run: | + ${{ matrix.packages_install }} + - name: Build artifacts + run: | + # Actually do builds and make zips and whatnot + dist build ${{ needs.plan.outputs.tag-flag }} --print=linkage --output-format=json ${{ matrix.dist_args }} > dist-manifest.json + echo "dist ran successfully" + - name: Attest + uses: actions/attest@v4 + with: + subject-path: "target/distrib/*${{ join(matrix.targets, ', ') }}*" + - id: cargo-dist + name: Post-build + # We force bash here just because github makes it really hard to get values up + # to "real" actions without writing to env-vars, and writing to env-vars has + # inconsistent syntax between shell and powershell. + shell: bash + run: | + # Parse out what we just built and upload it to scratch storage + echo "paths<> "$GITHUB_OUTPUT" + dist print-upload-files-from-manifest --manifest dist-manifest.json >> "$GITHUB_OUTPUT" + echo "EOF" >> "$GITHUB_OUTPUT" + + cp dist-manifest.json "$BUILD_MANIFEST_NAME" + - name: "Upload artifacts" + uses: actions/upload-artifact@v7 + with: + name: artifacts-build-local-${{ join(matrix.targets, '_') }} + path: | + ${{ steps.cargo-dist.outputs.paths }} + ${{ env.BUILD_MANIFEST_NAME }} + + # Build and package all the platform-agnostic(ish) things + build-global-artifacts: + needs: + - plan + - build-local-artifacts + runs-on: "ubuntu-22.04" + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BUILD_MANIFEST_NAME: target/distrib/global-dist-manifest.json + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + submodules: recursive + - name: Install cached dist + uses: actions/download-artifact@v8 + with: + name: cargo-dist-cache + path: ~/.cargo/bin/ + - run: chmod +x ~/.cargo/bin/dist + - name: Install cargo-cyclonedx + # we specify bash to get pipefail; it guards against the `curl` command + # failing. otherwise `sh` won't catch that `curl` return non-0 + run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/CycloneDX/cyclonedx-rust-cargo/releases/download/cargo-cyclonedx-0.5.5/cargo-cyclonedx-installer.sh | sh" + shell: bash + # Get all the local artifacts for the global tasks to use (for e.g. checksums) + - name: Fetch local artifacts + uses: actions/download-artifact@v8 + with: + pattern: artifacts-* + path: target/distrib/ + merge-multiple: true + - id: cargo-dist + shell: bash + run: | + dist build ${{ needs.plan.outputs.tag-flag }} --output-format=json "--artifacts=global" > dist-manifest.json + echo "dist ran successfully" + + # Parse out what we just built and upload it to scratch storage + echo "paths<> "$GITHUB_OUTPUT" + jq --raw-output ".upload_files[]" dist-manifest.json >> "$GITHUB_OUTPUT" + echo "EOF" >> "$GITHUB_OUTPUT" + + cp dist-manifest.json "$BUILD_MANIFEST_NAME" + - id: cargo-cyclonedx + shell: bash + run: | + # Generate SBOM (.cdx.xml) files. + cargo cyclonedx -v + + # Move all SBOM (.cdx.xml) files under target/distrib/ since + # we expect all artifacts to be in that folder. + find . -name '*.cdx.xml' -exec mv '{}' target/distrib/ ';' + + echo "paths<> "$GITHUB_OUTPUT" + find . -name '*.cdx.xml' | tee -a "$GITHUB_OUTPUT" + echo "EOF" >> "$GITHUB_OUTPUT" + - name: "Upload artifacts" + uses: actions/upload-artifact@v7 + with: + name: artifacts-build-global + path: | + ${{ steps.cargo-dist.outputs.paths }} + ${{ steps.cargo-cyclonedx.output.paths }} + ${{ env.BUILD_MANIFEST_NAME }} + # Determines if we should publish/announce + host: + needs: + - plan + - build-local-artifacts + - build-global-artifacts + # Only run if we're "publishing", and only if plan, local and global didn't fail (skipped is fine) + if: ${{ always() && needs.plan.result == 'success' && needs.plan.outputs.publishing == 'true' && (needs.build-global-artifacts.result == 'skipped' || needs.build-global-artifacts.result == 'success') && (needs.build-local-artifacts.result == 'skipped' || needs.build-local-artifacts.result == 'success') }} + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + runs-on: "ubuntu-22.04" + outputs: + val: ${{ steps.host.outputs.manifest }} + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + submodules: recursive + - name: Install cached dist + uses: actions/download-artifact@v8 + with: + name: cargo-dist-cache + path: ~/.cargo/bin/ + - run: chmod +x ~/.cargo/bin/dist + # Fetch artifacts from scratch-storage + - name: Fetch artifacts + uses: actions/download-artifact@v8 + with: + pattern: artifacts-* + path: target/distrib/ + merge-multiple: true + - id: host + shell: bash + run: | + dist host ${{ needs.plan.outputs.tag-flag }} --steps=upload --steps=release --output-format=json > dist-manifest.json + echo "artifacts uploaded and released successfully" + cat dist-manifest.json + echo "manifest=$(jq -c "." dist-manifest.json)" >> "$GITHUB_OUTPUT" + - name: "Upload dist-manifest.json" + uses: actions/upload-artifact@v7 + with: + # Overwrite the previous copy + name: artifacts-dist-manifest + path: dist-manifest.json + # Create a GitHub Release while uploading all files to it + - name: "Download GitHub Artifacts" + uses: actions/download-artifact@v8 + with: + pattern: artifacts-* + path: artifacts + merge-multiple: true + - name: Cleanup + run: | + # Remove the granular manifests + rm -f artifacts/*-dist-manifest.json + - name: Create GitHub Release + env: + PRERELEASE_FLAG: "${{ fromJson(steps.host.outputs.manifest).announcement_is_prerelease && '--prerelease' || '' }}" + ANNOUNCEMENT_TITLE: "${{ fromJson(steps.host.outputs.manifest).announcement_title }}" + ANNOUNCEMENT_BODY: "${{ fromJson(steps.host.outputs.manifest).announcement_github_body }}" + RELEASE_COMMIT: "${{ github.sha }}" + run: | + # Write and read notes from a file to avoid quoting breaking things + echo "$ANNOUNCEMENT_BODY" > $RUNNER_TEMP/notes.txt + + gh release create "${{ needs.plan.outputs.tag }}" --target "$RELEASE_COMMIT" $PRERELEASE_FLAG --title "$ANNOUNCEMENT_TITLE" --notes-file "$RUNNER_TEMP/notes.txt" artifacts/* + + announce: + needs: + - plan + - host + # use "always() && ..." to allow us to wait for all publish jobs while + # still allowing individual publish jobs to skip themselves (for prereleases). + # "host" however must run to completion, no skipping allowed! + if: ${{ always() && needs.host.result == 'success' }} + runs-on: "ubuntu-22.04" + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + submodules: recursive diff --git a/Cargo.toml b/Cargo.toml index 9ef0748..9be226c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,6 +8,8 @@ license = "MIT OR Apache-2.0" readme = "README.md" keywords = ["map", "static-map", "geojson", "tiles", "png"] categories = ["command-line-utilities", "graphics", "multimedia::images"] +repository = "https://github.com/baol/mapshoot" +homepage = "https://github.com/baol/mapshoot" [dependencies] ab_glyph = "0.2" @@ -22,3 +24,7 @@ ureq = { version = "3", default-features = false, features = ["rustls"] } lto = true strip = true codegen-units = 1 + +# The profile that 'dist' will build with +[profile.dist] +inherits = "release" diff --git a/README.md b/README.md index 9f543df..2fae330 100644 --- a/README.md +++ b/README.md @@ -240,6 +240,46 @@ cargo test --locked CI runs these on stable Rust (`.github/workflows/ci.yml`). Tests use local HTTP fixtures. +## Releases and packaging + +Pushing a `v*` tag builds and publishes a GitHub Release via cargo-dist +(`.github/workflows/release.yml`, configured in `dist-workspace.toml`). Each +release carries: + +- fully static musl tarballs for `x86_64` and `aarch64`, each holding the + binary, the README, both license files, and the embedded font's license; +- macOS tarballs for Intel and Apple Silicon; +- a `curl | sh` installer; +- native `.deb`, `.rpm`, and `.apk` packages built from the static binaries; +- `sha256.sum` and `mapshoot-packages.sha256` checksums, a CycloneDX SBOM, and + SLSA build provenance attestations. + +The Linux binaries are statically linked against musl and have no runtime +dependencies, so one tarball runs on glibc distributions and Alpine alike. That +is why the packages declare no dependencies and there are no separate `-gnu` +builds. + +Packaging lives in `packaging/`: + +| Path | Purpose | +|---|---| +| `nfpm.yaml` | shared deb/rpm/apk package definition | +| `build-packages.sh` | builds the packages from the staged musl binaries | +| `copyright` | Debian machine-readable copyright | + +Packages can be built locally too: + +```sh +dist build --target x86_64-unknown-linux-musl +MAPSHOOT_PACKAGE_TARGETS=x86_64-unknown-linux-musl packaging/build-packages.sh +``` + +The `.deb` and `.rpm` install the binary to `/usr/bin/mapshoot`, a man page to +`/usr/share/man/man1`, and the license files. The `.apk` is unsigned, so +installing it directly needs `apk add --allow-untrusted ./mapshoot-amd64.apk`. +Verify a release artifact with `gh attestation verify --repo +baol/mapshoot`. + ## License Dual licensed under Apache-2.0 ([LICENSE-APACHE](LICENSE-APACHE)) or MIT diff --git a/dist-workspace.toml b/dist-workspace.toml new file mode 100644 index 0000000..8755e73 --- /dev/null +++ b/dist-workspace.toml @@ -0,0 +1,55 @@ +[workspace] +members = ["cargo:."] + +# Config for 'dist' +[dist] +# The preferred dist version to use in CI (Cargo.toml SemVer syntax) +cargo-dist-version = "0.33.0" +# CI backends to support +ci = "github" +# The installers to generate for each app +installers = ["shell"] +# Target platforms to build apps for (Rust target-triple syntax). +# Linux ships as fully static musl only: one artifact per arch runs unmodified on +# glibc distributions and Alpine alike, with no runtime library dependencies. +targets = [ + "x86_64-unknown-linux-musl", + "aarch64-unknown-linux-musl", + "x86_64-apple-darwin", + "aarch64-apple-darwin", +] +# Path that installers should place binaries in +install-path = "CARGO_HOME" +# Where to host releases +hosting = "github" +# Whether to install an updater program +install-updater = false +# Emit SLSA build provenance attestations for the release artifacts. +# Verify with: gh attestation verify --repo baol/mapshoot +github-attestations = true +# Emit a CycloneDX SBOM (bom.xml) per project alongside the archives. +cargo-cyclonedx = true +# Embed the dependency tree into the binaries (audit with `cargo audit`). +cargo-auditable = true +# Extra files to drop at the root of every archive/installer. README, +# LICENSE-MIT and LICENSE-APACHE are auto-detected; the embedded marker font's +# license is not, and OFL 1.1 requires it to ship with the binary. +include = ["assets/OFL.txt"] + +# Native deb/rpm/apk packages, built from the static musl binaries by nfpm. +# dist has no built-in support for these formats, so they are produced as extra +# artifacts during the global build phase (which has all local artifacts staged +# in target/distrib/). Filenames are version-less by design: the asset list must +# be static across releases, and each GitHub Release is its own namespace. +[[dist.extra-artifacts]] +build = ["bash", "packaging/build-packages.sh"] +artifacts = [ + "target/distrib/mapshoot-amd64.deb", + "target/distrib/mapshoot-arm64.deb", + "target/distrib/mapshoot-amd64.rpm", + "target/distrib/mapshoot-arm64.rpm", + "target/distrib/mapshoot-amd64.apk", + "target/distrib/mapshoot-arm64.apk", + # checksums over the six packages above, written by the same script + "target/distrib/mapshoot-packages.sha256", +] diff --git a/docs/mapshoot.1 b/docs/mapshoot.1 new file mode 100644 index 0000000..bf6f452 --- /dev/null +++ b/docs/mapshoot.1 @@ -0,0 +1,310 @@ +.\" Man page for mapshoot. +.TH MAPSHOOT 1 "2026" "mapshoot 0.1.0" "User Commands" +.SH NAME +mapshoot \- render Web Mercator map images from online tile providers with GeoJSON overlays +.SH SYNOPSIS +.B mapshoot +.B \-\-bbox +.I west,south,east,north +.B \-\-output +.I map.png +.RI [ options ] +.br +.B mapshoot +.B \-\-center +.I longitude,latitude +.B \-\-radius +.I meters +.B \-\-output +.I map.png +.RI [ options ] +.br +.B mapshoot +.B \-\-geojson +.I file.geojson +.B \-\-output +.I map.png +.RI [ options ] +.SH DESCRIPTION +.B mapshoot +renders a PNG map image by fetching raster tiles from an online tile provider +and compositing a GeoJSON overlay on top of them. Tiles are drawn on the CPU +with tiny\-skia; no GPU, display server, or browser is required. +.PP +The output is a single PNG. An area is chosen either from an explicit bounding +box, from a center and radius, or is derived automatically from the extent of +the GeoJSON document. The requested box fills the image; the image height +follows the box aspect ratio in Web Mercator unless it is fixed explicitly. +.PP +Every option accepts either +.B \-\-flag VALUE +or +.BI \-\-flag= VALUE. +Rendering and PNG encoding complete before the destination is written, via a +temporary file that is renamed over the output, so a failed run never leaves a +truncated image behind. +.SH OPTIONS +.SS Area +.TP +.BI \-\-bbox " \fIwest,south,east,north\fR" +Bounding box in degrees. Longitudes span \-180..180 and latitudes +\-85.05112878..85.05112878, so the whole world is +.BR \-180,\-85.05112878,180,85.05112878 . +A +.I west +greater than +.I east +crosses the antimeridian. +.TP +.BI \-\-center " \fIlongitude,latitude\fR" +Center of the area; requires +.BR \-\-radius . +Mutually exclusive with +.BR \-\-bbox . +.TP +.BI \-\-radius " \fImeters\fR" +Radius around +.BR \-\-center , +from 0 (exclusive) to 1000000. The resulting box wraps in longitude and is +clamped at the Mercator latitude limit. +.TP +.BI \-\-buffer " \fImeters\fR" +Expand the box by this many meters on every side before framing. Default 0. +.TP +.BI \-\-padding " \fImeters\fR" +Synonym for +.BR \-\-buffer . +At most one of the two may be given. +.SS Image +.TP +.BI \-\-width " \fIN\fR" +Image width in pixels, 1..8192. Default 1024. +.TP +.BI \-\-height " \fIN\fR" +Image height in pixels, 1..8192. By default the height follows the box aspect +ratio; when given, the box is fitted inside the resulting frame and centered. +.TP +.BI \-\-aspect\-ratio " \fIW:H\fR" +Fix the frame shape as a width\-to\-height ratio, either +.I W:H +or a plain positive number. One of +.B \-\-width +or +.B \-\-height +is derived from the other if omitted. +.TP +.BI \-\-pixel\-ratio " \fIN\fR" +Integer output scale, 1..4. Default 1. Multiplies the output dimensions; +width times height times the square of this value must not exceed 64 megapixels. +.TP +.BI \-\-max\-zoom " \fIN\fR" +Highest tile zoom level, 0..22. Default 19 for +.BR osm , +20 for +.B here +and +.BR carto . +Tiles are rendered at +.IR ceil(log2(scale / tile_size)) , +capped at this value. +.TP +.BI \-\-tile\-size " \fIN\fR" +Tile edge length, 256 or 512. Default 256. +.B osm +and +.B carto +accept only 256. +.TP +.BI \-\-concurrency " \fIN\fR" +Parallel tile downloads, 1..32. Default 2 for +.B osm +and 8 for +.B here +and +.BR carto . +.TP +.BI \-\-timeout " \fIN\fR" +Total deadline for the tile download phase in milliseconds, 1..300000. +Default 15000. +.SS Basemap +.TP +.BI \-\-basemap " \fIprovider\fR" +One of +.BR here , +.BR osm , +.BR carto , +.BR xyz , +or +.BR none . +Default +.BR osm , +which needs no API key. +.B none +draws overlays on a plain #dddddd background and prints a warning. +.TP +.BI \-\-here\-style " \fINAME\fR" +HERE only. Default +.BR explore.day . +See +.B BASEMAP STYLES +below. +.TP +.BI \-\-carto\-style " \fINAME\fR" +CARTO only. Default +.BR voyager . +See +.B BASEMAP STYLES +below. +.TP +.BI \-\-tile\-url " \fIURL\fR" +XYZ only. An HTTP(S) URL template containing the placeholders +.BR {z} , +.BR {x} , +and +.BR {y} . +Any credentials belong in this URL. +.TP +.BI \-\-attribution " \fITEXT\fR" +XYZ only and required. Plain printable ASCII, validated to fit the image. +.SS Overlay and output +.TP +.BI \-\-geojson " \fIFILE\fR" +GeoJSON overlay, used with any basemap. Feature, FeatureCollection, +GeometryCollection, Point, LineString, Polygon and their Multi variants are +accepted; null geometries and empty collections are allowed, and polygon rings +must be closed. When neither +.B \-\-bbox +nor +.B \-\-center +is given, the box is derived from the document over the shortest longitude arc +and expanded to include markers and stroke widths. +.TP +.BI \-\-style " \fIFILE\fR" +JSON object with global style fields +.BR color , +.BR fillColor , +.BR weight , +.BR opacity , +.BR fillOpacity , +and +.BR radius . +Colors are #RRGGBB, opacities 0..1, and widths and radii are in logical pixels. +Unknown fields are an error. +.TP +.BI \-\-output ", " \-o " \fIFILE\fR" +Required. PNG destination path, or +.B \- +for standard output. Only PNG output is supported, so the path must end in +.BR .png +unless it is +.BR \- . +.SS Cache +.TP +.B \-\-no\-cache +Disable the tile cache for this run. +.TP +.BI \-\-cache\-dir " \fIPATH\fR" +Cache base directory. The default is the per\-user system cache directory; the +version component +.B v1 +is always appended. +.TP +.BI \-\-cache\-ttl " \fIDAYS\fR" +Freshness lifetime of cached tiles, 1..3650 days. Default 7. +.TP +.BI \-\-cache\-max\-mb " \fIMB\fR" +Cache size cap in megabytes, 1..102400. Default 512. The cache is trimmed +oldest\-first to 90% of the cap. +.SS General +.TP +.B \-\-help ", " \-h +Print a usage summary and exit. +.TP +.B \-\-version +Print the version and exit. +.SH BASEMAP STYLES +.TP +.B HERE +explore.day, explore.night, explore.satellite.day, lite.day, lite.night, +lite.satellite.day, logistics.day, logistics.night, logistics.satellite.day, +satellite.day, topo.day, topo.night, dem. +.TP +.B CARTO +voyager, voyager_nolabels, voyager_labels_under, light_all, light_nolabels, +dark_all, dark_nolabels. +.SH ENVIRONMENT +.TP +.B MAPSHOOT_HERE_API_KEY +HERE API key. Takes precedence over +.BR HERE_API_KEY . +.TP +.B MAPSHOOT_CARTO_API_KEY +CARTO API key. Takes precedence over +.BR CARTO_API_KEY . +.TP +.B MAPSHOOT_CACHE_DIR +Cache base directory, overriding the system default. An empty value disables +caching. Ignored when +.B \-\-cache\-dir +is given. +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An error occurred. With +.BR "\-o \-" , +a broken pipe (for example +.BR "mapshoot ... | head" ) +is treated as success. +.SH FILES +.TP +.I $XDG_CACHE_HOME/mapshoot/v1 +Default tile cache on Linux. +.TP +.I ~/.cache/mapshoot/v1 +Fallback tile cache location on Linux when +.B XDG_CACHE_HOME +is unset. +.TP +.I ~/Library/Caches/mapshoot/v1 +Default tile cache on macOS. +.TP +.I %LOCALAPPDATA%\emapshoot\ev1 +Default tile cache on Windows. +.SH EXAMPLES +Render OpenStreetMap with a styled overlay: +.PP +.RS 4 +.nf +mapshoot \-\-center 13.405,52.52 \-\-radius 1500 \\ + \-\-geojson berlin.geojson \-\-style berlin\-style.json \\ + \-\-output berlin.png +.fi +.RE +.PP +Render a bounding box and write PNG bytes to standard output: +.PP +.RS 4 +.nf +mapshoot \-\-bbox 13.37,52.50,13.44,52.54 \-o \- > berlin.png +.fi +.RE +.PP +Derive the area from the GeoJSON extent, using per\-feature simplestyle colors: +.PP +.RS 4 +.nf +mapshoot \-\-geojson simplestyle.geojson \-\-basemap none \-\-width 800 \-o map.png +.fi +.RE +.SH SEE ALSO +The project README and the library API at +.IR https://github.com/baol/mapshoot . +.SH LICENSE +Dual licensed under Apache\-2.0 or MIT, at your option. Marker symbols use the +embedded Space Grotesk font under the SIL Open Font License 1.1; the +attribution footer uses the 8x8 bitmap font from the +.B font8x8 +crate (MIT). diff --git a/packaging/build-packages.sh b/packaging/build-packages.sh new file mode 100755 index 0000000..0d1b071 --- /dev/null +++ b/packaging/build-packages.sh @@ -0,0 +1,123 @@ +#!/usr/bin/env bash +# +# Build .deb, .rpm and .apk packages for mapshoot from the fully static musl +# binaries that cargo-dist stages in target/distrib/. +# +# cargo-dist has no built-in deb/rpm/apk support, so this runs as an +# `extra-artifacts` build step in the global build phase, where every local +# artifact has already been downloaded into target/distrib/. +# +# It also runs locally at any time, e.g.: +# dist build --target x86_64-unknown-linux-musl +# MAPSHOOT_PACKAGE_TARGETS=x86_64-unknown-linux-musl packaging/build-packages.sh +# +# Requires: bash >= 4, awk, tar (with xz support), gzip, curl, sha256sum, and +# `file` from file(1). +set -euo pipefail + +cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." + +dist_dir=target/distrib +work_dir=target/package-work + +# Targets to package. Overridable to package a subset during local testing; +# dist itself verifies that the full set of declared artifacts exists. +if [[ -n ${MAPSHOOT_PACKAGE_TARGETS:-} ]]; then + read -r -a targets <<<"$MAPSHOOT_PACKAGE_TARGETS" +else + targets=(x86_64-unknown-linux-musl aarch64-unknown-linux-musl) +fi + +# --- pinned, checksum-verified nfpm -------------------------------------- +nfpm_version=2.48.0 +nfpm_base="https://github.com/goreleaser/nfpm/releases/download/v${nfpm_version}" + +case "$(uname -m)" in + x86_64 | amd64) + nfpm_arch=x86_64 + nfpm_sha256=6d7f9a28b2f397934403950fcbba83f598b08d02edbe79a0815b3b4897341750 + ;; + aarch64 | arm64) + nfpm_arch=arm64 + nfpm_sha256=a9a75213763783b7669719e505474c748c5ad7dc66591a195619deb50f85c2f4 + ;; + *) + echo "build-packages.sh: unsupported build host $(uname -m)" >&2 + exit 1 + ;; +esac + +nfpm_dir="target/nfpm-${nfpm_version}-${nfpm_arch}" +if [[ ! -x ${nfpm_dir}/nfpm ]]; then + echo "build-packages.sh: fetching nfpm ${nfpm_version} (${nfpm_arch})" + tmp_dir=$(mktemp -d) + trap 'rm -rf "$tmp_dir"' EXIT + tarball="nfpm_${nfpm_version}_Linux_${nfpm_arch}.tar.gz" + curl -fsSL "${nfpm_base}/${tarball}" -o "${tmp_dir}/${tarball}" + echo "${nfpm_sha256} ${tmp_dir}/${tarball}" | sha256sum -c - >/dev/null + mkdir -p "$nfpm_dir" + tar -xzf "${tmp_dir}/${tarball}" -C "$nfpm_dir" nfpm +fi +nfpm="$PWD/${nfpm_dir}/nfpm" + +# --- version ------------------------------------------------------------- +# Read [package] version straight from Cargo.toml: the global build job that +# runs this script has no cargo/rustup setup step of its own. +version=$(awk -F'"' ' + /^\[package\]/ { in_package = 1; next } + /^\[/ { in_package = 0 } + in_package && /^version[[:space:]]*=/ { print $2; exit } +' Cargo.toml) +if [[ -z ${version} ]]; then + echo "build-packages.sh: cannot determine the crate version from Cargo.toml" >&2 + exit 1 +fi + +mkdir -p "$work_dir" + +# --- build one package set per target ------------------------------------ +packages=() +for target in "${targets[@]}"; do + case "$target" in + x86_64-*) goarch=amd64 ;; + aarch64-*) goarch=arm64 ;; + *) + echo "build-packages.sh: unsupported target ${target}" >&2 + exit 1 + ;; + esac + + tarball="${dist_dir}/mapshoot-${target}.tar.xz" + if [[ ! -f ${tarball} ]]; then + echo "build-packages.sh: missing ${tarball}; run 'dist build' first" >&2 + exit 1 + fi + + bindir="${work_dir}/${target}" + rm -rf "$bindir" + mkdir -p "$bindir" + tar -xJf "$tarball" -C "$bindir" --strip-components=1 + + # Accept both "statically linked" and "static-pie linked"; reject anything + # that depends on a runtime loader. + binary_description=$(file -b "${bindir}/mapshoot") + if [[ $binary_description == *"dynamically linked"* ]]; then + echo "build-packages.sh: ${target} binary is not statically linked: ${binary_description}" >&2 + exit 1 + fi + + for format in deb rpm apk; do + out="${dist_dir}/mapshoot-${goarch}.${format}" + ARCH="$goarch" VERSION="$version" BINDIR="$bindir" \ + "$nfpm" package --config packaging/nfpm.yaml --packager "$format" --target "$out" + packages+=("mapshoot-${goarch}.${format}") + echo "build-packages.sh: built ${out}" + done +done + +# --- checksums over the packages ----------------------------------------- +( + cd "$dist_dir" + sha256sum "${packages[@]}" >mapshoot-packages.sha256 +) +echo "build-packages.sh: wrote ${dist_dir}/mapshoot-packages.sha256" diff --git a/packaging/copyright b/packaging/copyright new file mode 100644 index 0000000..1e018d7 --- /dev/null +++ b/packaging/copyright @@ -0,0 +1,21 @@ +Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ +Upstream-Name: mapshoot +Upstream-Contact: Mirko Maischberger +Source: https://github.com/baol/mapshoot + +Files: * +Copyright: 2026 Mirko Maischberger +License: MIT or Apache-2.0 + This software is dual licensed: you may use it under the terms of either the + MIT license or the Apache License 2.0, at your option. + . + The MIT license text is installed with this package in + /usr/share/doc/mapshoot/LICENSE-MIT. The full text of the Apache License 2.0 + is available on Debian systems in /usr/share/common-licenses/Apache-2.0 and is + installed with this package in /usr/share/doc/mapshoot/LICENSE-APACHE. + +Files: assets/SpaceGrotesk-Regular.ttf +Copyright: 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk) +License: OFL-1.1 + The full text of the SIL Open Font License 1.1 is installed with this package + in /usr/share/doc/mapshoot/OFL.txt. diff --git a/packaging/nfpm.yaml b/packaging/nfpm.yaml new file mode 100644 index 0000000..d5b0540 --- /dev/null +++ b/packaging/nfpm.yaml @@ -0,0 +1,72 @@ +# nFPM configuration for mapshoot. +# +# Builds .deb, .rpm and .apk packages from the fully static musl binary. +# Invoked by packaging/build-packages.sh, which supplies ARCH, VERSION and +# BINDIR in the environment. nFPM always expands ${...} in version/arch; it +# expands a `contents` entry only when that entry sets `expand: true`. +# +# ARCH Go architecture name: amd64 or arm64 (nFPM maps these to the +# per-format names: amd64/arm64 for deb, x86_64/aarch64 for rpm +# and apk). +# VERSION the crate version, e.g. 0.1.0 +# BINDIR directory containing the extracted, statically linked binary +name: mapshoot +arch: ${ARCH} +platform: linux +version: ${VERSION} +version_schema: semver +section: utils +priority: optional +maintainer: Mirko Maischberger +vendor: Mirko Maischberger +homepage: https://github.com/baol/mapshoot +license: MIT OR Apache-2.0 +description: | + Native Web Mercator map images from HERE, OpenStreetMap, CARTO, or XYZ PNG + tiles, with GeoJSON overlays. + mapshoot fetches raster tiles from an online provider, composites a GeoJSON + overlay, and writes a single PNG. Tiles are drawn on the CPU with tiny-skia, + so no GPU, display server, or browser is required. The binary is statically + linked and has no runtime dependencies. + +contents: + - src: ${BINDIR}/mapshoot + dst: /usr/bin/mapshoot + # nFPM only expands ${...} in a content entry when it is opted in. + expand: true + file_info: + mode: 0o755 + + - src: docs/mapshoot.1 + dst: /usr/share/man/man1/mapshoot.1 + file_info: + mode: 0o644 + + # Documentation and licenses are installed 0644 regardless of the local umask. + - src: README.md + dst: /usr/share/doc/mapshoot/README.md + file_info: + mode: 0o644 + - src: packaging/copyright + dst: /usr/share/doc/mapshoot/copyright + file_info: + mode: 0o644 + - src: LICENSE-MIT + dst: /usr/share/doc/mapshoot/LICENSE-MIT + file_info: + mode: 0o644 + - src: LICENSE-APACHE + dst: /usr/share/doc/mapshoot/LICENSE-APACHE + file_info: + mode: 0o644 + # OFL 1.1 requires the license text to accompany the embedded marker font. + - src: assets/OFL.txt + dst: /usr/share/doc/mapshoot/OFL.txt + file_info: + mode: 0o644 + +# Dependencies are intentionally empty: the binary is statically linked against +# musl, so the package has no runtime requirements at all. nFPM never adds any +# on its own, which keeps the .deb installable on Debian 10+ / Ubuntu 18.04+ and +# the .rpm installable across Fedora, RHEL, Alma, Rocky and openSUSE. Should a +# per-format dependency list ever be needed, it goes under an `overrides:` key.