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.