Overview
Start Here
Installation
Tutorial
Architect App Builder
Todo List App
Beacon Beats Audio Store
UCAL App
Authoring
Dynamic Apps
Static Apps
dev_docs
Why Pharos Feels Different
Architect Builder
Framework
Artifacts & Layout
Configuration
Outbound Email
How to Use CLI
Contracts
YAML Authoring
Action Hooks and Middleware
Feature Transaction Primitives
Generated Surfaces
Declarative CRM
Input Validation
Identity and Tenancy
UI Surface Library
Social Connections
Payment Provider Management
Integration Adapters
Reference
Contract, UI, and Surface Reference
Styling UI Elements
Architect Media Artifacts
API Docs
Use Cases
Dynamic SPAs
Generated Admin and APIs
Scheduling and Marketplaces
Multi-App Hosting
Release Notes
Vision
Pharos Framework

← Back

Generated Artifacts

Pharos writes build, package, cache, and validation output into a small set of predictable directories.

The directories are intentionally split by responsibility:

  • dist/ is the stable Pharos artifact surface used by the CLI, runtime, packaging, release checks, and human operators.
  • target/ is the Rust/Cargo compiler cache and intermediate build tree.
  • tmp/ is the repo-local scratch space for disposable local validation runs.

Canonical output layout

Built app artifacts

Built apps live under:

  • dist/apps/<app_id>/

Examples:

  • dist/apps/dev_docs/
  • dist/apps/dynamic_app/
  • dist/apps/static_app/
  • dist/apps/ucal/

Native binaries

Native runtime builds live under:

  • dist/native/<target_id>/

Examples:

  • dist/native/linux-x86_64-gnu/
  • dist/native/macos-x86_64/
  • dist/native/macos-arm64/

Packages

Packaged release outputs live under:

  • dist/packages/

Rust compiler cache

Rust compiler outputs and dependency caches live under:

  • target/

Examples:

  • target/debug/
  • target/release/
  • target/x86_64-apple-darwin/release/

target/ is not the canonical Pharos runtime artifact contract. It is an implementation detail of Cargo and may change shape across target triples, profiles, and toolchain behavior.

Reports

Generated command and validation reports live under:

  • dist/reports/

Temporary validation workspaces

Disposable local validation and staging workspaces should live under:

  • tmp/

Use tmp/ for ad hoc validation runs so it is obvious those outputs are removable and separate from final build artifacts.

Typical build flow

pharos build app dev_docs --build-dir dist
pharos build app ucal --build-dir dist

That produces artifact trees such as:

dist/apps/dev_docs/
dist/apps/ucal/

Package-ready app build flow

For database-backed apps that are about to be archived or deployed, build with packaging mode:

pharos build app ucal --build-dir dist --packaging

That still emits the final app artifact under:

dist/apps/ucal/

But the temporary isolated build-time runtime state is kept under:

dist/deploy-build/ucal/

This separation matters because packaging mode prevents build-time database and runtime-state work from using live-path defaults like /var/lib/pharos/ucal.sqlite3 and /var/state/pharos/ucal/runtime-state.json on the developer machine.

Package flow

Package builds consume the built app artifacts and native runtime outputs rather than raw source app roots.

Typical package-related outputs include:

  • dist/packages/*.deb
  • dist/native/<target_id>/pharos

Why dist/ stays separate from target/

Pharos keeps the split on purpose.

  • dist/ is the user-facing contract. The runtime resolves app artifacts from dist/apps/<app_id>, native packaging and evidence flows use dist/native/, and release docs and verification scripts already depend on those paths.
  • target/ is optimized for incremental Rust compilation, not for stable packaged outputs. It contains profile-specific and target-specific compiler products that are not suitable as the single contract path for app artifacts, release bundles, or validation reports.
  • Collapsing all artifact generation into target/ would mix Cargo internals with Pharos runtime artifacts, force widespread contract churn across scripts and docs, and make non-Rust outputs such as built apps and release bundles harder to reason about.

Current policy:

  • Keep target/ for Cargo-owned compiler products and dependency caches.
  • Keep dist/ for Pharos-owned artifacts, release bundles, docs output, and verification evidence.
  • Keep tmp/ for disposable local validation staging.

What should not be checked in

Most dist/, target/, and tmp/ output is generated and should remain untracked.

In particular:

  • Ad hoc scratch directories
  • Temporary validation output
  • Manually created test directories
  • Generated Rustdoc HTML under dist/apps/dev_docs/html/

The repository now treats tmp/ as the preferred home for removable local test output.

What is durable in practice

Some generated outputs may be retained locally because they are useful for release work or validation review, but they are still build artifacts rather than source of truth.

The app source of truth remains in:

  • apps/<app_id>/
  • docs/
  • src/
  • data/