diff options
| -rw-r--r-- | doc/functions.txt | 86 | ||||
| -rw-r--r-- | doc/package-system.txt | 166 | ||||
| -rw-r--r-- | doc/rsync-repositories.txt | 103 |
3 files changed, 0 insertions, 355 deletions
diff --git a/doc/functions.txt b/doc/functions.txt deleted file mode 100644 index 3954c44..0000000 --- a/doc/functions.txt +++ /dev/null @@ -1,86 +0,0 @@ -FUNCTIONS -================================================================================= - -This is a document for example functions to ensure portability across different -systems. These are mere examples as we currently depend on non-POSIX utilities on -packages. These dependencies will be removed as we go forward. - -I don't want to turn the functions in here into a library because these are -really simple, and I believe that the build scripts should be self-contained. -What's the point of creating portable functions if the functions themselves -depend on a library file to be installed on a system? - -These obviously have their own limitations, but not every limitation has to be -solved in a single function. Use your imagination, non-standard flags/commands -may save you some keypresses, but they are not standard, because you can already -do these with your brain and a few more keypresses. - -SED -i ---------------------------------------------------------------------------------- - -The -i function isn't portable across systems, and isn't defined by POSIX. But it -isn't too valuable as it can be replaced with a simple function. I present you -sed_i. This function only depends on the fact that the file name is the last -argument. - - - sed_i() { - # This makes sure that we store the last argument on - # a file variable. - for file; do :; done - - # Run the arguments against sed, and redirect output - # to a temporary file simply named '_'. - sed "$@" > _ - # Instead of moving we cat into the file. This way we - # do not have to worry about preserving permissions of - # the file - cat _ > "$file"; rm -f _ - } - -In build scripts with multiple 'sed -i' usage, such a function can be defined for -and used. If only it is used a single time, defining such a function is quite -unnecessary. In such a case prefer doing it manually. Assume the file is named -'file.h' and we are calling 's/this/that/g'. - - - sed 's/this/that/g' file.h >_ - cat _ > file.h; rm -f _ - - -INSTALL -D,-t ---------------------------------------------------------------------------------- - -'install' does not have a standard. Options such as '-D' and '-t', even though -they are the most used, do not exist on every implementation. Avoid using these -flags where possible. You can prefer using functions such as these. The first -function is similar to '-t' flag, where you can install multiple files to a given -target. The second function is similar to the usage without the '-t' flag, a -single file where it will be named as the argument. - - - kinstall_t() { - # usage: kinstall_t 755 /usr/bin file1 file2 file3 - mod=$1 dir=$2; mkdir -p "$dir" - shift 2 - for file; do - ! [ -d "$dir/$file" ] || { - printf '%s\n' "Error: $dir/$file is a directory >&2" - return 1 - } - cp "$file" "$dir" - chmod "$mod" "$dir/$file" - done - } - - - kinstall() { - # usage: kinstall 755 filename /usr/bin/file - ! [ -d "$3" ] || { - printf '%s\n' "Error: $target is a directory" >&2 - return 1 - } - mkdir -p "${3%/*}"; cp "$2" "$3" - chmod "$1" "$3" - } - diff --git a/doc/package-system.txt b/doc/package-system.txt deleted file mode 100644 index dcbb5ed..0000000 --- a/doc/package-system.txt +++ /dev/null @@ -1,166 +0,0 @@ -PACKAGE SYSTEM -================================================================================= - - -This document talks about the packaging system works with the Carbs Packaging -Tools in detail. For information regarding the usage of the package manager -itself, see the cpt(1) manual page. - -A package is formed of 4 MANDATORY files. These are, -- BUILD -- SOURCES -- CHECKSUMS -- VERSION - -The package manager also reacts to the existence of these files, -- DEPENDS -- POST-INSTALL -- MESSAGE - -Any other file can be added to the package directory at the discretion of the -package maintainer. Everything in the package directory will also be added to the -package database that is located on '/var/db/cpt/installed'. These can be -patches, configuration files, etc. - - -BUILD ---------------------------------------------------------------------------------- - -Typically build files are shell scripts that run commands to prepare the source -code to be installed on the target system. Even though we will be assuming that -the build file is a POSIX shell script (for portability's sake), build files can -be any executable program from binary programs to Perl scripts. - -The contents of a build script do not need to follow a certain rule for the -package manager, except for the fact that the user needs the permission to -execute the file. - -An important advice is to append an '-e' to the shebang (#!/bin/sh -e) so that -the build script exits on compilation error. - -Build is run with three arguments -$1: Location of the package directory (DESTDIR) -$2: Package version -$3: System Architecture - - -SOURCES ---------------------------------------------------------------------------------- - -sources file is a list of files and sources that will be put to the build -directory during the build process. Those can be remote sources (such as -tarballs), git repositories, and files that reside on the package directory. - -The SYNTAX is pretty simple for the sources file. Here are some example 'sources' -files taken from the packages in the repository. - - BUSYBOX - - https://busybox.net/downloads/busybox-1.31.1.tar.bz2 - files/.config - files/.config-suid - files/acpid.run - files/crond.run - files/inittab - files/ntpd.run - files/syslogd.run - files/ntp.conf - patches/fsck-resolve-uuid.patch - patches/modprobe-kernel-version.patch - patches/adduser-no-setgid.patch - patches/install-fix-chown.patch - patches/print-unicode.patch - patches/1-date-64-prefix.patch - patches/2-time-64-prefix.patch - patches/3-syscall-gettime.patch - - - SINIT - - git+git://git.suckless.org/sinit#v1.1 - files/config.h - files/reboot - files/poweroff - - - GST-PLUGINS - https://gstreamer.freedesktop.org/src/gst-plugins-good/gst-plugins-good-1.16.2.tar.xz good - https://gstreamer.freedesktop.org/src/gst-plugins-bad/gst-plugins-bad-1.16.2.tar.xz bad - https://gstreamer.freedesktop.org/src/gst-plugins-ugly/gst-plugins-ugly-1.16.2.tar.xz ugly - https://gstreamer.freedesktop.org/src/gst-libav/gst-libav-1.16.2.tar.xz libav - - -This file is read from the package manager as space seperated. Files that begin -with a '#' comment are ignored. The first value points to the location of the -source. - -If it starts with a protcol url, (such as ftp:// http:// https://) it will be -downloaded with curl(1). - -If the source is GIT repository, it shall be prefixed with a 'git+'. git(1) will -be used to do a shallow clone of the repository. If the commit is suffixed by a -history pointer, git will checkout the relevant revision. So, - -- git+git://example.com/pub/repo#v1.2.3 will checkout the tag named 'v1.2.3' -- git+git://example.com/pub/repo#development will checkout the branch named 'development' -- git+git://example.com/pub/repo#1a314s87 will checkout the commit named '1a314s87' - - -Other files are assumed to be residing in the package directory. They should be -added with their paths relative to the package directory. - -The optional second value marks the DESTINATION of the source. If the value is -'example', the source will be extracted to a directory named 'example'. This is -useful on cases where there are multiple sources, or where a software requires -a source to be on a specific directory, you can see the gcc package for that. - - -CHECKSUMS ---------------------------------------------------------------------------------- - -checksums file is generated by the `cpt c pkg` command. It is generated -according to the order of the sources file. That's why you shouldn't be editing -it manually. The checksums file is created with the digests of the files using -the sha256 algorithm. - - -VERSION ---------------------------------------------------------------------------------- - -The version file includes the version of the software and the release number of -of the package on a space seperated format. The contents of the file should look -like below. - - 1.3.2 1 - -The version should always match to the number of the upstream release. For -drastic changes that require a rebuild Those can be, - -- update of libraries that forces the package to be relinked -- change in the build scripts that affect the output of the package - -When a version bump occurs, the release should be reset to 1. - - -DEPENDS ---------------------------------------------------------------------------------- - -This is a list of dependencies that must be installed before a package build. You -can append 'make' after a dependency to mark a package is only required during -the build process of a package. Packages marked as a make dependency can be -removed after the build. - - -POST-INSTALL ---------------------------------------------------------------------------------- - -post-installs have the same requirements as the build script. They will be run -after the package is installed as root (or as the user if the user has write -permissions on CPT_ROOT). - - -MESSAGE ---------------------------------------------------------------------------------- - -This plaintext file will be outputted with 'cat(1)' after every package is -installed. diff --git a/doc/rsync-repositories.txt b/doc/rsync-repositories.txt deleted file mode 100644 index 71799e5..0000000 --- a/doc/rsync-repositories.txt +++ /dev/null @@ -1,103 +0,0 @@ -RSYNC REPOSITORIES -================================================================================= - -RSYNC repositories are simple to serve and simple to use. In the repository -directory, there needs to be a '.rsync' file that points to the remote of the -repository. This is used in order to fetch changes from the upstream. '.rsync' -file looks like this for the core repository: - - +--------------------------------------------------------------------------+ - | | - | rsync://carbslinux.org/repo/core | - | | - +--------------------------------------------------------------------------+ - - -RSYNC repositories have some few distinctions when it comes to fetching them. -Unlike GIT repositories, they don't have a defined "root" directory. When there -are multiple repositories in a shared repository (such as the Carbs Linux and -KISS Linux repositories), individual repositories need to have this '.rsync' -file. This doesn't, however, slow down operations. Fetching from rsync -repositories are still considerably faster and smaller. - - -Setting up an rsync repository ---------------------------------------------------------------------------------- - -Carbs Linux repositories automatically sync from the git repostitories and serve -it through the rsync daemon. Here is a sample shell script that I use in order to -sync repositories. Feel free to customize for your own use. - - +--------------------------------------------------------------------------+ - | | - | #!/bin/sh | - | HOSTNAME=rsync://carbslinux.org/repo | - | GITDIR=/pub/git/repo | - | SHAREDIR=/pub/share/repo | - | | - | git -C "$GITDIR" pull | - | rsync -aC --delete --include=core --exclude=.rsync \ | - | "$GITDIR/" "$SHAREDIR" | - | | - | for dir in "$SHAREDIR/"*; do | - | [ -d "$dir" ] || continue | - | [ -f "$dir/.rsync" ] || | - | printf '%s/%s\n' "$HOSTNAME" "${dir##*/}" > "$dir/.rsync" | - | done | - | | - +--------------------------------------------------------------------------+ - - -You can then create an 'rsync' user for serving the repositories. - - +--------------------------------------------------------------------------+ - | | - | $ adduser -SD rsync | - | | - +--------------------------------------------------------------------------+ - - -Create '/etc/rsyncd.conf' and a service configuration as well. - - +--------------------------------------------------------------------------+ - | /etc/rsyncd.conf | - +--------------------------------------------------------------------------+ - | | - | uid = rsync | - | gid = rsync | - | address = example.com | - | max connections = 10 | - | use chroot = yes | - | | - | [repo] | - | path = /pub/share/repo | - | comment = My Repository | - | | - +--------------------------------------------------------------------------+ - -Create a service file: - - +--------------------------------------------------------------------------+ - | /etc/sysmgr/rsync or /etc/sv/rsync/run | - +--------------------------------------------------------------------------+ - | | - | #!/bin/sh | - | exec rsync --daemon --no-detach | - | | - +--------------------------------------------------------------------------+ - - -Switching to an rsync repository ---------------------------------------------------------------------------------- - -It is considerably easy to switch to the Carbs Linux rsync repository. - - +--------------------------------------------------------------------------+ - | | - | $ mkdir -p /path/to/repo | - | $ rsync -az rsync://carbslinux.org/repo/ /path/to/repo | - | | - +--------------------------------------------------------------------------+ - -This will fetch the repository to the given location, you can then add it to your -$CPT_PATH. |