diff options
Diffstat (limited to 'docs/cpt.org')
| -rw-r--r-- | docs/cpt.org | 281 |
1 files changed, 255 insertions, 26 deletions
diff --git a/docs/cpt.org b/docs/cpt.org index 3949cea..b3fc97b 100644 --- a/docs/cpt.org +++ b/docs/cpt.org @@ -6,10 +6,14 @@ #+TEXINFO_DIR_CATEGORY: Development #+TEXINFO_DIR_TITLE: Carbs Packaging Tools: (cpt) #+TEXINFO_DIR_DESC: Carbs Package Management Library +#+INCLUDE: ./config.org #+OPTIONS: html-scripts:nil todo:nil +#+MACRO: index (eval (format (if (org-export-derived-backend-p org-export-current-backend 'texinfo) "%s Index\n:PROPERTIES:\n:INDEX: %s\n:DESCRIPTION: %ss mentioned in this manual\n:END:\n" "%s%s%s :noexport:\n") $1 $2 $1)) + This is a reference document containing both the user-guide and the development -manual for *Carbs Packaging Tools*. For development logs see [[https://git.carbslinux.org/cpt][the git repository]]. +manual for *Carbs Packaging Tools* version {{{version}}}. For development logs +see [[https://fossil.carbslinux.org/cpt][the fossil repository]]. * Copying :PROPERTIES: @@ -38,6 +42,10 @@ it revolves around the shell library =cpt-lib=, and many tools that wrap around it. This document aims to document both the usage of the distributed tools and document the library functions. +If you happen to find something that is not properly covered by the +documentation, or an area that can be improved, please feel free to submit a +patch, or [[https://fossil.carbslinux.org/cpt/tktnew][open a ticket]]. + * Usage :PROPERTIES: :DESCRIPTION: Basic usage of Carbs Packaging Tools @@ -107,19 +115,32 @@ man cpt-build The package manager does *NOT* have a configuration file, but there are a variety of ways in order to interact with and configure the package manager. -** CPT Base +** Configuration directory + +Some features of the package manager can be configured from the files found +under {{{conf_dir}}}. Even though this doesn't sound like the premise of "no +configuration" files, these files are completely optional to the package +manager, and still the majority of configuration is done through environment +variables. The files on this directory are for configuration that don't have a +big impact on how the package manager behaves, and are not feasible to be used +inside simple environment variables (such as the base package list and +package manager hooks). + +*** CPT Base :PROPERTIES: :DESCRIPTION: Defining base packages :END: -An =/etc/cpt-base= file can be used in order to define the base to the package -manager. Base packages are the packages that receive special treatment by -utilities such as =cpt-reset=, and =cpt-orphans=. +#+CINDEX: Base packages + +The file {{{conf_dir(base)}}} can be used in order to define the base to the +package manager. Base packages are the packages that receive special treatment +by utilities such as =cpt-reset=, and =cpt-orphans=. #+begin_example # This file defines the base packages of the system. You can add or remove # package names in order to redefine the base. This file will be used by -# cpt-orphans and cpt-reset. If this file doesn't exist on /etc/cpt-base, both +# cpt-orphans and cpt-reset. If this file doesn't exist on /etc/cpt/base, both # of the tools will assume that there is no defined base, so use with caution. baselayout binutils @@ -144,6 +165,13 @@ xz zlib #+end_example +*** Systemwide hooks + +A collection of hooks can be installed under {{{conf_dir(hooks/)}}}. All of the +files installed under this directory will then be sourced by the package manager +whenever a hook is called. Some examples for system hooks can be found under the +{{{data_dir(cpt/examples/hooks/)}}} directory. + ** Environment Variables :PROPERTIES: :DESCRIPTION: Change the behaviour of cpt through environment configuration @@ -156,41 +184,105 @@ variables that alter the behaviour of =cpt=, some of them have separate sections to provide detailed information. - ~CPT_PATH~ :: + + #+VINDEX: CPT_PATH Set the locations of your repositories. It is similar to the ~PATH~ variable. + - ~CPT_CACHE~ :: + + #+VINDEX: CPT_CACHE The cache directory for =cpt=. Default: ~$XDG_CACHE_HOME/cpt~. + - ~CPT_CHOICE~ :: + + #+VINDEX: CPT_CHOICE If this is set to 0, a package installation will be aborted on conflicts. + - ~CPT_COLOR~ :: + + #+VINDEX: CPT_COLOR If this is set to 1, =cpt= tools will be forced to display coloured output. If set to 0, they will be forced to display them without colours. Otherwise, =cpt= will output colour as long as it is outputting to a terminal. + - ~CPT_DEBUG~ :: + + #+VINDEX: CPT_DEBUG If set to 1, temporary directories will not be removed after the operation. + +- ~CPT_DOWNLOADER~ :: + + The tool to be used to download package sources. One of =curl=, =wget=, + =wget2=, =axel=, =aria2c=. Defaults to the first one found in that order. + - ~CPT_FETCH~ :: + + #+VINDEX: CPT_FETCH If set to 0, ~cpt-update~ will not fetch repositories. + - ~CPT_FORCE~ :: + + #+VINDEX: CPT_FORCE If set to 1, =cpt= tools will force operation. + - ~CPT_HOOK~ :: + + #+VINDEX: CPT_HOOK Absolute path to the package manager hook file. + - ~CPT_KEEPLOG~ :: + + #+VINDEX: CPT_KEEPLOG If set to 1, =cpt= will keep logs regardless of operation success. + +- ~CPT_NOSTRIP~ :: + + #+VINDEX: CPT_NOSTRIP + If set to 1, =cpt= will not strip debug information from the binaries. Keep in + mind that your compiler already strips most debug information during + compilation, so you also need to add ~-g~ flag to your ~$C{XX}FLAGS~ + - ~CPT_PID~ :: + + #+VINDEX: CPT_PID Set the temporary build directory name. + - ~CPT_PROMPT~ :: + + #+VINDEX: CPT_PROMPT If set to 0, =cpt= will not prompt you for anything. + +- ~CPT_REPO_CACHE~ :: + + #+VINDEX: CPT_REPO_CACHE + If set to 0, =cpt= will not use or write repository information cache. + - ~CPT_ROOT~ :: + + #+VINDEX: CPT_ROOT If this variable is set, =cpt= will assume the given path as the system root. + - ~CPT_TEST~ :: + + #+VINDEX: CPT_TEST If set to 1, ~cpt-build~ will run tests whenever available. + - ~CPT_TMPDIR~ :: + + #+VINDEX: CPT_TMPDIR The directory to create the temporary directories. +- ~CPT_VERBOSE~ :: + + #+VINDEX: CPT_VERBOSE + If this variable is set to 1, the package manager will print more information. + *** =CPT_PATH= :PROPERTIES: :DESCRIPTION: Set the locations of your repositories :END: +#+CINDEX: Setting up repositories Similar to the =PATH= variable, =cpt= find repositories from the =CPT_PATH= variable. Here is an example: @@ -213,6 +305,7 @@ This example brings us to the next section of this document. :DESCRIPTION: Prioritise package repositories :END: +#+CINDEX: package conflicts When you are using multiple repositories from multiple vendors, you will find out that some repositories have the same packages. =cpt= doesn't care about conflicting packages. If you want to build a package that exists on multiple @@ -310,8 +403,10 @@ There are a variety of package hooks, mostly self explanatory: - test-fail :: Run if the ~test~ script fails - pre-install :: Run before a package is installed for each package - post-install :: Run after a package is installed for each package +- end-install :: Run after all given packages are installed - pre-remove :: Run before a package is removed for each package - post-remove :: Run after a package is removed for each package +- end-remove :: Run after all given packages are removed - pre-fetch :: Run before all repositories are fetched - post-fetch :: Run after all repositories are fetched - post-package :: Run after a tarball for a package is created @@ -369,8 +464,8 @@ EOF :DESCRIPTION: More detail on creating packages :END: -A package is formed of several files, from these files, only ~build~, -~checksums~, and ~version~ files are mandatory. +A package is a directory formed of several files, from these files, only +~build~, ~checksums~, and ~version~ files are mandatory. This section talks about files that are interpreted specially by the package manager. Any other file can be added to the package directory at the discretion @@ -378,6 +473,21 @@ 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. +Below is a table that provides a small summary for each file, see the relevant +section to learn detailed information on each of them. + +| File | Language | Executable | Mandatory | +|--------------+------------------------------------+------------+-----------| +| build | any | yes | yes | +| checksums | generated by =cpt-checksum= | no | no | +| meta | key-value pairs as in RFC822[fn:1] | no | no[fn:2] | +| depends | custom format | no | no | +| sources | custom format | no | no | +| version | custom format | no | yes | +| message | plaintext | no | no | +| post-install | any | yes | no | +| test | any | yes | no | + ** build :PROPERTIES: :DESCRIPTION: The build script @@ -451,7 +561,7 @@ the sha256 algorithm. ** version :PROPERTIES: -:DESCRIPTION: The file containing the version and the release numbers of a package +:DESCRIPTION: The file containing version information for a package :END: The version file includes the version of the software and the release number of @@ -498,6 +608,9 @@ license: MIT maintainer: Linux User <linux-user@example.com> #+end_example +Even though =meta= is not mandatory by the packaging system, it is a mandatory +file for submitting packages to Carbs Linux repositories. + ** post-install :PROPERTIES: :DESCRIPTION: The post-installation script @@ -520,12 +633,30 @@ installed. :DESCRIPTION: The test script for a package :END: +#+VINDEX: CPT_TEST 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 +* Package Repositories +:PROPERTIES: +:DESCRIPTION: Ways of distributing packages +:END: + +*cpt* has backends to support the use of a variety of distribution methods. You +can currently use Git, Mercurial, Fossil, and Rsync to distribute a package +repository. That, however, does not mean that you need to setup either of those, +if you are simply going for a local repository on your system. + +#+CINDEX: Setting up repositories +In the broad sense, a package repository is any directory that contains packages +that were described in [[Packaging System]]. This means that as long as you can +serve them, there is not much needed to do in order to distribute a repository. +The following subsections aim to detail the notes and the caveats of certain +distribution methods. + +** Rsync Repositories :PROPERTIES: :DESCRIPTION: Information on using or creating rsync repositories :END: @@ -572,7 +703,7 @@ repository and will sync the entire repository instead of each individual reposi 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 +*** Setting up an Rsync repository :PROPERTIES: :DESCRIPTION: Set up a repository for distribution :END: @@ -626,6 +757,37 @@ Create a service file at =/etc/sv/rsync/run= (runit): exec rsync --daemon --no-detach #+END_SRC +** Fossil repositories +:PROPERTIES: +:DESCRIPTION: Advantages and disadvantages of Fossil +:END: + +Setting up a Fossil repository is no different than setting up any other +repository. There are certainly many advantages of using Fossil as a means of +distributing packages. You can create a Linux distribution and have your +website, forum, documentation, and your package repository entirely contained +inside a single Fossil repository. Fossil's built-in wiki and forum features +make it the ultimate single-tool distribution software. + +However, the biggest caveat of Fossil is that it doesn't allow symlinks by +default unless it's manually set by the user, and this feature cannot even be +set globally. Symbolic links aren't quite common within distribution +repositories, but they come in handy where there are two packages that use the +same source files (=emacs= and =emacs-nox=, or =libelf= and =libdw= from +elfutils). If symbolic links are too big of a deal for your repository, this can +be a huge issue for you. + +** Message of the Day +:PROPERTIES: +:DESCRIPTION: Communicate with the users using your repository +:END: + +If a file named =MOTD= (all uppercase) is found on the root directory of the +package repository, its contents will be printed to the standard output when the +users are updating their repositories. This method can be used to communicate +messages to the users, such as package removals or otherwise important +information. + * Comparison Between CPT and KISS Lots of things have changed since ~cpt~ was forked from ~kiss~ in terms of @@ -649,12 +811,13 @@ this is the ~cpt~ documentation, so it may be biased regardless. - Package Repositories :: - In addition to git repositories, ~cpt~ also makes use of [[Rsync Repositories][rsync repositories]]. + In addition to git repositories, ~cpt~ also supports Rsync, Fossil, and + Mercurial repositories. - Package Sources :: - In addition to git repositories for sources, ~cpt~ also supports mercurial - repositories. + In addition to git repositories for sources, ~cpt~ also supports Mercurial and + Fossil repositories. - Post-Installation Messages :: @@ -697,6 +860,52 @@ files: This will load the library inside your script, and will set some environment variables that are used inside the package manager. +** Variables + +This section lists some of the variables defined by the package manager that can +be used in scripts. These variables usually cannot be defined by the user, so +they are not part of the [[* Environment Variables][variables]] section above. + +#+VINDEX: cpt_version +- =$cpt_version= :: + Package manager version. +#+VINDEX: cpt_confdir +- =$cpt_confdir= :: + Location of the CPT system configuration directory. This is usually either + =/etc/cpt= or =PREFIX/etc/cpt=. +#+VINDEX: pkg_db +- =$pkg_db= :: + Location of the package database without the root (=var/db/cpt/installed=). +#+VINDEX: sys_db +#+VINDEX: CPT_ROOT +- =$sys_db= :: + Location of the package manager database, making use of the current + =$CPT_ROOT= (=$CPT_ROOT/$pkg_db=). This is the database you probably want to + use. +#+CINDEX: Base packages +#+VINDEX: cpt_base +- =$cpt_base= :: + Location of the file that defines the base packages. + +#+CINDEX: Scripts that use CPT cache directories +If for some reason, your script interacts with the directories created and +managed by the package manager you should use the following variables instead of +the user assigned variables such as =$CPT_CACHE= or =$CPT_TMPDIR=. The variables +below are the ones used for package operations (which are assigned by using a +combination of user-assigned values and their fallbacks). + +#+VINDEX: cac_dir +- =$cac_dir= :: + Cache directory used by the package manager. +- =$src_dir= :: + Directory containing downloaded sources for packages. +- =$log_dir= :: + Directory where logs are saved. +- =$bin_dir= :: + Directory where built package tarballs are saved. +- =$tmp_dir= :: + Temporary directory for the package manager operations. + ** Option parsing :PROPERTIES: :DESCRIPTION: Easy way of parsing options with cpt-lib @@ -743,13 +952,21 @@ inside. Here is the proper way of doing it. The =global_options()= function is a simple convenience call to include flags that can be used inside most =cpt= tools. It defines the following flags: -| Flag | Long Option | Calls | -|------+---------------+--------------| -| ~-f~ | ~--force~ | =CPT_FORCE= | -| ~-y~ | ~--no-prompt~ | =CPT_PROMPT= | -| | ~--root~ | =CPT_ROOT= | -| ~-h~ | ~--help~ | =usage()= | -| ~-v~ | ~--version~ | =version()= | +| Flag | Long Option | Calls | +|------+---------------+---------------| +| ~-f~ | ~--force~ | =CPT_FORCE= | +| ~-y~ | ~--no-prompt~ | =CPT_PROMPT= | +| | ~--root~ | =CPT_ROOT= | +| ~-h~ | ~--help~ | =usage()= | +| ~-v~ | ~--version~ | =version()= | +| | ~--verbose~ | =CPT_VERBOSE= | + +This function can take two arguments: + +- =silent= :: If this argument is specified, the function does not print the usage + information defined by its flags. +- =compact= :: If this argument is specified, the function only prints the help + output of the ~--help~ and ~--version~ flags. ** Message functions :PROPERTIES: @@ -1058,7 +1275,7 @@ SEARCH_PATH=$PATH pkg_find 'cpt-*' all -x :DESCRIPTION: List system base packages :END: -This function returns the base packages as defined in =/etc/cpt-base=. If an +This function returns the base packages as defined in the base file. If an optional argument is present, it will print all package names in a single line. If it is not given any arguments, it will return one package per line. See [[CPT Base]] for more information on base packages. @@ -1110,12 +1327,24 @@ rsync curl zlib ca-certificates bearssl This function is used to query the [[meta][meta file]] inside package directories. It can be used to retrieve information on a package that is otherwise irrelevant to the -package manager itself. It takes two arguments, first being the package and the -second being the key to be retrieved. If the package does not have a =meta= -file or the file does not contain the requested key, the function will return -with 1. +package manager itself. It takes two arguments, first being the package (or the +full path to a package directory) and the second being the key to be retrieved. +If the package does not have a =meta= file or the file does not contain the +requested key, the function will return with 1. #+begin_src sh $ pkg_query_meta cpt description Carbs Packaging Tools + +$ pkg_query_meta /path/to/cpt license +MIT #+end_src + +* {{{index(Concept, cp)}}} +* {{{index(Variable,vr)}}} + +* Footnotes + +[fn:1] https://datatracker.ietf.org/doc/html/rfc822#section-3.2 +[fn:2] Not mandatory for the packaging system, but mandatory for inclusion in +the repositories |