aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKylie McClain <kylie@somas.is>2020-07-07 09:27:57 -0400
committerKylie McClain <kylie@somas.is>2020-07-07 09:33:53 -0400
commit314fe409d5ab0253dcfbdde9b5c48460eaa00f85 (patch)
tree6bf739c768a426dfa702ac21be5ff63bafe8d14c
parent30d92082920447f7b467df753b4c431bd87a1638 (diff)
downloadpraxis-314fe409d5ab0253dcfbdde9b5c48460eaa00f85.tar.gz
praxis-314fe409d5ab0253dcfbdde9b5c48460eaa00f85.tar.xz
praxis-314fe409d5ab0253dcfbdde9b5c48460eaa00f85.zip
theory(5): improvements to "Packages"
- explain the usage of "package" - unwrap "Disambiguation"
-rw-r--r--theory.5.adoc43
1 files changed, 32 insertions, 11 deletions
diff --git a/theory.5.adoc b/theory.5.adoc
index ab9acea..0e6e07a 100644
--- a/theory.5.adoc
+++ b/theory.5.adoc
@@ -88,17 +88,38 @@ Do not add repositories to `dependencies` simply because a package in your repos
in another repository. The package manager should deal with determining what repository needs to be
installed to satisfy a dependency through usage of the <<repo-meta,`universe` meta-repository>>.
+[#repo-packages]
=== Packages
-Repositories *should* contain a directory named `packages`; if they do not, package managers *may*
+Repositories should contain a directory named `packages`; if they do not, package managers can
ignore them entirely, as there's not much use to a repository with no package.
-==== Package specifications
+See the <<pkg,packages>> section for details about what goes on within.
+
+[#pkg]
+== Packages
+
+This term can be a bit overloaded. It's just too useful of a term.
+When I say package, I mean "a collection containing instructions to build a piece of software".
+
+In theory(5), a package means a directory containing an action, libraries, or both. If it's just a
+directory with metadata, it is not a package, because there's no actual build script. And, in fact,
+if you depend on libraries that also don't provide any action file, your directory is not a package.
+
+Why so lenient? Because a package can add actions on top of the actions declared in the libraries it
+uses, and same with metadata. It is a hierarchy of inheritance. It all gets combined to create a
+self-sufficient script, which is what's actually used when building.
+
+Unlike other, simpler formats which provide simpler build scripts, this allows for reducing code
+duplication in a tree of packages.
+
+[#pkg-specifications]
+=== Specifications
Package specifications (informally referred to as "specs") are strings which describe a package.
-Specifications take on multiple permutations, because they are made up of four different parts, of
-which only the name is required.
+Specifications take on multiple permutations, because they are made up of four different parts,
+<<pkg-disambiguation,of which only the name is required>>.
Given the fully-qualified spec `package#1.0::repository`...
@@ -119,15 +140,15 @@ characters. (for `r1`, etc.)
All parts of a package spec are case-sensitive.
-===== Disambiguation
+[#pkg-disambiguation]
+==== Disambiguation
-The only strictly *required* part of a spec is the inclusion of the
-package name. If any other part other than the name is omitted, it will
-be disambiguated in order to determine what packages can satisfy the
-specification given.
+When used as user input, the only strictly *required* part of a spec is the inclusion of the package
+name. If any other part other than the name is omitted, it will be disambiguated in order to
+determine what packages can satisfy it.
-If more than one package matches a specification, the package manager
-*may* prompt the user in some fashion to be more specific.
+If more than one package matches a specification, the package manager *should* prompt the user in
+some fashion to be more specific.
=== Format