aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKylie McClain <kylie@somas.is>2020-07-04 18:11:17 -0400
committerKylie McClain <kylie@somas.is>2020-07-04 18:11:17 -0400
commite6f872d7b678ab3ed79271af26c4350e20dac632 (patch)
treeead24dec45dd3243d1af365ef92b4df076faba09
parent47a9cec628a8a10500e013674a0bdbc98a314140 (diff)
downloadpraxis-e6f872d7b678ab3ed79271af26c4350e20dac632.tar.gz
praxis-e6f872d7b678ab3ed79271af26c4350e20dac632.tar.xz
praxis-e6f872d7b678ab3ed79271af26c4350e20dac632.zip
doc: combine praxis-design(7) with praxis(7)
-rw-r--r--README138
-rw-r--r--praxis-design.7.adoc75
-rw-r--r--praxis.7435
-rw-r--r--praxis.7.adoc119
4 files changed, 682 insertions, 85 deletions
diff --git a/README b/README
index 77609e9..dbaaf48 100644
--- a/README
+++ b/README
@@ -3,7 +3,11 @@ PRAXIS(7) Mutineer's Guide - praxis PRAXIS(7)
NAME
- praxis - a package manager for Mutiny's package API, theory
+ praxis - package manager for Mutiny's package API, theory
+
+SYNOPSIS
+ This page consists of documentation and other notes on the design of
+ the praxis package manager.
PHILOSOPHY
Starting from the bottom-up, praxis aims to be composed of multiple
@@ -24,7 +28,137 @@ PHILOSOPHY
metadata from packages without having to call out to a shell running
arbitrary code or duplicate metadata. This has tended to be a problem
for other source-based package formats, such as the Arch Linux AUR,
- Exherbo’s exheres-0, and Gentoo’s EAPI.
+ Exherbo’s exheres-0, and Gentoo’s EAPI. That is to say, it should be
+ relatively static and not actually require a shell parser for anything
+ other than running the actual actions that build a package.
+
+DEPENDENCIES
+ • idioms <https://git.mutiny.red/mutiny/idioms>
+
+ • A POSIX-compliant shell
+
+ • s6-portable-utils <https://skarnet.org/software/s6-portable-utils>
+
+ • s6-update-symlinks is used for updating repositories while
+ respecting priority.
+
+ROADMAP
+ • Build repository management utilities
+
+ • repo-list - list all repositories by if they have libraries
+ and/or packages.
+
+ • Tests
+
+ • repo-update - update repositories and combine them according to
+ priority.
+
+ • Tests (currently are skipped until things settle)
+
+ • repo-lint - lint repositories and check their validity
+ according to theory(5).
+
+ • Tests
+
+ • Build theory construction utilities
+
+ • theory-action - resolve and print all action (build script)
+ parts of a theory.
+
+ • Tests
+
+ • theory-metadata - resolve and print all metadata parts of a
+ theory.
+
+ • Tests
+
+ • Open questions:
+
+ 1. Should packages be created by concatenation of things,
+ which creates a mostly self-contained and perhaps
+ easier-debugged build script, or should they be parsed more
+ heavily by the package manager itself? This needs to be
+ decided pretty soon since it basically dictates the rest of
+ the format.
+
+ • Build package building utilities
+
+ • pkg-gen - create a self-contained package script.
+
+ • Tests
+
+ • See the first open question above to understand my
+ anxieties with this format.
+
+WISHLIST
+ • Multiple repositories
+
+ • Intra-repository dependencies
+
+ • Priority levels
+
+ • ::mutiny is the most important repository.
+
+ • Other repositories should always be able to depend on
+ libraries in repositories that are have a higher priority.
+
+ • Repository synchronization
+
+ • Use git for synchronization by default, but allow alternative
+ transport/sync methods.
+
+ • Paludis has sync prefixes: cave sync -s local repository, which
+ are really useful for fast development of repositories and
+ packages within them.
+
+ • Something akin to apt-get source would be pretty nice - we have all
+ the metadata to do just this anyway, since all packages are built
+ from source.
+
+ Example configuration
+ Here’s what I’m imagining for the configuration format. Basically,
+ something akin to Paludis' configuration format, but simpler.
+
+ /etc/praxis/options.conf
+ Options enabled on packages.
+
+ * -* ruby ssl
+ tz leaps
+ toybox static
+ nginx webdav pcre
+
+ Files may also be put in /etc/praxis/options.d/*.conf, and they’ll take
+ priority over options.conf.
+
+ /etc/praxis/world
+ Packages explicitly requested to be installed by the user. They were
+ not installed as dependencies of other packages.
+
+ beets
+ lighttpd
+ mpd
+ passage
+
+GLOSSARY
+ actions
+ The actual executable code used to build a package.
+
+ theory
+
+ 1. The package API. See theory(5).
+
+ 2. A directory containing the data used to build a package. A
+ directory contains a package if it has either an action, or a
+ library (which creates actions).
+
+ETYMOLOGY
+ Named as such to conform with the rest of the Mutiny naming scheme.
+ "Praxis," the word, means in the original Greek, "action." Packages are
+ referred to as theories, thus praxis carries out a theory(3). praxis is
+ the reference implementation of the package manager used by mutiny(7).
+
+SEE ALSO
+ theory(5)
CONTRIBUTING
The canonical URL of this repository is
diff --git a/praxis-design.7.adoc b/praxis-design.7.adoc
deleted file mode 100644
index 79dc520..0000000
--- a/praxis-design.7.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-= praxis-design(7)
-
-== Name
-
-praxis - reference implementation of the package manager for Mutiny
-
-== Synopsis
-
-This page consists of documentation on the design of the `praxis` package manager.
-
-== Wishlist
-
-* Multiple repositories
- ** Intra-repository dependencies
- ** Important levels
- *** `::primary` is the most important repository
- *** Other repositories can always depend on libraries in repositories that are more important
-* Repository synchronization
- ** we might not want to have `git` in the basic system requirements
- *** Sounds like a great way to justify having `rsync` be a sysreq though... which is also
- kinda bad. that said, there is stuff like `openrsync` now...
- *** Having full history of the source repositories on your system is very appealing though
- and would be very much in line with system principles
- ** We could offer synchronization via tar archives _or_ git repositories; gitlab and github
- both can do autogenerated archives for each commit, the `master` branch, etc.
- ** Multiple ways to sync repositories
- ** Paludis has sync prefixes: `cave sync -s local repository`, which is really useful for
- development of repositories
-* Something akin to `apt-get source` would be pretty nice - we have all the metadata to do just this
- anyway, since all packages are built from source
-
-== Configuration
-
-=== `/etc/praxis/masks.conf`
-
-----
-ignore linux-headers[>$(uname -r | cut -d- -f1)]
-----
-
-=== `/etc/praxis/build.conf`
-
-Options enabled on packages; this may also include things such as environment variables.
-
-----
-MAKEFLAGS="-j12"
-
-* -* ruby ssl
-timezones leaps
-toybox MAKEFLAGS="-j1" static
-lighttpd MAKEFLAGS="-j -l3" webdav pcre -lua
-----
-
-=== `/etc/praxis/world`
-
-Packages specifically requested to be installed by the user. They were not installed as
-dependencies of other packages.
-
-----
-beets
-lighttpd
-mpd
-pass
-----
-
-== Etymology
-
-Named as such to conform with the rest of the Mutiny naming scheme. "Praxis," the word, means in the
-original Greek, "action." Packages are referred to as theories, thus praxis carries out a
-theory(3). `praxis` is the reference implementation of the package manager used by mutiny(7).
-
-== See also
-
-<<theory.3.adoc#,theory(3)>>
-
-include::footer.adoc[]
diff --git a/praxis.7 b/praxis.7
index 7a7b848..ec39078 100644
--- a/praxis.7
+++ b/praxis.7
@@ -28,12 +28,15 @@
. LINKSTYLE blue R < >
.\}
.SH "NAME"
-praxis \- a package manager for Mutiny\(aqs package API, theory
+praxis \- package manager for Mutiny\(aqs package API, theory
+.SH "SYNOPSIS"
+.sp
+This page consists of documentation and other notes on the design of the \fBpraxis\fP package manager.
.SH "PHILOSOPHY"
.sp
-Starting from the bottom\-up, \f(CRpraxis\fP aims to be composed of multiple small utilities that do one
+Starting from the bottom\-up, \fBpraxis\fP aims to be composed of multiple small utilities that do one
thing, so as to ease frontend development and more importantly, to make the surface area for issues
-very small. With this design in mind, \f(CRpraxis\fP can be fast and very compact, while providing a lot
+very small. With this design in mind, \fBpraxis\fP can be fast and very compact, while providing a lot
of useful functionality for developers, metadata consumers, and users.
.sp
No code evaluation is used at any point. All code is generated purely by following hierarchies of
@@ -47,7 +50,431 @@ repositories, and libraries.
Furthermore, another goal is ensuring that it should be possible to get metadata from packages
without having to call out to a shell running arbitrary code or duplicate metadata. This has tended
to be a problem for other source\-based package formats, such as the Arch Linux AUR, Exherbo\(cqs
-exheres\-0, and Gentoo\(cqs EAPI.
+exheres\-0, and Gentoo\(cqs EAPI. That is to say, it should be relatively static and not actually
+require a shell parser for anything other than running the actual actions that build a package.
+.SH "DEPENDENCIES"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+.URL "https://git.mutiny.red/mutiny/idioms" "\f(CRidioms\fP" ""
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+A POSIX\-compliant shell
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+.URL "https://skarnet.org/software/s6\-portable\-utils" "\f(CRs6\-portable\-utils\fP" ""
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+\f(CRs6\-update\-symlinks\fP is used for updating repositories while respecting priority.
+.RE
+.RE
+.SH "ROADMAP"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Build repository management utilities
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+\f(CRrepo\-list\fP \- list all repositories by if they have libraries and/or packages.
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Tests
+.RE
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+\f(CRrepo\-update\fP \- update repositories and combine them according to priority.
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Tests (currently are skipped until things settle)
+.RE
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+\f(CRrepo\-lint\fP \- lint repositories and check their validity according to theory(5).
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Tests
+.RE
+.RE
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Build theory construction utilities
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+\f(CRtheory\-action\fP \- resolve and print all action (build script) parts of a theory.
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Tests
+.RE
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+\f(CRtheory\-metadata\fP \- resolve and print all metadata parts of a theory.
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Tests
+.RE
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Open questions:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+. sp -1
+. IP " 1." 4.2
+.\}
+Should packages be created by concatenation of things, which creates a mostly
+self\-contained and perhaps easier\-debugged build script, or should they be parsed more
+heavily by the package manager itself? This needs to be decided pretty soon since it
+basically dictates the rest of the format.
+.RE
+.RE
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Build package building utilities
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+\f(CRpkg\-gen\fP \- create a self\-contained package script.
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Tests
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+See the first open question above to understand my anxieties with this format.
+.RE
+.RE
+.RE
+.SH "WISHLIST"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Multiple repositories
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Intra\-repository dependencies
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Priority levels
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+\f(CR::mutiny\fP is the most important repository.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Other repositories should always be able to depend on libraries in repositories that
+are have a higher priority.
+.RE
+.RE
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Repository synchronization
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Use \fBgit\fP for synchronization by default, but allow alternative transport/sync methods.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Paludis has sync prefixes: \f(CRcave sync \-s local repository\fP, which are really useful for
+fast development of repositories and packages within them.
+.RE
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Something akin to \f(CRapt\-get source\fP would be pretty nice \- we have all the metadata to do just
+this anyway, since all packages are built from source.
+.RE
+.SS "Example configuration"
+.sp
+Here\(cqs what I\(cqm imagining for the configuration format. Basically, something akin to Paludis\(aq
+configuration format, but simpler.
+.SS "\fI/etc/praxis/options.conf\fP"
+.sp
+Options enabled on packages.
+.sp
+.if n .RS 4
+.nf
+* \-* ruby ssl
+tz leaps
+toybox static
+nginx webdav pcre
+.fi
+.if n .RE
+.sp
+Files may also be put in \fI/etc/praxis/options.d/*.conf\fP, and they\(cqll take priority over
+\fIoptions.conf\fP.
+.SS "\fI/etc/praxis/world\fP"
+.sp
+Packages explicitly requested to be installed by the user. They were not installed as dependencies
+of other packages.
+.sp
+.if n .RS 4
+.nf
+beets
+lighttpd
+mpd
+passage
+.fi
+.if n .RE
+.SH "GLOSSARY"
+.sp
+actions
+.RS 4
+The actual executable code used to build a package.
+.RE
+.sp
+theory
+.RS 4
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+. sp -1
+. IP " 1." 4.2
+.\}
+The package API. See theory(5).
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+. sp -1
+. IP " 2." 4.2
+.\}
+A directory containing the data used to build a package. A directory contains a package if it
+has either an action, or a library (which creates actions).
+.RE
+.RE
+.SH "ETYMOLOGY"
+.sp
+Named as such to conform with the rest of the Mutiny naming scheme. "Praxis," the word, means in the
+original Greek, "action." Packages are referred to as theories, thus praxis carries out a
+theory(3). \f(CRpraxis\fP is the reference implementation of the package manager used by mutiny(7).
+.SH "SEE ALSO"
+.sp
+theory(5)
.SH "CONTRIBUTING"
.sp
The canonical URL of this repository is \c
diff --git a/praxis.7.adoc b/praxis.7.adoc
index de7c71e..c8bb7fe 100644
--- a/praxis.7.adoc
+++ b/praxis.7.adoc
@@ -2,13 +2,17 @@
== Name
-praxis - a package manager for Mutiny's package API, theory
+praxis - package manager for Mutiny's package API, theory
+
+== Synopsis
+
+This page consists of documentation and other notes on the design of the *praxis* package manager.
== Philosophy
-Starting from the bottom-up, `praxis` aims to be composed of multiple small utilities that do one
+Starting from the bottom-up, *praxis* aims to be composed of multiple small utilities that do one
thing, so as to ease frontend development and more importantly, to make the surface area for issues
-very small. With this design in mind, `praxis` can be fast and very compact, while providing a lot
+very small. With this design in mind, *praxis* can be fast and very compact, while providing a lot
of useful functionality for developers, metadata consumers, and users.
No code evaluation is used at any point. All code is generated purely by following hierarchies of
@@ -20,6 +24,113 @@ repositories, and libraries.
Furthermore, another goal is ensuring that it should be possible to get metadata from packages
without having to call out to a shell running arbitrary code or duplicate metadata. This has tended
to be a problem for other source-based package formats, such as the Arch Linux AUR, Exherbo's
-exheres-0, and Gentoo's EAPI.
+exheres-0, and Gentoo's EAPI. That is to say, it should be relatively static and not actually
+require a shell parser for anything other than running the actual actions that build a package.
+
+== Dependencies
+
+* https://git.mutiny.red/mutiny/idioms[`idioms`]
+* A POSIX-compliant shell
+* https://skarnet.org/software/s6-portable-utils[`s6-portable-utils`]
+ ** `s6-update-symlinks` is used for updating repositories while respecting priority.
+
+== Roadmap
+
+* [ ] Build repository management utilities
+ ** [x] `repo-list` - list all repositories by if they have libraries and/or packages.
+ *** [x] Tests
+ ** [x] `repo-update` - update repositories and combine them according to priority.
+ *** [ ] Tests (currently are skipped until things settle)
+ ** [ ] `repo-lint` - lint repositories and check their validity according to theory(5).
+ *** [ ] Tests
+
+* [ ] Build theory construction utilities
+ ** [x] `theory-action` - resolve and print all action (build script) parts of a theory.
+ *** [ ] Tests
+ ** [x] `theory-metadata` - resolve and print all metadata parts of a theory.
+ *** [ ] Tests
+ ** Open questions:
+ . Should packages be created by concatenation of things, which creates a mostly
+ self-contained and perhaps easier-debugged build script, or should they be parsed more
+ heavily by the package manager itself? This needs to be decided pretty soon since it
+ basically dictates the rest of the format.
+
+* [ ] Build package building utilities
+ ** [ ] `pkg-gen` - create a self-contained package script.
+ *** [ ] Tests
+ *** See the first open question above to understand my anxieties with this format.
+
+== Wishlist
+
+* Multiple repositories
+ ** Intra-repository dependencies
+ ** Priority levels
+ *** `::mutiny` is the most important repository.
+ *** Other repositories should always be able to depend on libraries in repositories that
+ are have a higher priority.
+
+* Repository synchronization
+ ** Use *git* for synchronization by default, but allow alternative transport/sync methods.
+ ** Paludis has sync prefixes: `cave sync -s local repository`, which are really useful for
+ fast development of repositories and packages within them.
+
+* Something akin to `apt-get source` would be pretty nice - we have all the metadata to do just
+ this anyway, since all packages are built from source.
+
+=== Example configuration
+
+Here's what I'm imagining for the configuration format. Basically, something akin to Paludis'
+configuration format, but simpler.
+
+==== _/etc/praxis/options.conf_
+
+Options enabled on packages.
+
+[example]
+----
+* -* ruby ssl
+tz leaps
+toybox static
+nginx webdav pcre
+----
+
+Files may also be put in _/etc/praxis/options.d/*.conf_, and they'll take priority over
+_options.conf_.
+
+==== _/etc/praxis/world_
+
+Packages explicitly requested to be installed by the user. They were not installed as dependencies
+of other packages.
+
+[example]
+----
+beets
+lighttpd
+mpd
+passage
+----
+
+[glossary]
+== Glossary
+
+[glossary]
+actions::
+ The actual executable code used to build a package.
+
+theory::
+ . The package API. See theory(5).
+
+ . A directory containing the data used to build a package. A directory contains a package if it
+ has either an action, or a library (which creates actions).
+
+== Etymology
+
+Named as such to conform with the rest of the Mutiny naming scheme. "Praxis," the word, means in the
+original Greek, "action." Packages are referred to as theories, thus praxis carries out a
+theory(3). `praxis` is the reference implementation of the package manager used by mutiny(7).
+
+== See also
+
+<<theory.5.adoc#,theory(5)>>
include::footer.adoc[]