Pharos Framework

← Back

Generated Artifacts

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

Canonical output layout

Built app artifacts

Built apps live under:

  • dist/apps/<app_id>/

Examples:

  • dist/apps/dev_docs/
  • dist/apps/dynamic_app_template/
  • dist/apps/static_app_template/
  • dist/apps/ucal/

Native binaries

Native runtime builds live under:

  • dist/native/<target_id>/

Examples:

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

Packages

Packaged release outputs live under:

  • dist/packages/

Reports

Generated command and validation reports live under:

  • dist/reports/

Temporary scratch output

Disposable test and scratch output should live under:

  • dist/tmp/

Use dist/tmp/ for ad hoc validation runs so it is obvious those outputs are removable.

Typical build flow

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

That produces artifacts 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 --text

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 controller or 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

What should not be checked in

Most dist/ output is generated and should remain untracked.

In particular:

  • ad hoc scratch directories
  • temporary validation output
  • manually created test directories
  • generated Doxygen HTML under docs/html/

The repository now treats dist/tmp/ as the preferred home for removable 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/