aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKylie McClain <kylie@somas.is>2020-07-08 01:00:40 -0400
committerKylie McClain <kylie@somas.is>2020-07-08 01:13:58 -0400
commit6c7713308c9d62d116ca326246ca24a4337f196d (patch)
tree6e93680f1dec6b4187f0d4038462227e13d68369
parente5e50c1fa805bee8c34ed70b2b26fd9a3b3dd6e1 (diff)
downloadpraxis-6c7713308c9d62d116ca326246ca24a4337f196d.tar.gz
praxis-6c7713308c9d62d116ca326246ca24a4337f196d.tar.xz
praxis-6c7713308c9d62d116ca326246ca24a4337f196d.zip
theory(5): move "Phases" to be under "Packages"; flesh it out some more
-rw-r--r--theory.5.adoc30
1 files changed, 19 insertions, 11 deletions
diff --git a/theory.5.adoc b/theory.5.adoc
index 1ff1fef..2789825 100644
--- a/theory.5.adoc
+++ b/theory.5.adoc
@@ -183,19 +183,17 @@ src_install() {
}
----
-[#build]
-== Building
-
-This section is about the environment a package is built in.
+[#pkg-phases]
+=== Phases
-When referring to a "build environment", this document is referring to the literal shell environment
-which the shell process is running in. This means it consists of things such as variables,
-functions, and the current working directory.
+The process of package building is split up into phases. Splitting up into phases allows for easier,
+more precise debugging, and also for sandboxing of specific parts of the build process.
-[#build-phases]
-=== Phases
+Additionally, we split things more than some other package formats do. Many formats only define
+three (build, test, install) or four phases (prepare, build, check, package), or might not even have
+phases.
-Everything in this section is *required* of any package manager implementation. If this isn't
+Everything in this section is required of any package manager implementation. If this isn't
adhered to, we'll have issues with some packages building in one implementation but not another.
"By default" refers to a package which does not define any phases or import any libraries which
@@ -206,7 +204,8 @@ defined, regardless of if they have any function; if a phase listed here is not
the package manager, or the package (or a library used by the package), the package manager *must*
error out and fail, because that is an invalid package.
-"Does nothing" would mean something like `pkg_init() { true; }`.
+"Does nothing" would mean something like `pkg_init() { true; }`; a no-op.
+
"Not defined" would mean no definition of the function.
(ex. Attempting to run function that is not defined would give an unknown command error)
@@ -317,6 +316,15 @@ the package is merged.
By default it does nothing.
+[#build]
+== Building
+
+This section is about the environment a package is built in.
+
+When referring to a "build environment", this document is referring to the literal shell environment
+which the shell process is running in. This means it consists of things such as variables,
+functions, and the current working directory.
+
=== Directories
The only requirements of the directory in which a package build is executed is that it is read-write