docs

Carbs Linux Documentation
git clone git://git.carbslinux.org/docs
Log | Files | Refs | Submodules | README

commit 351e4bc1c439d8167ed5dc8591421e061bd1b27d
parent 12625de9812b512076fcffebd20ed5bf9d5b8e38
Author: Cem Keylan <cem@ckyln.com>
Date:   Fri, 25 Dec 2020 16:49:07 +0300

carbslinux.org: remove package manager docs

The package manager documentation now resides with the package manager

Diffstat:
Mcarbslinux.org | 636-------------------------------------------------------------------------------
1 file changed, 0 insertions(+), 636 deletions(-)

diff --git a/carbslinux.org b/carbslinux.org @@ -43,35 +43,6 @@ distribution, installation, to the package manager. It is not yet complete. - [[#fstab][Fstab]] - [[#post-installation][Post-installation]] - [[#kiss-repositories][KISS repositories]] -- [[#package-manager][Package Manager]] - - [[#usage][Usage]] - - [[#cpt-alternatives][=cpt-alternatives=]] - - [[#cpt-build][=cpt-build=]] - - [[#cpt-checksum][=cpt-checksum=]] - - [[#cpt-download][=cpt-download=]] - - [[#cpt-install][=cpt-install=]] - - [[#cpt-list][=cpt-list=]] - - [[#cpt-remove][=cpt-remove=]] - - [[#cpt-search][=cpt-search=]] - - [[#cpt-update][=cpt-update=]] - - [[#global-flags][Global Flags]] - - [[#environment-variables][Environment Variables]] - - [[#cpt_compress][=CPT_COMPRESS=]] - - [[#cpt_force][=CPT_FORCE=]] - - [[#cpt_pid][=CPT_PID=]] - - [[#hooks][Hooks]] - - [[#editing-the-build-file-during-pre-build][Editing the =build= file during pre-build]] - - [[#packaging-system][Packaging System]] - - [[#build][=build=]] - - [[#sources][=sources=]] - - [[#checksums][=checksums=]] - - [[#version][=version=]] - - [[#depends][=depends=]] - - [[#post-install][=post-install=]] - - [[#message][=message=]] - - [[#test][=test=]] - - [[#rsync-repositories][Rsync Repositories]] - - [[#setting-up-an-rsync-repository][Setting up an Rsync repository]] - [[#init-system][Init System]] - [[#configuring-init][Configuring Init]] - [[#kernel-command-line][Kernel Command Line]] @@ -533,613 +504,6 @@ While not 100% compatible with cpt, you can use kiss repositories in your system the same way you are using the distribution repositories. Here is an example for the KISS Linux Community repository. -* Package Manager -:PROPERTIES: -:DESCRIPTION: Carbs Packaging Tools -:END: - -Carbs Linux uses its own package managing toolchain named =cpt=. It is a fork of -the [[https://github.com/kisslinux/kiss][kiss]] package manager. Unlike =kiss=, however, its main goal is being easily -extendable. Instead of being a single file package manager, it revolves around -the shell library =cpt-lib=, and many tools that wrap around it. - -The full documentation of =cpt-lib= is incomplete, but will be added to the -[[https://github.com/CarbsLinux/cpt][package manager's own source]]. - -** Usage -:PROPERTIES: -:DESCRIPTION: Basic usage of Carbs Packaging Tools -:END: - -=cpt= is formed of many tools combined in a single environment, similar to -=git=. When you run =cpt= without any arguments, it will show all available -tools and their explanations. Here is an example call with extra scripts on my -system: - -#+BEGIN_EXAMPLE - -> Carbs Packaging Tool - -> add Commit the current directory as a new package - -> alternatives List and swap to alternatives - -> build Build a package - -> bump Commit the current directory as a version bump - -> cargo-urlgen Create static cargo sources for Rust packages - -> cargolock-urlgen Convert the given Cargo.lock file to sources - -> cat Concatanate package files in the installed package database - -> changelog Print the git log of the specific package - -> chbuild Create/destroy temporary chroots - -> checkmissing Verify package manifests - -> checksum Generate checksums - -> chroot Enter a chroot - -> commit Commit a package without the prefix of 'package:' - -> depends Display a package's dependencies - -> download Download sources for the given package - -> exec Execute a command inside the alternatives system - -> export Turn an installed package into a CPT tarball - -> fork Fork a package to the current directory - -> getchoice Prints the full path to a file in the alternatives system. - -> install Install a package - -> link Link a forked package's files to the other repository - -> list List installed packages - -> maintainer Find the maintainer of a package - -> manifest Display all files owned by a package - -> manifest-tree Display all files owned by a package with a tree view - -> new Create a boilerplate CPT package - -> orphans List orphaned packages - -> owns Check which package owns a file - -> rel Bump the release number of a package - -> remove Remove a package - -> repodepends Display a package's dependencies in the repository - -> reporevdepends Display packages on the repository which depend on package - -> reset Remove all packages except for the base - -> revdepends Display packages which depend on package - -> search Search for a package - -> size Show the size on disk for a package - -> source Extract sources of a given package to the current directory - -> update Check for updates -#+END_EXAMPLE - -*** =cpt-alternatives= -:PROPERTIES: -:DESCRIPTION: List and swap to alternatives -:END: - -You can list and swap to alternatives using =cpt-alternatives=, or -=cpt a= for short. When run without alternatives, it will list -alternatives. It can read from standard input if =-= is given as an -argument. - -**** Examples - -List alternatives. - -#+BEGIN_EXAMPLE - $ cpt-alternatives - ncurses /usr/bin/clear - ncurses /usr/bin/reset -#+END_EXAMPLE - -Swap to =clear= from =ncurses=. - -#+BEGIN_EXAMPLE - $ cpt-alternatives ncurses /usr/bin/clear - -> Swapping '/usr/bin/clear' from 'busybox' to 'ncurses' -#+END_EXAMPLE - -Swap in bulk (all of =sbase=). - -#+BEGIN_EXAMPLE - $ cpt a | grep ^sbase | cpt a - -#+END_EXAMPLE - -*** =cpt-build= -:PROPERTIES: -:DESCRIPTION: Build a package -:END: - -=cpt-build= will build given packages and their dependencies. If multiple -packages are specified, it will ask to install the packages as well. - -| Flags | Explanation | -|----------------+--------------| -| =-t=, =--test= | Run tests | - -*** =cpt-checksum= -:PROPERTIES: -:DESCRIPTION: Generate checksums -:END: - -=cpt-checksum= will generate a =checksums= file from the package's sources. - -*** =cpt-download= -:PROPERTIES: -:DESCRIPTION: Download sources for the given package -:END: - -=cpt-download= will download the sources of a package. - -*** =cpt-install= -:PROPERTIES: -:DESCRIPTION: Install a package -:END: - -=cpt-install= will install given packages. - -*** =cpt-list= - -When called without arguments, =cpt-list= will print all installed -packages. You can add package names as arguments to check whether they are -installed or not. In success, =cpt-list= will exit with status 0 if all -given packages are installed, it will return 1 if any of the given packages -aren't installed. - -| Flags | Explanation | -|-------------------+----------------------------------------| -| =-c=, =--current= | Use the current directory as a package | - -*** =cpt-remove= -:PROPERTIES: -:DESCRIPTION: Remove a package -:END: - -=cpt-remove= will remove given packages. - -*** =cpt-search= -:PROPERTIES: -:DESCRIPTION: Search for a package -:END: - -=cpt-search= will search for packages, it accepts regular expressions as well. - -| Flags | Explanation | -|------------------+-------------------------------------------| -| =-s=, =--single= | Only show the first instance of a package | - - -#+BEGIN_EXAMPLE - $ cpt-search 'alsa-*' - /var/db/cpt/repo/extra/alsa-lib - /var/db/cpt/repo/extra/alsa-utils - /var/db/cpt/installed/alsa-lib - /var/db/cpt/installed/alsa-utils - - $ cpt-search emacs - /home/cem/repos/main/community/emacs - /home/cem/repos/kiss-community/community/emacs - /var/db/cpt/installed/emacs - - $ cpt-search --single emacs - /home/cem/repos/main/community/emacs -#+END_EXAMPLE - - -*** =cpt-update= -:PROPERTIES: -:DESCRIPTION: Check for updates -:END: - -=cpt-update= will update the packages on your system. It fetches remote -repositories, and builds, and installs packages that have versions different -from the ones installed on the system. It doesn't check if the version string -is actually higher, it only checks whether they differ. - -| Flags | Explanation | -|----------------------+--------------------------------------| -| =-d=, =--download= | Only download updatable packages | -| =-n=, =--no-fetch= | Do not update remote repositories | -| =-o=, =--only-fetch= | Only fetch the repositories and exit | - - -*** Global Flags -:PROPERTIES: -:DESCRIPTION: Flags that work globally on some cpt utilities -:END: - -| Flags | Explanation | -|---------------------+----------------------------------| -| =-f=, =--force= | Force operation, [[=CPT_FORCE=][See =CPT_FORCE=]] | -| =-y=, =--no-prompt= | Do not prompt for confirmation | -| =-root CPT_ROOT= | Use an alternate root directory | -| =-h=, =--help= | Show this help message | -| =-v=, =--version= | Print version information | - -** Environment Variables -:PROPERTIES: -:DESCRIPTION: Change the behaviour of cpt through environment configuration -:END: - -Since there is no configuration file for cpt, the package manager is configured -through environment variables. These can be set per operation, or be set to your -shell configuration or =~/.profile=. Here are the environment variables that -alter the behaviour of =cpt=: - -| ENVIRONMENT VALUE | Effects | -|-------------------+-------------------------------------------------------------------------------| -| =CPT_PATH= | Set the locations of your repositories. It is similar to the =PATH= variable. | -| =XDG_CACHE_HOME= | Unless this is set, the =~/.cache= directory will be used instead. | -| =CPT_CACHE= | The cache directory for =cpt=. Default: =$XDG_CACHE_HOME/cpt= | -| =CPT_CHOICE= | If this is set to 0, a package installation will be aborted on conflicts. | -| =CPT_COMPRESS= | Program used to compress package tarballs. [[=CPT_COMPRESS=][See =CPT_COMPRESS=]] | -| =CPT_DEBUG= | If set to 1, temporary directories will not be removed after the operation. | -| =CPT_FETCH= | If set to 0, =cpt-update= will not fetch repositories. | -| =CPT_FORCE= | [[=CPT_FORCE=][See =CPT_FORCE=]] | -| =CPT_HOOK= | Location for the hook file. | -| =CPT_KEEPLOG= | If set to 1, cpt will keep logs regardless of operation success. | -| =CPT_PID= | [[=CPT_PID=][See =CPT_PID=]] | -| =CPT_PROMPT0= | If set to 0, =cpt= will not prompt you for anything. | -| =CPT_ROOT= | If this variable is set, =cpt= will assume this as the system root. | -| =CPT_TEST= | If set to 1, =cpt-build= will run tests whenever available. | -| =CPT_TMPDIR= | The directory to create the temporary directories. | - - -*** =CPT_COMPRESS= -:PROPERTIES: -:DESCRIPTION: Compression tool to use in cpt -:END: - -When setting the =CPT_COMPRESS= value, you should set the name of the default -suffixes for the program. Available values are: - -- =gz= -- =zst= -- =bz2= -- =xz= - -Defaults to =gz=. - -*** =CPT_FORCE= -:PROPERTIES: -:DESCRIPTION: Force operations on cpt -:END: - -If this is set to 1, some of the =cpt= tools will continue regardless of -errors or skip certain checks. Here are some examples: - -- =cpt-install= will install a package without verifying its manifest. -- =cpt-install= will install a package even when there are missing dependencies. -- =cpt-remove= will remove packages even when there are other packages that - depend on the current package. - -Defaults to 0. - -*** =CPT_PID= -:PROPERTIES: -:DESCRIPTION: Set reproducible temporary directories -:END: - -If this variable is set, the temporary files will be created with this variable -as the suffix, instead of the PID of the =cpt= process. The advantage is that -you can know exactly where the build directory is located, while the -disadvantage is that there will be issues with multiple operations at the same -time. So the best way to use this variable is during one-time =cpt= calls. - -#+BEGIN_EXAMPLE - CPT_PID=mesa cpt b mesa -#+END_EXAMPLE - -By running the above, you will know that the created build directories will end -with the =*-mesa= suffix. - -** Hooks -:PROPERTIES: -:DESCRIPTION: Use hooks to customize the package manager operations -:END: - -Hooks can be used in order to change the runtime behaviour of the package manager. -There are a variety of package hooks, mostly self explanatory: - -- pre-build -- post-build -- build-fail -- pre-test -- test-fail -- pre-install -- post-install -- pre-remove -- post-remove -- pre-fetch -- post-fetch -- post-package - -In order to use hooks, you will need to set the =CPT_HOOK= variable pointing to -your hook file. Your hook file *MUST* be a POSIX shell script as its contents -are sourced by the package manager. - -The hook is given 3 variables when it is executed. Those are: - -| Variable | Explanation | -|----------+--------------------------------------------------------------| -| =$TYPE= | The type of the hook, (=pre-build=, =post-build=, etc.) | -| =$PKG= | The package that =cpt= is currently working on. Can be null. | -| =$DEST= | The destination of the operation. Can be null. | - -*** Editing the =build= file during pre-build -:PROPERTIES: -:DESCRIPTION: Modify a package build with your hooks -:END: - -You can edit the =build= file during pre-build. The file is copied from the -repository to the build directory named as =.build.cpt=. You can use =sed= or -any other tool to edit the build file. After the build is complete, a =diff= -file will be placed to the package database named as =build.diff=. Here is an -example =build= file manipulation during the pre-build hook. - -#+BEGIN_SRC sh - cat <<EOF> .build.cpt - #!/bin/sh -e - - for patch in bash50-0??; do - patch -p0 < "\$patch" - done - - export LDFLAGS=-static - - ./configure \ - --prefix=/usr \ - --without-bash-malloc \ - --disable-nls - - export MAKEFLAGS="TERMCAP_LIB=/usr/lib/libncursesw.a $MAKEFLAGS" - - make - make DESTDIR="\$1" install - - ln -s bash "\$1/usr/bin/sh" - EOF -#+END_SRC - -** Packaging System -:PROPERTIES: -:DESCRIPTION: More detail on creating packages -:END: - -A package is formed of several files, these are: - -- =build= -- =sources= -- =checksums= -- =version= -- =depends= -- =post-install= -- =message= -- =test= - -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= -:PROPERTIES: -:DESCRIPTION: The build script -:END: - -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 (=$#=) - -- Location of the package directory (DESTDIR) -- Package version -- System architecture - -*** =sources= -:PROPERTIES: -:DESCRIPTION: The file containing package sources -:END: - -=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 =soures= file; =src dest=. The =dest= -parameter is optional. It is the directory that the source will be placed in. -Here is the =sources= file for the =gst-plugins= package: - -#+BEGIN_EXAMPLE - 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 -#+END_EXAMPLE - -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=. - -If the source is a 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. - -*** =checksums= -:PROPERTIES: -:DESCRIPTION: The file containing sha256sum of the sources -:END: - -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= -:PROPERTIES: -:DESCRIPTION: The file containing the version and the release numbers of a package -:END: - -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. - -#+BEGIN_EXAMPLE - 1.3.2 1 -#+END_EXAMPLE - -*** =depends= -:PROPERTIES: -:DESCRIPTION: The file containing the dependencies of a package -:END: - -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. There are also "test" dependencies. These dependencies -are only installed if either the =CPT_TEST= is set to 1, or the build is run -with the =-t= or =--test= options. So, a package package could have -the following =depends= file: - -#+BEGIN_EXAMPLE - linux-headers make - python test - zlib -#+END_EXAMPLE - -*** =post-install= -:PROPERTIES: -:DESCRIPTION: The post-installation script -:END: - -=post-install= files 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= -:PROPERTIES: -:DESCRIPTION: The post-installation message to be displayed -:END: - -This plaintext file will be outputted with =cat= after every package is -installed. - -*** =test= -:PROPERTIES: -:DESCRIPTION: The test script for a package -:END: - -Test files are mainly for the repository maintainer to test the packages, and -will only run if the user has the =CPT_TEST= variable set, or the build is -run with the =-t= or =--test= options. This script is run on the -build directory. It is run right after the build script is finished. - -** Rsync Repositories -:PROPERTIES: -:DESCRIPTION: Information on using or creating rsync repositories -:END: - -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: - -#+BEGIN_EXAMPLE - rsync://carbslinux.org/repo/core -#+END_EXAMPLE - -Rsync repositories have some few distinctions when it comes to fetching them. -They can be either synced individually or as a "root". There are 2 important -files, those are =.rsync= and =.rsync_root=. Here is the Carbs Linux -rsync repository structure. - -#+BEGIN_EXAMPLE - / - ----------------- - | | - .rsync core/ - ---------------- - | | - .rsync .rsync_root -#+END_EXAMPLE - -Unlike git repositories, they don't have a defined "root" directory. This is -both an advantage and a disadvantage. This way, we can sync individual -repositories, but that also means we need extra files to define root directories -and repository locations. Here is the content for each of these files: - -#+BEGIN_EXAMPLE - /.rsync: rsync://carbslinux.org/repo - /core/.rsync: rsync://carbslinux.org/repo/core - /core/.rsync_root: .. -#+END_EXAMPLE - -The =.rsync_root= file on the core repository points to the upper directory. -If a =.rsync= file exists on the upper directory, this means that is the whole -repository and will sync the entire repository instead of each individual repository. - -If the upper directory doesn't have this =.rsync= file, this means that this -is an individual repository, and the package manager will fetch accordingly. - -*** Setting up an Rsync repository -:PROPERTIES: -:DESCRIPTION: Set up a repository for distribution -:END: - -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. - -#+BEGIN_SRC sh - #!/bin/sh - HOSTNAME="rsync://carbslinux.org/repo" - GITDIR="/pub/git/repo" - SHAREDIR="/pub/share/repo" - git -C "$GITDIR" pull - - rsync -avcC --delete --include=core --exclude=.rsync,.rsync_root "$GITDIR/." "$SHAREDIR" - - printf '%s\n' "$HOSTNAME" > "$GITDIR/.rsync" - for dir in "$GITDIR/"*; do - [ -d "$dir" ] || continue - [ -f "$dir/.rsync" ] || - printf '%s/%s\n' "$HOSTNAME" "${dir##*/}" > "$dir/.rsync" - printf '..\n' > "$dir/.rsync_root" - done -#+END_SRC - -You can then create an *rsync* user for serving the repositories. - -#+BEGIN_EXAMPLE - $ adduser -SD rsync -#+END_EXAMPLE - -Create =/etc/rsyncd.conf= and a service configuration as well. - - -#+BEGIN_EXAMPLE - uid = rsync - gid = rsync - address = example.com - max connections = 10 - use chroot = yes - - [repo] - path = /pub/share/repo - comment = My repository -#+END_EXAMPLE - -Create a service file at =/etc/sv/rsync/run= (runit): - -#+BEGIN_SRC sh - #!/bin/sh -e - exec rsync --daemon --no-detach -#+END_SRC - * Init System :PROPERTIES: :DESCRIPTION: Configure the init system