bonsai/kiss
3
0
Fork 0
forked from kiss-community/kiss
Code Issues 2 Pull Requests Projects Releases Activity

doc: update package-system.txt

Browse Source
This commit is contained in:
Dylan Araps 2021-07-21 13:53:04 +03:00
parent 0a5b7ffbb9
commit bc32b77f95
No known key found for this signature in database
GPG Key ID: 13295DAC2CF13B5C
1 changed files with 123 additions and 255 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

378
doc/package-system.txt
View File

@ -1,81 +1,87 @@
KISS PACKAGE SYSTEM KISS PACKAGE SYSTEM
________________________________________________________________________________ ________________________________________________________________________________
The distribution employs a package system based around the concept of easily Packages are comprised of a directory and the series of files contained within.
parseable plain-text files (with fields separated by lines and spaces). The name of the package is derived from its directory name. The files which
comprise the system are as follows.
This format allows effortless interface using any programming language or just +------------------+----------+------------+----------+-------------+----------+
basic UNIX utilities and tools. | File | Language | Executable | Comments | Blank lines | Required |
+------------------+----------+------------+----------+-------------+----------+
| | | | | | |
| build | Any | Yes [2] | N/A | N/A | Yes |
| checksums | DSL [3] | No | No | No | No [1] |
| depends | DSL [3] | No | Yes | Yes | No |
| sources | DSL [3] | No | Yes | Yes | No |
| version | DSL [3] | No | No | No | Yes |
| | | | | | |
| pre-remove | Any | Yes [2] | N/A | N/A | No |
| post-install | Any | Yes [2] | N/A | N/A | No |
| | | | | | |
+------------------+----------+------------+----------+-------------+----------+
Unless stated otherwise, all files marked DSL are a grid of cells split into
rows by newline and columns by whitespace.
[1] The checksums file is only required if the sources file contains sources
which exist as files on disk (directories, git repositories need not apply).
[2] The only requirement is that the file be executable. The file itself can be
written in any programming language.
[3] The file's format is a domain specific language with its own rules.
https://en.wikipedia.org/wiki/Domain-specific_language
[0.0] Index [1.0] build
________________________________________________________________________________ ________________________________________________________________________________
- Directory Structure [1.0] The build file is executed in the directory containing the package's extracted
sources. Unlike other distributions, a 'cd' is not needed as sources have their
top-level directory components stripped away.
- build [2.0] The build file is given two arguments. The destination directory (where
- depends [3.0] artifacts should be installed) and the first field of the package's version
- sources [4.0] file (verbatim).
- version [5.0]
- pre-remove [6.0] The build file is given a modified environment containing DESTDIR, KISS_ROOT,
- post-install [7.0] GOPATH and generic defaults for toolchain variables (if unset by the user). The
- patches/* [8.0] toolchain defaults are as follows: AR=ar, CC=cc, CXX=c++, NM=nm, RANLIB=ranlib
- files/* [9.0]
+------------------------------------------------------------------------------+
| Example shell-based build file |
+------------------------------------------------------------------------------+
| |
| 1 #!/bin/sh -e |
| 2 |
| 3 # Disable stripping (use if needed). |
| 4 :> nostrip |
| 5 |
| 6 ./configure \ |
| 7 --prefix=/usr |
| 8 |
| 9 make |
| 10 make install |
| |
+------------------------------------------------------------------------------+
[1.0] Directory Structure [2.0] checksums
________________________________________________________________________________ ________________________________________________________________________________
+------------------------------------------------------------------------------+ The checksums file is generated by the package manager (kiss c pkg) and is
| | derived from files listed in the package's sources file. Directories and Git
| zlib/ # Package name. | repositories are excluded.
| - build # Build script (chmod +x). |
| - sources # Remote and local sources. |
| - version # Package version. |
| |
| |
| # Optional files. |
| |
| - depends # Dependencies (usually required). |
| - pre-remove # Pre-remove script (chmod +x). |
| - post-install # Post-install script (chmod +x). |
| - patches/* # Directory to store patches. |
| - files/* # Directory to store misc files. |
| |
+------------------------------------------------------------------------------+
Checksum verification can be disabled for a source by replacing its checksum
[2.0] build with 'SKIP' in the checksums file. The package manager will notify you when
________________________________________________________________________________ this occurs.
The build file should contain all of the steps necessary to patch, configure,
make and install ('make install' in this context) the package. The file is
language agnostic and the only requirement is that it be executable.
On execution the script will start in the directory of the package's source
(no need to cd anywhere).
The script is also given arguments (equivalent to 'script arg arg'). The first
argument contains the path where the script should install the compiled files.
The second argument contains the package's version.
Everything in the mentioned path is added to the package tarball and later
installed to the system.
+------------------------------------------------------------------------------+
| build |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| | | |
| #!/bin/sh -e | | 1 892a0875b9872acd04a9fde79b1f943075d5ea162415de3047c327df33fbaee5 |
| | | 2 8a5b38a76b778da8d6f4236f1ea89e680daea971be6ee3a57e4e7ae99a883aa2 |
| # Disable stripping (add this only if needed). | | 3 SKIP |
| :> nostrip |
| |
| ./configure \ |
| --prefix=/usr |
| |
| make |
| make DESTDIR="$1" install |
| | | |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
@ -83,26 +89,18 @@ installed to the system.
[3.0] depends [3.0] depends
________________________________________________________________________________ ________________________________________________________________________________
The depends file should contain any other packages the package depends on to The depends file contains the package's dependencies listed one per line in
function correctly. Each dependency should be listed one per line. alphabetical order. Duplicate entries are not supported. The second optional
field denotes the dependency type (unset for runtime, 'make' for compile-time).
A second and optional field allows for the distinction between a compile time
dependency and a run time one. The value of this field should be set to 'make'
for compile time dependencies and left blank for runtime dependencies.
The depends file can be omitted entirely if the package has no dependencies.
+------------------------------------------------------------------------------+
| depends |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| | | |
| # Comments are supported. | | 1 alsa-lib |
| | | 2 meson make |
| # Perl is needed at compile time. | | 3 |
| perl make | | 4 # This is a comment. |
| | | 5 wayland |
| # zlib is needed at runtime. | | 6 wayland-protocols make |
| zlib |
| | | |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
@ -110,119 +108,57 @@ The depends file can be omitted entirely if the package has no dependencies.
[4.0] sources [4.0] sources
________________________________________________________________________________ ________________________________________________________________________________
The sources file should contain all remote and local files needed by the The sources file contains the package's sources one per line. A valid source is
package during the build. This includes the source, patches and any other a URL to a file, relative path, absolute path or Git repository. The optional
miscellaneous files which may be needed. second field denotes the relative destination directory.
Each source should be listed one per line. An optional second field specifies Git repositories must be prefixed with git+. An optional suffix is supported to
an extraction directory (relative to the build directory). checkout a specific branch (@BRANCH) or commit (#COMMIT). All clones are shallow
where supported by the remote server. If no suffix is used, master is cloned.
Sources which pull from a git repository use a special syntax. An additional
prefix 'git+' should be added with an optional suffix #hash or @branch).
Adding a suffix of '?no-extract' to the source URL will prevent the package
manager from automatically extracting the source (if a tarball or zip).
Sources also support MARKERS which are replaced with the version information
as defined in the version file at runtime.
+------------------------------------------------------------------------------+
| sources |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| | | |
| https://example.com/dhcpcd-8.0.2.tar.xz | | 1 # This is a comment. |
| files/dhcpcd.run | | 2 https://www.openssl.org/source/openssl-VERSION.tar.gz |
| 3 https://causal.agency/libretls/libretls-3.3.3p1.tar.gz libretls |
| 4 |
| 5 files/update-certdata.sh |
| 6 git+https://github.com/kisslinux/kiss@dev |
| | | |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+ The following MARKERS can be used to substitute version information. These are
| sources (usage with second field) | replaced at runtime with their respective values. Literal MARKERS can be escaped
+------------------------------------------------------------------------------+ by prepending a backslash.
| |
| https://example.com/gcc-9.1.0.tar.xz gcc |
| https://example.com/gmp-6.1.2.tar.xz gcc/gmp |
| https://example.com/mpfr-4.0.2.tar.xz gcc/mpfr |
| https://example.com/mpc-1.1.0.tar.gz gcc/mpc |
| |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| sources (usage with Git) |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| | | |
| git+https://github.com/dylanaraps/eiwd | | VERSION The first field of the version file verbatim. |
| | | RELEASE The second field of the version file verbatim. |
| # Grabbing a specific branch. | | MAJOR The first component of VERSION split on .-_+ |
| git+https://github.com/dylanaraps/eiwd@branch | | MINOR The second component of VERSION split on .-_+ |
| | | PATCH The third component of VERSION split on .-_+ |
| # Grabbing a specific commit. | | IDENT All other components. |
| git+https://github.com/dylanaraps/eiwd#commit | | PACKAGE The name of the package. |
| | | |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| sources (usage with MARKERS) |
+------------------------------------------------------------------------------+
| |
| VERSION The first field of the version file verbatim. |
| RELEASE The second field of the version file verbatim. |
| MAJOR The first component of VERSION split on .+-_ |
| MINOR The second component of VERSION split on .+-_ |
| PATCH The third component of VERSION split on .+-_ |
| IDENT All other components of VERSION. |
| PKG The name of the package. |
| |
+------------------------------------------------------------------------------+
| |
| https://example.com/dhcpcd-VERSION.tar.xz |
| https://example.com/pub/gnome/sources/atk/MAJOR.MINOR/atk-VERSION.tar.xz |
| |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| sources (usage with automatic source extraction disabled) |
+------------------------------------------------------------------------------+
| |
| https://example.com/zlib-1.2.0.tar.xz?no-extract |
| |
+------------------------------------------------------------------------------+
[5.0] version [5.0] version
________________________________________________________________________________ ________________________________________________________________________________
The version file should contain a single line with two fields. All other lines The version file is a single line split into two mandatory fields. The first
will be ignored. field is the package's version and the second field the version of the
repository files themselves.
The first field should contain the software's upstream version and the second If the package follows its upstream release schedule, the first field should
field should contain the version number of the repository files themselves. match the upstream version number. If the source is a Git repository, the
version should be set to 'git'. If a specific git commit is used, the version
If the package is using a git source to pull down the latest commit, the number should match accordingly.
version should be simply set to 'git'. If a specific commit hash is being
used, the version should be set accordingly.
+------------------------------------------------------------------------------+
| version |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| | | |
| 1.2.3 1 | | 1 1.2.11 1 |
| |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| version (Git) |
+------------------------------------------------------------------------------+
| |
| git 1 |
| |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| version (commit hash) |
+------------------------------------------------------------------------------+
| |
| 7fd2c9bd80b1053852a9cc989205f7ee6b1f6d6f 1 |
| | | |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
@ -230,18 +166,14 @@ used, the version should be set accordingly.
[6.0] pre-remove [6.0] pre-remove
________________________________________________________________________________ ________________________________________________________________________________
The pre-remove file should contain anything that needs run prior to the The pre-remove file is executed before removal of the package. This file should
removal of the package. The file is language agnostic and the only requirement be used to perform any required pre-removal steps or to display notices.
is that it be executable.
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| pre-remove | | Example shell-based pre-remove file |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| | | |
| #!/bin/sh -e | | TODO: Example |
| |
| printf 'No one has used this yet!\n' |
| printf 'I have no example!\n' |
| | | |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
@ -249,87 +181,23 @@ is that it be executable.
[7.0] post-install [7.0] post-install
________________________________________________________________________________ ________________________________________________________________________________
The post-install file should contain anything that needs to be run after a The post-install file is executed after installation of the package. This file
package installation to properly setup the software. The file is language should be used to perform any required post-install steps or to display notices.
agnostic and the only requirement is that it be executable.
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| post-install | | Example shell-based post-install file |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| | | |
| #!/bin/sh -e | | 1 #!/bin/sh -e |
| | | 2 |
| fc-cache -vf | | 3 cat <<EOF |
| | | 4 |
+------------------------------------------------------------------------------+ | 5 The commands zcat, unpigz and gunzip were merely symbolic |
| 6 links to the pigz binary. They have been removed. To gain |
| 7 them back, create the symlinks (or use an alias or shell |
[8.0] patches/* | 8 function). |
________________________________________________________________________________ | 9 |
| 10 EOF |
The patches directory should contain any patches the software needs.
In the `sources` file patches are referred to by using a relative path
(patches/musl.patch). The package manager does not automatically apply patches.
This must be done in the build script of the package.
The build script has direct access to the patches in its current working
directory ('patch -p1 < example.patch' works directly).
+------------------------------------------------------------------------------+
| sources (usage with patches) |
+------------------------------------------------------------------------------+
| |
| https://example.com/rxvt-unicode-9.22.tar.bz2 |
| patches/gentables.patch |
| patches/rxvt-unicode-kerning.patch |
| |
+------------------------------------------------------------------------------+
| build (usage with patches) |
+------------------------------------------------------------------------------+
| |
| #!/bin/sh -e |
| |
| patch -p1 < rxvt-unicode-kerning.patch |
| patch -p1 < gentables.patch |
| |
| ./configure \ |
| --prefix=/usr |
| |
| make |
| make DESTDIR="$1" install |
| |
+------------------------------------------------------------------------------+
[9.0] files/*
________________________________________________________________________________
The files/ directory should contain any miscellaneous files the software needs.
In the sources file, files are referred to by using a relative path
(files/busybox.config).
The build script has direct access to the files in its current working
directory ('cat example_file' works directly).
+------------------------------------------------------------------------------+
| sources (usage with local files) |
+------------------------------------------------------------------------------+
| |
| https://example.com/kiss-1.0.0.tar.gz |
| files/kiss_path.sh |
| |
+------------------------------------------------------------------------------+
| build (usage with local files) |
+------------------------------------------------------------------------------+
| |
| #!/bin/sh -e |
| |
| install -D kiss "$1/usr/bin/kiss" |
| |
| # Accessible directly in '$PWD'. |
| install -D kiss_path.sh "$1/etc/kiss_path.sh" |
| | | |
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+