You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+44-11Lines changed: 44 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,28 +29,58 @@ Operating System
29
29
30
30
## Quick Start
31
31
32
+
The canonical project-mode structure is demonstrated in `examples/hello-app/`:
33
+
34
+
**examples/hello-app/spore.toml:**
35
+
```toml
36
+
[package]
37
+
name = "hello-app"
38
+
version = "0.1.0"
39
+
type = "application"
40
+
spore-version = ">=0.1.0"
41
+
42
+
[project]
43
+
platform = "basic-cli"
44
+
default-entry = "app"
45
+
46
+
[entries.app]
47
+
path = "main.sp"
48
+
49
+
[capabilities]
50
+
allow = ["Compute"]
51
+
52
+
[dependencies]
53
+
basic-cli = { path = "../.." }
54
+
```
55
+
56
+
**examples/hello-app/src/main.sp:**
32
57
```spore
33
-
/// A simple "Hello World" using the basic-cli platform.
58
+
import basic_cli.stdout as stdout
59
+
34
60
fn main() -> () uses [Console] {
35
-
println("Hello from Spore basic-cli!")
61
+
println("Hello from a project-mode Spore application!")
62
+
return
36
63
}
37
64
```
38
65
66
+
**Run the project:**
39
67
```bash
40
-
spore check examples/hello.sp
41
-
spore build examples/hello.sp
42
-
spore run examples/hello.sp
68
+
cdexamples/hello-app
69
+
spore check src/main.sp
70
+
spore run src/main.sp
43
71
```
44
72
45
-
This repository currently keeps `examples/` limited to files that PR CI validates today.
73
+
This is a real package-backed application. The in-repo example points `basic-cli` at `../..`; projects generated by `spore new` vendor the package and use `vendor/basic-cli` instead. The formatter currently normalizes the import to `import basic_cli.stdout as stdout`, while `println` still resolves directly in scope.
74
+
75
+
For quick experiments, you can also run standalone `.sp` files (see `examples/hello.sp`), but production applications should use the project-mode structure above.
46
76
47
77
## Project Structure
48
78
49
79
```
50
80
basic-cli/
51
81
├── spore.toml # Platform manifest
52
82
├── src/
53
-
│ ├── host.sp # Compatibility runtime entry point
83
+
│ ├── host.sp # Legacy compatibility shim
54
84
│ ├── platform_contract.sp
55
85
│ └── basic_cli/ # Spore API modules, checked and built in CI
56
86
│ ├── stdout.sp # Standard output operations
@@ -75,13 +105,14 @@ The current Platform contract MVP is intentionally split across two artifacts:
75
105
- a hole-backed `main` function carries the authoritative startup signature
76
106
-`main_for_host` is the Platform-owned adapter that receives the application startup function
77
107
78
-
Applications targeting `basic-cli` must implement the same startup function name/signature in their entry module. When the compiler starts reading Platform contracts from packages, `spec` items attached to the Platform contract and the application implementation will both have to hold.
108
+
Applications targeting `basic-cli` must implement the same startup function name/signature in their entry module. The current compiler already resolves the package's `[platform]` metadata and `src/platform_contract.sp` to validate that startup shape. Runtime support is currently specialized to package-backed `basic-cli`: imported `basic_cli.*` foreign functions route through the built-in basic-cli host profile, while generic `handles` enforcement and startup `spec` stacking are still follow-up work.
79
109
80
-
`src/host.sp` remains as a compatibility copy of the adapter while the compiler still hardcodes platform startup behavior.
110
+
`src/host.sp` remains as a compatibility copy of the adapter for older references; current manifest-backed projects use `src/platform_contract.sp`.
81
111
82
112
## Tutorial Contract
83
113
84
-
-`examples/` is for truthful, CI-validated examples only.
114
+
-`examples/hello-app/` is the **canonical project-mode example** — it is formatted, checked, built, and run in CI.
115
+
-`examples/hello.sp` is a minimal standalone file for quick experiments (also validated in CI).
85
116
-`src/basic_cli/` is the API surface for the platform modules themselves.
86
117
-`src/platform_contract.sp` is the package-owned startup contract surface.
87
118
- Only add `tests/` when the repo has real Spore-side regression coverage worth running with `spore test`.
@@ -105,7 +136,9 @@ Following Spore's [SEP-0003 (Effect Capability System)](https://github.com/spore
105
136
106
137
🚧 **Early development** — API is unstable and subject to change.
107
138
108
-
At the moment, the validated example is `examples/hello.sp`. More ambitious host-backed demos such as environment/file workflows should stay out of `examples/` until the current platform import/runtime architecture supports them honestly.
139
+
The canonical example is the **package-backed project-mode**`examples/hello-app/` application. It already validates and runs with `[project].platform = "basic-cli"`, an in-repo path dependency, and `import basic_cli.stdout`.
140
+
141
+
The standalone file example (`examples/hello.sp`) stays around for quick experiments. The main remaining platform gaps are generic `handles` enforcement, startup `spec` stacking, and lifting the runtime from its current explicit `basic-cli` host profile to a more general package-backed mechanism.
0 commit comments