randy
5afb130c45
Replace Leaflet/raster tiles with MapLibre GL JS: an online OpenFreeMap style and an offline style built from a local PMTiles archive via pmtiles.js and protomaps-themes-base (no glyphs/labels offline by design, see docs/architecture.adoc). Frontend libraries are vendored locally rather than loaded from a CDN so the app keeps working with no internet access. Also add an animated RainViewer precipitation radar overlay (toggle, play/pause, scrub slider), matching the default time window of the weather-radar-card Home Assistant integration.
110 lines
3.2 KiB
Plaintext
110 lines
3.2 KiB
Plaintext
= Development guide
|
|
:toc:
|
|
:toclevels: 2
|
|
|
|
== Web app only
|
|
|
|
[source,shell]
|
|
----
|
|
bundle install
|
|
bundle exec puma -C config/puma.rb
|
|
----
|
|
|
|
Open http://127.0.0.1:4567. For auto-reload during development, run
|
|
via the `rerun` gem instead:
|
|
|
|
[source,shell]
|
|
----
|
|
bundle exec rerun -- bundle exec puma -C config/puma.rb
|
|
----
|
|
|
|
TIP: Browsers apply heuristic caching to static files even without
|
|
explicit cache headers, so an edit to `public/` (or `views/`) can
|
|
appear not to have taken effect on the next reload. Force a real
|
|
reload (e.g. Ctrl/Cmd+Shift+R) if that happens.
|
|
|
|
== Offline map data
|
|
|
|
To enable the offline style, place a PMTiles file at
|
|
`data/offline.pmtiles` (see `docs/architecture.adoc` for how it is
|
|
served and styled). It is not part of the repository — obtain or
|
|
build one locally:
|
|
|
|
* The simplest source is a pre-built extract from
|
|
https://app.protomaps.com[protomaps.com's extract builder] — pick a
|
|
region and download it as `.pmtiles`. Its schema is what
|
|
`protomaps-themes-base` (the styling library used for the offline
|
|
style) expects.
|
|
* To convert some other vector tile source (e.g. an `.mbtiles` file)
|
|
into PMTiles, use the
|
|
https://github.com/protomaps/go-pmtiles[go-pmtiles] CLI:
|
|
`pmtiles convert in.mbtiles data/offline.pmtiles`.
|
|
|
|
Once the file is in place, `GET /api/offline-tiles` reports
|
|
`available: true` and the map defaults to the offline style.
|
|
|
|
This is picked up automatically for `cargo tauri dev` (it just runs
|
|
the Sinatra app from the project root). To ship it inside a *packaged*
|
|
build, add it to `bundle.resources` in `src-tauri/tauri.conf.json`:
|
|
`"../data/offline.pmtiles": "data/offline.pmtiles"`. Not added by
|
|
default, since these files can be large and are picked per
|
|
deployment.
|
|
|
|
== Desktop shell (Tauri)
|
|
|
|
=== Prerequisites
|
|
|
|
* Rust (stable) and the Tauri CLI: `cargo install tauri-cli --version "^2"`
|
|
* Ruby + Bundler, with gems installed (`bundle install` in the project
|
|
root)
|
|
* Platform build tools required by Tauri itself:
|
|
** *Linux*: WebKitGTK and GTK development packages, e.g. on
|
|
Debian/Ubuntu:
|
|
+
|
|
[source,shell]
|
|
----
|
|
sudo apt install libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1-dev \
|
|
libgtk-3-dev libsoup-3.0-dev build-essential
|
|
----
|
|
** *macOS*: Xcode command line tools.
|
|
** *Windows*: the WebView2 runtime (preinstalled on current Windows) and
|
|
the MSVC build tools.
|
|
|
|
See the upstream https://tauri.app/start/prerequisites/[Tauri
|
|
prerequisites] page for the current package names on your platform.
|
|
|
|
=== Running in development
|
|
|
|
[source,shell]
|
|
----
|
|
cd src-tauri
|
|
cargo tauri dev
|
|
----
|
|
|
|
This runs `beforeDevCommand` (starts Puma on `127.0.0.1:4567`) and
|
|
opens a native window pointed at it, per `src-tauri/tauri.conf.json`.
|
|
|
|
=== Building
|
|
|
|
[source,shell]
|
|
----
|
|
cd src-tauri
|
|
cargo tauri build
|
|
----
|
|
|
|
Requires `Gemfile.lock` to exist (`bundle install` beforehand), since
|
|
the Ruby app files are embedded into the bundle as resources. See
|
|
`docs/architecture.adoc` for the current limitation around this build
|
|
still depending on a system Ruby installation on the target machine.
|
|
|
|
=== Regenerating icons
|
|
|
|
Desktop icons live in `src-tauri/icons/`. To regenerate them from a
|
|
new source image (at least 1024x1024 PNG):
|
|
|
|
[source,shell]
|
|
----
|
|
cd src-tauri
|
|
cargo tauri icon path/to/source.png
|
|
----
|