provs/doc/ForDevelopers.md

35 lines
1.3 KiB
Markdown
Raw Normal View History

2022-02-26 20:13:12 +00:00
# Information for developers
2022-04-19 15:35:26 +00:00
## Create a provs jar-file
2022-02-26 20:13:12 +00:00
* Clone this repo
* Build the jar-file by `./gradlew uberjarDesktop`
2022-04-19 15:35:26 +00:00
* In folder build/libs you'll find the file `provs-desktop.jar`
2022-02-26 20:13:12 +00:00
2022-04-19 15:35:26 +00:00
This uberjar is a Java jar-file including all required dependencies.
2022-02-26 20:13:12 +00:00
2022-04-19 15:35:26 +00:00
## Task
```kotlin
2023-09-09 10:47:03 +00:00
fun Prov.provisionK3s() = task { /* ... code and subtasks come here ... */ }
2022-04-19 15:35:26 +00:00
```
2022-04-19 17:37:25 +00:00
If you're having a deeper look into the provs code, you'll see regularly a task definition like this and might wonder ...
2022-04-19 15:35:26 +00:00
### What is a task ?
A task is the **basic execution unit** in provs. When executed, each task produces exactly one result (line) with either success or failure.
The success or failure is computed automatically in the following way:
* a **task** fails if it calls subtasks and if at least one subtask has failed
* a **taskWithResult** works the same except that it requires an additional result to be returned which is also included in the success calculation
* a task defined with **optional** (i.e. `= optional { /* ... */ }` always returns success (even if there are failing subtasks)
* **requireLast** defines a task which must provide an explicit result and solely this result counts for success calculation
2022-04-19 17:37:25 +00:00
## Call hierarchy
2023-02-24 14:59:48 +00:00
In the following link you can find an example of a sequence diagram when provisioning a desktop:
2022-04-19 17:37:25 +00:00
2023-02-24 14:59:48 +00:00
[ProvisionDesktopSequence.md](ProvisionDesktopSequence.md)