building/setup

196 notes in this subject, read out of this brain and free to use. This is page 3 of 4.

Build command for Microsoft Store with offline installer config

To build for Microsoft Store with offline installer configuration, run: npm run tauri build -- --no-bundle followed by npm run tauri bundle -- --config src-tauri/tauri.microsoftstore.conf.json. This allows separate bundling for Microsoft Store versus other Windows installer distributions.

Microsoft Store requires Offline Installer webview mode

The Windows installer distributed through the Microsoft Store must use the Offline Installer Webview2 installation option. This can be configured in a separate tauri configuration file with webviewInstallMode type set to offlineInstaller.

Microsoft Store app registration process

After enrolling as a developer with your Microsoft account, you need to register your app in the Apps and Games page on partner.microsoft.com. Click New Product, select EXE or MSI app, and reserve a unique name for your app.

Install snapcraft

Run 'sudo snap install snapcraft --classic' to install snapcraft.

Snapcraft prerequisites for Debian

To install snap on Debian, run 'sudo apt install snapd'.

Snapcraft prerequisites for Arch

To install snap on Arch, run: sudo pacman -S --needed git base-devel; git clone https://aur.archlinux.org/snapd.git; cd snapd; makepkg -si; sudo systemctl enable --now snapd.socket; sudo systemctl start snapd.socket; sudo systemctl enable --now snapd.apparmor.service.

Snapcraft prerequisites for Fedora

To install snap on Fedora, run 'sudo dnf install snapd' and 'sudo ln -s /var/lib/snapd/snap /snap'. Then reboot the system.

Install core22 base snap

Run 'sudo snap install core22' to install a base snap.

Snapcraft configuration prerequisites

Before creating a snapcraft.yaml file, create a UbuntuOne account and register an app name on the Snapcraft website at https://snapcraft.io.

snapcraft.yaml structure and fields

The snapcraft.yaml file contains: name (required, must match registered app name), base (e.g. core22), version (should be updated with each source change), summary (79 characters maximum), description, grade (e.g. stable), confinement (e.g. strict), layout (optional, defines filesystem bindings), apps (exposes desktop and binary files for running the app), package-repositories (adds package repositories for dependencies), parts (defines build configuration with plugin type, build-snaps, build-packages, stage-packages, source, and override-build commands).

snapcraft.yaml layout section for webkit2gtk

To include webkit2gtk-4.1 in the snap, add the layout section: layout:\n /usr/lib/$SNAPCRAFT_ARCH_TRIPLET/webkit2gtk-4.1:\n bind: $SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/webkit2gtk-4.1

snapcraft.yaml apps section structure

The apps section defines app configuration with: command (required, path to binary), desktop (path to .desktop file), extensions (e.g. [gnome]), plugs (optional, device/service access), slots (optional, interfaces exposed to other snaps).

snapcraft.yaml single-instance plugin configuration

For the single-instance plugin, add slots and plugs sections with interface dbus, bus session, and name in format 'org.net_mydomain_MyApp.SingleInstance' where net_mydomain_MyApp is the app ID with underscores instead of dots and hyphens. See https://v2.tauri.app/plugin/single-instance/ for details.

snapcraft.yaml gnome extension included plugs

The gnome extension in snapcraft.yaml automatically includes these plugs: desktop, desktop-legacy, gsettings, opengl, wayland, x11, mount-observe, calendar-service.

snapcraft.yaml build dependencies

Standard build packages for a Tauri snap include: libwebkit2gtk-4.1-dev, build-essential, curl, wget, file, libxdo-dev, libssl-dev, libayatana-appindicator3-dev, librsvg2-dev, dpkg. Build snaps include: node/20/stable, rustup/latest/stable.

snapcraft.yaml runtime dependencies

Standard stage packages (runtime dependencies) for a Tauri snap include: libwebkit2gtk-4.1-0, libayatana-appindicator3-1.

snapcraft.yaml override-build section example

The override-build section runs commands after sources are pulled. For Tauri, it typically contains: set -eu; npm install; npm run tauri build -- --bundles deb; dpkg -x src-tauri/target/release/bundle/deb/*.deb $SNAPCRAFT_PART_INSTALL/; sed -i -e 's|Icon=appname|Icon=/usr/share/icons/hicolor/32x32/apps/appname.png|g' $SNAPCRAFT_PART_INSTALL/usr/share/applications/appname.desktop

Build a Tauri snap

Run 'sudo snapcraft' from the project root to build the snap.

Test a Tauri snap

Run 'snap run your-app' to test the snap after building.

Manually release a Tauri snap

To manually release a snap: run 'snapcraft login' with UbuntuOne credentials, then run 'snapcraft upload --release=stable mysnap_latest_amd64.snap' to upload to the stable channel.

Automatically build and release Tauri snap via GitHub

To automatically build and release a snap: on the app's developer page in Snapcraft, click the 'builds' tab, click 'login with github', and enter the repository details.

RPM script configuration in tauri.conf.json

Configure RPM lifecycle scripts in `tauri.conf.json` under `bundle.linux.rpm` with these fields: `preInstallScript`, `postInstallScript`, `preRemoveScript`, and `postRemoveScript`. Each field should contain the full path to the corresponding script file.

Cross-compile Tauri for ARMv8/ARM64 (64-bit ARM)

To cross-compile for ARMv8 (ARM64): install Rust target with `rustup target add aarch64-unknown-linux-gnu`, install linker with `sudo apt install gcc-aarch64-linux-gnu`, add `[target.aarch64-unknown-linux-gnu]` with `linker = "aarch64-linux-gnu-gcc"` to `<project-root>/.cargo/config.toml`, enable architecture with `sudo dpkg --add-architecture arm64`, install webkitgtk with `sudo apt install libwebkit2gtk-4.1-dev:arm64`, optionally install OpenSSL headers with `sudo apt install libssl-dev:arm64`, export `PKG_CONFIG_SYSROOT_DIR=/usr/aarch64-linux-gnu/`, then build with `cargo tauri build --target aarch64-unknown-linux-gnu`.

OpenSSL vendored feature for ARM cross-compilation

When cross-compiling for ARM and getting OpenSSL development header errors, either install system-wide OpenSSL headers for the target architecture or enable the vendored OpenSSL feature in `Cargo.toml` by adding: `openssl-sys = {version = "0.9", features = ["vendored"]}`.

RPM package build output directory

When building an RPM package with Tauri, the compiled package is placed in the `src-tauri/target/release/bundle/rpm` directory.

RPM pre/post install and remove scripts folder structure

Create a `scripts` folder in the `src-tauri` directory to store RPM lifecycle scripts. The script files should be named: `preinstall.sh`, `postinstall.sh`, `preremove.sh`, and `postremove.sh`. These scripts receive a parameter indicating the operation type (install, upgrade, or uninstall).

Cross-compile Tauri for ARMv7 (32-bit ARM)

To cross-compile for ARMv7: install Rust target with `rustup target add armv7-unknown-linux-gnueabihf`, install linker with `sudo apt install gcc-arm-linux-gnueabihf`, add `[target.armv7-unknown-linux-gnueabihf]` with `linker = "arm-linux-gnueabihf-gcc"` to `<project-root>/.cargo/config.toml`, enable architecture with `sudo dpkg --add-architecture armhf`, install webkitgtk with `sudo apt install libwebkit2gtk-4.1-dev:armhf`, optionally install OpenSSL headers with `sudo apt install libssl-dev:armhf`, export `PKG_CONFIG_SYSROOT_DIR=/usr/arm-linux-gnueabihf/`, then build with `cargo tauri build --target armv7-unknown-linux-gnueabihf`.

RPM debug commands for package inspection

Use these commands to debug RPM packages: `rpm -qip package_name.rpm` (get general package info), `rpm -qp --queryformat '[%{NAME} %{VERSION} %{RELEASE} %{ARCH} %{SIZE}\n]' package_name.rpm` (query specific fields), `rpm -qlp package_name.rpm` (list all files), `rpm -qp --scripts package_name.rpm` (show pre/post scripts), `rpm -qp --requires package_name.rpm` (check dependencies), `rpm -q --whatrequires package_name.rpm` (list packages depending on this one), `rpm -ivvh package_name.rpm` (install with very verbose output), `rpm -Uvvh package_name.rpm` (upgrade with very verbose output).

RPM build baseline system requirements for glibc compatibility

Build Tauri applications on the oldest base system intended for support that provides WebKitGTK 4.1. Ubuntu 22.04 and Debian 12 are suitable baselines as they include `libwebkit2gtk-4.1-dev` from standard repositories. Building on newer systems raises the minimum glibc version required, causing runtime errors like `/usr/lib/libc.so.6: version 'GLIBC_2.33' not found` on older systems. Docker containers or GitHub Actions are recommended for consistent Linux builds.

Add license to RPM package via Cargo.toml and tauri.conf.json

Set license in `src-tauri/Cargo.toml` using the `license` field in the `[package]` section (e.g., `license = "MIT"`). In `tauri.conf.json` under `bundle`, set `license` field to the license type and `licenseFile` field to the relative path to the license file.

RPM RpmConfig options: conflicts, depends, provides, files, obsoletes, desktopTemplate, epoch

The `tauri.conf.json` `bundle.linux.rpm` configuration supports: `conflicts` (array of package names to prevent installation), `depends` (array of required dependencies), `provides` (array of RPM dependencies this app provides), `files` (object specifying files to include), `obsoletes` (array of packages to remove if present), `desktopTemplate` (path to custom desktop file), and `epoch` (integer defining weighted version comparison). Epoch is not recommended unless necessary as it alters package manager version comparison behavior.

Cross-compile Windows NSIS installer on macOS

To cross-compile Windows NSIS installers on macOS, install NSIS with 'brew install nsis'.

Install LLVM and LLD linker for Windows cross-compilation

For Windows cross-compilation from Linux or macOS, install LLVM and the LLD linker. On Ubuntu run 'sudo apt install lld llvm'. On macOS run 'brew install llvm' and add /opt/homebrew/opt/llvm/bin to your PATH. The llvm-rc binary is needed to compile Windows Resource files for setting the app icon.

Install Windows Rust target for cross-compilation

For cross-compilation to 64-bit Windows systems, run 'rustup target add x86_64-pc-windows-msvc'. For 32-bit, run 'rustup target add i686-pc-windows-msvc'. For ARM64, run 'rustup target add aarch64-pc-windows-msvc'.

Install cargo-xwin for Windows cross-compilation

Use 'cargo install --locked cargo-xwin' to install cargo-xwin, which will be used as Tauri's runner for cross-compilation. By default it downloads Windows SDKs into a project-local folder. Set the XWIN_CACHE_DIR environment variable to share those files across multiple projects.

Build Windows app on Linux/macOS with cargo-xwin

To build for Windows from Linux or macOS, run 'npm run tauri build -- --runner cargo-xwin --target x86_64-pc-windows-msvc'. The build output will be in 'target/x86_64-pc-windows-msvc/release/bundle/nsis/'.

Build Windows 32-bit installer

To build for 32-bit Windows machines, run 'npm run tauri build -- --target i686-pc-windows-msvc'. First install the 32-bit Windows toolchain with 'rustup target add i686-pc-windows-msvc'.

Build Windows ARM64 installer

To build for ARM64 Windows, first open Visual Studio Installer, click Modify, go to Individual Components tab, and install the C++ ARM64 build tools (exact name in VS2022: 'MSVC v143 - VS 2022 C++ ARM64 build tools (Latest)'). Then run 'rustup target add aarch64-pc-windows-msvc' and build with 'npm run tauri build -- --target aarch64-pc-windows-msvc'. Note that the NSIS installer itself runs as x86 via emulation on ARM machines, but the app is a native ARM64 binary.

Enable Windows 7 support for Notification API

To use the Notification API in Windows 7, enable the 'windows7-compat' Cargo feature by adding 'tauri-plugin-notification = { version = "2.0.0", features = [ "windows7-compat" ] }' to Cargo.toml.

FIPS Compliance for MSI bundle

If your system requires the MSI bundle to be FIPS compliant, set the TAURI_BUNDLER_WIX_FIPS_COMPLIANT environment variable to 'true' before running 'tauri build'. In PowerShell, use '$env:TAURI_BUNDLER_WIX_FIPS_COMPLIANT="true"'.

WebView2 installation methods comparison

Windows installers support four WebView2 installation methods: (1) downloadBootstrapper (default, 0MB overhead, requires internet, not recommended for Windows 7 .msi); (2) embedBootstrapper (~1.8MB overhead, requires internet, better Windows 7 support); (3) offlineInstaller (~127MB overhead, no internet required, recommended for offline environments); (4) fixedVersion (~180MB overhead, no internet required, embeds specific WebView2 version); (5) skip (0MB overhead, no internet, not recommended as app will not work without WebView2 pre-installed).

WebView2 runtime on Windows 10/11

On Windows 10 (April 2018 release or later) and Windows 11, the WebView2 runtime is distributed as part of the operating system.

Configure downloadBootstrapper WebView2 mode

The default WebView2 installation mode is downloadBootstrapper. Configure it in tauri.conf.json with: {"bundle": {"windows": {"webviewInstallMode": {"type": "downloadBootstrapper"}}}}

Configure embedBootstrapper WebView2 mode

To embed the WebView2 Bootstrapper, configure in tauri.conf.json with: {"bundle": {"windows": {"webviewInstallMode": {"type": "embedBootstrapper"}}}} This increases installer size by ~1.8MB but improves Windows 7 compatibility.

Configure offlineInstaller WebView2 mode

To embed WebView2 offline installer, configure in tauri.conf.json with: {"bundle": {"windows": {"webviewInstallMode": {"type": "offlineInstaller"}}}} This increases installer size by ~127MB but allows installation without internet connection.

Configure fixedVersion WebView2 mode

To bundle a fixed WebView2 runtime version: (1) Download the runtime from https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section; (2) Extract to src-tauri folder: 'Expand .\Microsoft.WebView2.FixedVersionRuntime.128.0.2739.42.x64.cab -F:* ./src-tauri'; (3) Configure in tauri.conf.json: {"bundle": {"windows": {"webviewInstallMode": {"type": "fixedRuntime", "path": "./Microsoft.WebView2.FixedVersionRuntime.98.0.1108.50.x64/"}}}}

Configure skip WebView2 mode

To remove WebView2 Runtime download check from installer, configure in tauri.conf.json with: {"bundle": {"windows": {"webviewInstallMode": {"type": "skip"}}}} Warning: Your application will not work if the user does not have the runtime installed.

Configure NSIS perMachine install mode

To configure system-wide installation in NSIS, set in tauri.conf.json: {"bundle": {"windows": {"nsis": {"installMode": "perMachine"}}}}

Set minimum WebView2 version requirement

To specify a minimum WebView2 version for features like custom URI schemes, configure in tauri.conf.json: {"bundle": {"windows": {"minimumWebview2Version": "110.0.1531.0"}}} The Windows installer will verify the WebView2 version and run the bootstrapper if it does not match.

WiX MSI installer customization options

The .msi Windows Installer is built using WiX Toolset v3. It can be customized through pre-defined configurations in tauri.conf.json, using a custom WiX source file (.wxs), or through WiX fragments (.wxs files defining registry entries, features, or other components).

WiX installer template uses Handlebars

The default WiX installer template uses Handlebars templating, allowing Tauri CLI to brand your installer according to tauri.conf.json definitions. The default template is at https://github.com/tauri-apps/tauri/blob/dev/crates/tauri-bundler/src/bundle/windows/msi/main.wxs

Replace WiX installer with custom template

To use a completely custom WiX installer, create a .wxs file and configure it in tauri.conf.json at 'tauri.bundle.windows.wix.template'.

WiX fragment example: registry entries

A WiX fragment example creating registry entries: The fragment defines a Component with a unique Id, placed in a DirectoryRef. Registry keys use Root="HKCU" for HKEY_CURRENT_USER. Tauri uses the second portion of bundle identifier as the company name (e.g., 'tauri-apps' in 'com.tauri-apps.test'). Registry path becomes: HKEY_CURRENT_USER\Software\MyCompany\MyApplicationName

Configure WiX fragment in tauri.conf.json

To use WiX fragments, save .wxs files in src-tauri/windows/fragments/ and reference in tauri.conf.json: {"bundle": {"windows": {"wix": {"fragmentPaths": ["./windows/fragments/registry.wxs"], "componentRefs": ["MyFragmentRegistryEntries"]}}}} You must also reference component/feature/merge element ids using componentRefs, componentGroupRefs, featureRefs, featureGroupRefs, or mergeRefs respectively.

NSIS hook example: installing dependencies

NSIS hooks can install system dependencies like Visual C++ Redistributables. Example checks if dependency is installed via registry, copies it from $INSTDIR\resources to $TEMP, executes the installer with passive/quiet flags and /norestart to prevent reboots, checks exit code, and cleans up temporary files. Best practices: always check if dependency is already installed; use passive/quiet/silent flags; include /norestart; clean up temp files; handle installation failures gracefully.

NSIS install modes

NSIS supports three install modes: (1) default/currentUser: installs for current user only in %LOCALAPPDATA%, does not require admin privileges; (2) perMachine: system-wide installation in C:/Program Files, requires admin privileges; (3) both: user chooses between current user or system-wide, requires admin privileges.

Configure NSIS both install modes

To let users choose between current user or system-wide installation in NSIS, set in tauri.conf.json: {"bundle": {"windows": {"nsis": {"installMode": "both"}}}} Note that the installer will require Administrator privileges to execute.

Build command for Windows installer

Run 'npm run tauri build' (or equivalent for your package manager) on a Windows computer to build and bundle your app into a Windows installer.

NSIS internationalization

The NSIS installer is multi-language, containing all selected translations in a single installer. Specify languages using tauri.bundle.windows.nsis.languages property. A list of supported languages is available in NSIS GitHub project. By default the operating system default language is used. You can configure a language selector with displayLanguageSelector: true.

Configure NSIS language selector

To display a language selector in the NSIS installer before the installer contents are rendered, set in tauri.conf.json: {"bundle": {"windows": {"nsis": {"displayLanguageSelector": true}}}}

Give your agent this brain