AdminConsole
Quickstarts/Linux
LinuxEntitlement Required45 minutes

Boot a supervised embedded map client

a health-checked native process with an atomic data/runtime boundary

Entitlement Required

What this path can prove

The public snapshot has no platform-specific Linux distribution guide. The runtime, ABI, compiler, graphics, activation, and data contract must come from the entitled private distribution.

Credential boundary

Use device/workload identity and entitlement delivered through the approved provisioning channel; never bake fleet-wide secrets into an image or package.

Provider-specific implementation intentionally stops here.

No public guide proves this distribution. Obtain the named entitled/private contract, attach its version and fingerprint to the project, then implement only inside the scaffolded adapter.

Before the timer starts

Prepare the exact environment

Do not count account, package, build-host, or device discovery as hidden quickstart work.

  1. 01

    Target CPU, ABI, libc, GPU/graphics, OS image, storage, and sensor manifest

  2. 02

    Entitled runtime, data, license, and activation contract

  3. 03

    A supervised service environment

  4. 04

    Dual-slot storage or another atomic rollback mechanism

Five-stage path

Build one complete result

Each stage has a proof. If the proof is missing, do not advance by assumption.

  1. 01

    Confirm the source line

    Open the linked evidence and confirm the exact Linux package, endpoint, toolchain, region, and account entitlement before installing anything. The public snapshot has no platform-specific Linux distribution guide. The runtime, ABI, compiler, graphics, activation, and data contract must come from the entitled private distribution.

  2. 02

    Create a clean boundary

    Validate runtime/data/compiler compatibility and signatures before installing; run the application with explicit read-only runtime/data and isolated writable state under a supervisor.

  3. 03

    Build one useful result

    Expose liveness, readiness, active runtime/data versions, activation state, and last safe error; render a deterministic offline fixture before enabling live data.

  4. 04

    Run the release path

    Cold boot without network, kill/restart the process, fill staging storage, corrupt a staged package, and interrupt power before/after the atomic activation pointer.

  5. 05

    Break it deliberately

    Exercise missing/denied credentials, unavailable network or runtime, invalid input, cancellation, and cleanup. Show a bounded user-safe failure while retaining a correlation identity for support.

Clean-path commands

Run what will ship

Replace documented placeholders through your environment or secret provider. Commands are scaffolds; platform signing, accounts, packages, and schemes remain project-specific.

$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

$ cmake --build build

$ ctest --test-dir build

$ ./build/mappls_client --self-test
Application-owned seam

Start with code you can replace

The scaffold keeps provider-specific symbols and credentials behind a narrow boundary. Bind the confirmed Mappls source line inside that adapter.

Linux first-success scaffold
struct RuntimeHealth { bool live; bool ready; std::string runtimeVersion; std::string dataVersion; };

class MapRuntime {
public:
  virtual ~MapRuntime() = default;
  virtual RuntimeHealth health() const = 0;
  virtual void renderFixture() = 0;
  virtual void shutdown() noexcept = 0;
};

// The entitled SDK adapter is selected only after manifest and activation checks.
Definition of first success

Verify behavior, not screenshots

  1. 1

    Every test leaves exactly one bootable active runtime/data set and health reports the selected versions without leaking device credentials.

  2. 2

    A blocked, missing, or unentitled provider produces a useful explicit failure rather than a blank surface or fabricated result.

  3. 3

    No server credential, bearer value, precise private fixture, or provider response body appears in client bundles, logs, screenshots, or test artifacts.

  4. 4

    Resources, listeners, sessions, processes, or requests stop cleanly when the owning screen, request, or application ends.

Before productionRuntime/data compatibility is enforcedActivation can rotateUpdates are signed and reversibleHealth survives process restartRuntime and data compatibility is enforcedDevice identity and activation can be rotatedUpdates are signed, resumable, and reversibleHealth and resource telemetry survive application restarts
Fast diagnosis

When first contact fails

Keep the safe provider request identity, resolved package/runtime versions, platform logs, and exact reproduction steps. Never attach credentials or private location payloads.

SignalLikely causeNext action
The process starts but rendering or routing fails on target hardware

ABI/libc/compiler/GPU/runtime/data epoch or activation is incompatible despite a successful file copy.

Compare the signed release manifest to device facts, fail readiness, retain the previous slot, and obtain the exact compatibility decision from the runtime owner.

Authentication or entitlement is rejected

The credential class, restriction, account region, host/path generation, package application, or subscribed capability does not match.

Do not try another credential shape blindly. Capture the safe status/request identity and reconcile the exact contract in the developer console or support packet.

The sample works once but not after reload, backgrounding, or a second run

Lifecycle ownership, listener disposal, token/session refresh, saved state, or a singleton initialization boundary is incomplete.

Instrument create/ready/cancel/destroy transitions and prove one owner before adding product behavior.

Keep building

From first success to a real journey

Choose the next tutorial only after the quickstart verification holds in your release path.