Skip to content

Commit b92239d

Browse files
JordanMartinezJordanMartinez
authored
Further document spago.yml file format (#954)
1 parent 7684aa7 commit b92239d

File tree

1 file changed

+204
-1
lines changed

1 file changed

+204
-1
lines changed

‎spaghetto/README.md‎

Lines changed: 204 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,204 @@ spago bundle -p spago-bin
2525
./bin/bundle.js bundle -p spago-bin
2626
```
2727

28-
## Spago.yml
28+
## The `spago.yml` configuration file
29+
30+
In general, repositories are not always used to store a single project per repository. Nowadays, there are concepts like [monorepos](https://monorepo.tools/).
31+
32+
To better support [monorepos and multirepos/polyrepos](https://monorepo.tools/), Spago works in terms of "workspaces".
33+
34+
| Term | Meaning | Example |
35+
| - | - | - |
36+
| **Package** | a library or script/application | -- |
37+
| **Dependencies** | libraries used by a **package** | A remote package (e.g. `prelude`) or a local package (e.g. a package in a monorepo) |
38+
| **Backend** | the tool to use to compile PureScript source code to some target language. When this is not defined, source code is compiled to JavaScript via `purs`. | <ul><li>For Erlang, [`purerl`](https://github.com/purerl/purerl)</li><li>For optimized JS, [`purs-backend-es`]()</li><li>... etc.</li></ul> |
39+
| **Workspace** | indicates which **package(s)** using some common source of **dependencies** can be compiled to a language via te same **backend** tool. |
40+
41+
`spago.yml` files can be used primarily in three different ways depending on whether the `workspace` and/or `package` field(s) are used:
42+
43+
| -- | has `workspace` | lacks `workspace` |
44+
| - | - | - |
45+
| has `package` | <ul><li>**Concept**: monorepo root with a single primary application</li><li>**Location**: for normal repos or monorepos, stored in the root directory. For polyrepos, stored in the root folder of that project</li><li>**Usage**: for polyrepos, defines a single backend-specific output target (e.g. Erlang server)</li></ul> | <ul><li>**Concept**: defines another package in a monorepo/polyrepo.</li><li>**Location**: stored in a subdirectory of a folder containing a workspace config file</li><li>**Usage**: usually defines a shared local library used by other local packages or defines a local script to automate some task</li></ul> |
46+
| lacks `package` | <ul><li>**Concept**: monorepo with no single primary application</li><li>**Location**: for monorepos, stored in the root directory.</li><li>**Usage**: defines the backend and source of dependencies used by all other packages in the workspace</li></ul> | invalid `spago.yml` file |
47+
48+
Each idea is further illustrated below:
49+
50+
<details>
51+
<summary>A "normal" repo: a single repository containing one distinct project</summary>
52+
53+
Given this project structure...
54+
```
55+
root
56+
/spago.yml
57+
/src/Main.purs
58+
```
59+
60+
... the `spago.yml` file would look like this:
61+
```yml
62+
package:
63+
name: my-random-number-game
64+
dependencies:
65+
- prelude
66+
- effect
67+
- console
68+
69+
workspace:
70+
package_set:
71+
registry: 11.10.0
72+
```
73+
74+
In other words, there is only 1 package named `my-random-number-game` for this workspace.
75+
76+
</details>
77+
78+
<details>
79+
<summary>A monorepo repo with no single primary application</summary>
80+
81+
Given this project structure...
82+
```sh
83+
root
84+
/spago.yml
85+
# /src/Main.purs # if the repo has a single primary application
86+
/core
87+
/spago.yml
88+
/src/Types.purs
89+
/lib1
90+
/spago.yml
91+
/src/Types.purs
92+
/script1
93+
/spago.yml
94+
/src/Script1/Main.purs
95+
```
96+
97+
... the `spago.yml` files might look like this:
98+
99+
```yml
100+
# root/spago.yml
101+
102+
# if the repo has a single primary application, this is uncommented
103+
#package:
104+
# name: core
105+
# dependencies:
106+
# - prelude
107+
108+
workspace:
109+
package_set:
110+
registry: 11.10.0
111+
```
112+
113+
```yml
114+
# core/spago.yml
115+
package:
116+
name: core
117+
dependencies:
118+
- prelude
119+
```
120+
121+
```yml
122+
# lib/spago.yml
123+
package:
124+
name: lib1
125+
dependencies:
126+
- prelude
127+
- core
128+
```
129+
130+
```yml
131+
# core/spago.yml
132+
package:
133+
name: app1
134+
dependencies:
135+
- prelude
136+
- core
137+
```
138+
139+
```yml
140+
# core/spago.yml
141+
package:
142+
name: app2
143+
dependencies:
144+
- prelude
145+
- core
146+
- lib1
147+
```
148+
149+
</details>
150+
151+
152+
<details>
153+
<summary>A polyrepo: loosely-connected projects</summary>
154+
155+
Given this project structure...
156+
```diff
157+
root
158+
/erlang
159+
/spago.yml
160+
/src/Main.purs
161+
/scripts
162+
/spago.yml
163+
/src/Scripts/Main.purs
164+
/node
165+
/spago.yml
166+
/src/Main.purs
167+
```
168+
169+
... the `spago.yml` files might look like this:
170+
171+
```yml
172+
# root/erlang/spago.yml
173+
package:
174+
name: erlang-app
175+
dependencies:
176+
- prelude
177+
178+
workspace:
179+
package_set:
180+
registry: 11.10.0
181+
backend:
182+
cmd: purerl
183+
```
184+
185+
```yml
186+
# root/node/spago.yml
187+
package:
188+
name: node-app
189+
dependencies:
190+
- prelude
191+
192+
workspace:
193+
package_set:
194+
registry: 11.10.0
195+
backend:
196+
cmd: purs-backend-es
197+
```
198+
199+
</details>
200+
201+
### Finding Packages in a Workspace
202+
203+
- A "workspace" `spago.yml` file is one that *uses* the `workspace` field.
204+
- A "non-workspace" `spago.yml` file is one that *omits* the `workspace` field.
205+
206+
Spago uses "workspace" `spago.yml` files to determine what are all of the packages one could build. Given the following project structure...
207+
208+
```sh
209+
foo
210+
/spago.yml # workspace config file; defines package `foo`
211+
/bar/spago.yml # workspace config file; defines package `bar`
212+
/bar/something.spago.yml # non-workspace file; defines package `something`
213+
/baz/spago.yml # non-workspace config file; defines package `baz`
214+
```
215+
216+
<details>
217+
<summary>The `foo` and `baz` packages can be built when `foo` is the current working directory.</summary>
218+
219+
When ran from the directory `foo`, Spago will search for a "workspace" config file in the current directory. It finds `foo/spago.yml` and sees that it defines the package `foo`. It will then recurse into all subdirectories of `foo`.
220+
- If it finds another "workspace" config file in these subdirectories (e.g. `foo/bar/spago.yml`), it ignores that entire subdirectory. So packages from `foo/bar/spago.yml` and `foo/bar/something/spago.yml` are excluded
221+
- If it finds a "non-workspace" config files (e.g. `foo/baz/spago.yml`), it includes those packages.
222+
223+
At the end of this process, `foo` and `baz` are the only packages considered.
224+
225+
### `spago.yml` fields and their meaning
29226

30227
```yml
31228
# optional
@@ -149,3 +346,9 @@ workspace:
149346
# optional, Boolean, fail the build if `spago.yml` has redundant/missing packages
150347
pedantic_packages: false
151348
```
349+
350+
### FAQs
351+
352+
#### Why switch from `spago.dhall` to `spago.yml`?
353+
354+
See `some link here...`.

0 commit comments

Comments
 (0)