bQUARKz
f9120e740b
Co-authored-by: Nilton Constantino <nilton.constantino@visma.com> Reviewed-on: #8
269 lines
4.0 KiB
Markdown
269 lines
4.0 KiB
Markdown
# Prometeu.json — Project Manifest Specification
|
|
|
|
## Status
|
|
|
|
Draft · Complementary specification to the PBS Linking & Module Model
|
|
|
|
## Purpose
|
|
|
|
`prometeu.json` is the **project manifest** for Prometeu-based software.
|
|
|
|
Its role is to:
|
|
|
|
* Identify a Prometeu project
|
|
* Declare its dependencies
|
|
* Provide **input metadata to the compiler and linker**
|
|
|
|
It is **not** consumed by the Virtual Machine.
|
|
|
|
---
|
|
|
|
## Design Principles
|
|
|
|
1. **Compiler-owned**
|
|
|
|
* Only the Prometeu Compiler reads `prometeu.json`.
|
|
* The VM and runtime never see this file.
|
|
|
|
2. **Declarative, not procedural**
|
|
|
|
* The manifest declares *what* the project depends on, not *how* to resolve it.
|
|
|
|
3. **Closed-world output**
|
|
|
|
* Compilation + linking produce a single, fully resolved bytecode blob.
|
|
|
|
4. **Stable identity**
|
|
|
|
* Project identity is explicit and versioned.
|
|
|
|
---
|
|
|
|
## File Location
|
|
|
|
`prometeu.json` must be located at the **root of the project**.
|
|
|
|
---
|
|
|
|
## Top-level Structure
|
|
|
|
```json
|
|
{
|
|
"name": "my_project",
|
|
"version": "0.1.0",
|
|
"kind": "app",
|
|
"dependencies": {
|
|
"std": {
|
|
"git": "https://github.com/prometeu/std",
|
|
"version": ">=0.2.0"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Fields
|
|
|
|
### `name`
|
|
|
|
**Required**
|
|
|
|
* Logical name of the project
|
|
* Used as the **default module namespace**
|
|
|
|
Rules:
|
|
|
|
* ASCII lowercase recommended
|
|
* Must be unique within the dependency graph
|
|
|
|
Example:
|
|
|
|
```json
|
|
"name": "sector_crawl"
|
|
```
|
|
|
|
---
|
|
|
|
### `version`
|
|
|
|
**Required**
|
|
|
|
* Semantic version of the project
|
|
* Used by the compiler for compatibility checks
|
|
|
|
Format:
|
|
|
|
```
|
|
MAJOR.MINOR.PATCH
|
|
```
|
|
|
|
---
|
|
|
|
### `kind`
|
|
|
|
**Optional** (default: `app`)
|
|
|
|
Defines how the project is treated by tooling.
|
|
|
|
Allowed values:
|
|
|
|
* `app` — executable program
|
|
* `lib` — reusable module/library
|
|
* `system` — firmware / system component
|
|
|
|
---
|
|
|
|
### `dependencies`
|
|
|
|
**Optional**
|
|
|
|
A map of **dependency aliases** to dependency specifications.
|
|
|
|
```json
|
|
"dependencies": {
|
|
"alias": { /* spec */ }
|
|
}
|
|
```
|
|
|
|
#### Alias semantics
|
|
|
|
* The **key** is the name by which the dependency is referenced **inside this project**.
|
|
* It acts as a **rename / namespace alias**.
|
|
|
|
Example:
|
|
|
|
```json
|
|
"dependencies": {
|
|
"gfx": {
|
|
"path": "../prometeu-gfx"
|
|
}
|
|
}
|
|
```
|
|
|
|
Internally, the dependency will be referenced as `gfx`, regardless of its original project name.
|
|
|
|
---
|
|
|
|
## Dependency Specification
|
|
|
|
Each dependency entry supports the following fields.
|
|
|
|
### `path`
|
|
|
|
Local filesystem dependency.
|
|
|
|
```json
|
|
{
|
|
"path": "../std"
|
|
}
|
|
```
|
|
|
|
Rules:
|
|
|
|
* Relative paths are resolved from the current `prometeu.json`
|
|
* Absolute paths are allowed but discouraged
|
|
|
|
---
|
|
|
|
### `git`
|
|
|
|
Git-based dependency.
|
|
|
|
```json
|
|
{
|
|
"git": "https://github.com/prometeu/std",
|
|
"version": "^0.3.0"
|
|
}
|
|
```
|
|
|
|
The compiler is responsible for:
|
|
|
|
* Cloning / fetching
|
|
* Version selection
|
|
* Caching
|
|
|
|
---
|
|
|
|
### `version`
|
|
|
|
Optional version constraint.
|
|
|
|
Examples:
|
|
|
|
* Exact:
|
|
|
|
```json
|
|
"version": "0.3.1"
|
|
```
|
|
|
|
* Range:
|
|
|
|
```json
|
|
"version": ">=0.2.0 <1.0.0"
|
|
```
|
|
|
|
* Latest:
|
|
|
|
```json
|
|
"version": "latest"
|
|
```
|
|
|
|
Semantics are defined by the compiler.
|
|
|
|
---
|
|
|
|
## Resolution Model (Compiler-side)
|
|
|
|
The compiler must:
|
|
|
|
1. Load root `prometeu.json`
|
|
2. Resolve all dependencies recursively
|
|
3. Apply aliasing rules
|
|
4. Detect:
|
|
|
|
* Cycles
|
|
* Version conflicts
|
|
* Name collisions
|
|
5. Produce a **flat module graph**
|
|
6. Invoke the linker to generate a **single Program Image**
|
|
|
|
---
|
|
|
|
## Interaction with the Linker
|
|
|
|
* `prometeu.json` feeds the **module graph**
|
|
* The linker:
|
|
|
|
* Assigns final function indices
|
|
* Fixes imports/exports
|
|
* Emits a closed bytecode image
|
|
|
|
After linking:
|
|
|
|
> No module boundaries or dependency information remain at runtime.
|
|
|
|
---
|
|
|
|
## Explicit Non-Goals
|
|
|
|
This specification does **not** define:
|
|
|
|
* Lockfiles
|
|
* Registry formats
|
|
* Caching strategies
|
|
* Build profiles
|
|
* Conditional dependencies
|
|
|
|
These may be added in future specs.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
* `prometeu.json` is the **single source of truth for project identity and dependencies**
|
|
* Dependency management is **compiler-owned**
|
|
* The VM executes **only fully linked bytecode**
|
|
|
|
This file completes the boundary between **project structure** and **runtime execution**.
|