aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKylie McClain <kylie@somas.is>2020-07-08 01:12:59 -0400
committerKylie McClain <kylie@somas.is>2020-07-08 01:13:58 -0400
commit3aabb683220950b5654f4ae8f6b440689219451b (patch)
treea21c5507288b85ae626f9e160800bc1a9779d086
parent16911223719a3679bee9942ef5fd49c46681d3a4 (diff)
downloadpraxis-3aabb683220950b5654f4ae8f6b440689219451b.tar.gz
praxis-3aabb683220950b5654f4ae8f6b440689219451b.tar.xz
praxis-3aabb683220950b5654f4ae8f6b440689219451b.zip
theory(5): add idioms section
-rw-r--r--theory.5.adoc20
1 files changed, 20 insertions, 0 deletions
diff --git a/theory.5.adoc b/theory.5.adoc
index 062f7ae..cb65d22 100644
--- a/theory.5.adoc
+++ b/theory.5.adoc
@@ -321,6 +321,26 @@ When referring to a "build environment", this document is referring to the liter
which the shell process is running in. This means it consists of things such as variables,
functions, and the current working directory.
+[#build-idioms]
+=== Idioms
+
+:url-idioms: https://git.mutiny.red/mutiny/idioms
+
+There's one special dependency that someone writing a package should always be able to expect to be
+installed, no matter what: {url-idioms}[`idioms`].
+
+Why is `idioms` used? Because it provides good, general purpose flow control functionality in
+shell scripts. praxis(7) itself uses it.
+
+The main functions that you would use from it when writing a package would be
+<<idioms-call.3.adoc#,idioms-call(3)>>, <<idioms-error.3.adoc#,idioms-error(3)>>,
+<<idioms-warn.3.adoc#,idioms-warn(3)>>, <<idioms-die.3.adoc#,idioms-die(3)>>, and lastly,
+<<idioms-die.3.adoc#,idioms-die(3)>>.
+
+If you're implementing a package manager though and wish to not have the dependency, just
+implement those commands. They're not very complex, and their existence (due to being basically
+included as part of this package API) makes their commands effectively keywords which can be.
+
=== Directories
The only requirements of the directory in which a package build is executed is that it is read-write