diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 19 | ||||
| -rw-r--r-- | docs/cpt.org | 281 | ||||
| -rw-r--r-- | docs/cpt.texi | 338 | ||||
| -rw-r--r-- | docs/cpt.txt | 369 |
4 files changed, 861 insertions, 146 deletions
diff --git a/docs/Makefile b/docs/Makefile index 344bd70..7c5a431 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,9 +1,16 @@ # Carbs Packaging Tools Documentation -include ../config.mk +-include ../config.mk INSTALL_SH = ../tools/install.sh all: cpt.txt cpt.texi cpt.info +config.org: ../config.mk + printf '%s\n' '#+MACRO: version $(VERSION)' \ + '#+MACRO: conf_dir (eval (concat "=$(SYSCONFDIR)/cpt/" $$1 "="))' \ + '#+MACRO: data_dir (eval (concat "=$(DATAROOTDIR)/" $$1 "="))' > config.org + +cpt.txt cpt.texi cpt.info: cpt.org config.org + .SUFFIXES: .info .texi .org .txt .org.texi: rm -f $@ @@ -20,14 +27,6 @@ clean: rm -f cpt.info all-clean: clean - rm -f cpt.texi cpt.txt - -install: all - ${INSTALL_SH} -Dm644 cpt.txt ${DESTDIR}${CPTDOC}/cpt.txt - ${INSTALL_SH} -Dm644 cpt.info ${DESTDIR}${INFODIR}/cpt.info - -uninstall: - rm -rf ${DESTDIR}${CPTDOC} - rm -f ${DESTDIR}${INFODIR}/cpt.info + rm -f cpt.texi cpt.txt config.org .PHONY: all clean all-clean install uninstall 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 diff --git a/docs/cpt.texi b/docs/cpt.texi index c39b393..e6b331c 100644 --- a/docs/cpt.texi +++ b/docs/cpt.texi @@ -41,7 +41,8 @@ the section entitled "GNU Free Documentation License." @top Carbs Packaging Tools This is a reference document containing both the user-guide and the development -manual for @strong{Carbs Packaging Tools}. For development logs see @uref{https://git.carbslinux.org/cpt, the git repository}. +manual for @strong{Carbs Packaging Tools} version Fossil. For development logs +see @uref{https://fossil.carbslinux.org/cpt, the fossil repository}. @end ifnottex @menu @@ -49,20 +50,27 @@ manual for @strong{Carbs Packaging Tools}. For development logs see @uref{https: * Usage:: Basic usage of Carbs Packaging Tools * Configuration:: Configuring the package manager * Packaging System:: More detail on creating packages -* Rsync Repositories:: Information on using or creating rsync repositories +* Package Repositories:: Ways of distributing packages * Comparison Between CPT and KISS:: * CPT Library:: Documentation of the Library +* Concept Index:: Concepts mentioned in this manual +* Variable Index:: Variables mentioned in this manual @detailmenu --- The Detailed Node Listing --- Configuration -* CPT Base:: Defining base packages +* Configuration directory:: * Environment Variables:: Change the behaviour of cpt through environment configuration * Hooks:: Use hooks to customize the package manager operations * Editing the build file during pre-build:: Modify a package build with your hooks +Configuration directory + +* CPT Base:: Defining base packages +* Systemwide hooks:: + Environment Variables * @samp{CPT_PATH}:: Set the locations of your repositories @@ -75,13 +83,19 @@ Packaging System * build:: The build script * sources:: The file containing package sources * checksums:: The file containing sha256sum of the sources -* version:: The file containing the version and the release numbers of a package +* version:: The file containing version information for a package * depends:: The file containing the dependencies of a package * meta:: File containing more information on packages * post-install:: The post-installation script * message:: The post-installation message to be displayed * test:: The test script for a package +Package Repositories + +* Rsync Repositories:: Information on using or creating rsync repositories +* Fossil repositories:: Advantages and disadvantages of Fossil +* Message of the Day:: Communicate with the users using your repository + Rsync Repositories * Setting up an Rsync repository:: Set up a repository for distribution @@ -89,6 +103,7 @@ Rsync Repositories CPT Library * Calling the library:: Including the library on your code +* Variables:: * Option parsing:: Easy way of parsing options with cpt-lib * Message functions:: Communicate to users * Text functions:: Manipulate or check text @@ -152,6 +167,10 @@ it revolves around the shell library @samp{cpt-lib}, and many tools that wrap ar 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 @uref{https://fossil.carbslinux.org/cpt/tktnew, open a ticket}. + @node Usage @chapter Usage @@ -218,23 +237,42 @@ The package manager does @strong{NOT} have a configuration file, but there are a variety of ways in order to interact with and configure the package manager. @menu -* CPT Base:: Defining base packages +* Configuration directory:: * Environment Variables:: Change the behaviour of cpt through environment configuration * Hooks:: Use hooks to customize the package manager operations * Editing the build file during pre-build:: Modify a package build with your hooks @end menu +@node Configuration directory +@section Configuration directory + +Some features of the package manager can be configured from the files found +under @samp{/etc/cpt/}. 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). + +@menu +* CPT Base:: Defining base packages +* Systemwide hooks:: +@end menu + @node CPT Base -@section CPT Base +@subsection CPT Base + +@cindex Base packages -An @samp{/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 @samp{cpt-reset}, and @samp{cpt-orphans}. +The file @samp{/etc/cpt/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 @samp{cpt-reset}, and @samp{cpt-orphans}. @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 @@ -259,6 +297,14 @@ xz zlib @end example +@node Systemwide hooks +@subsection Systemwide hooks + +A collection of hooks can be installed under @samp{/etc/cpt/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 +@samp{/usr/share/cpt/examples/hooks/} directory. + @node Environment Variables @section Environment Variables @@ -270,35 +316,80 @@ to provide detailed information. @table @asis @item @code{CPT_PATH} +@vindex CPT_PATH Set the locations of your repositories. It is similar to the @code{PATH} variable. + @item @code{CPT_CACHE} +@vindex CPT_CACHE The cache directory for @samp{cpt}. Default: @code{$XDG_CACHE_HOME/cpt}. + @item @code{CPT_CHOICE} +@vindex CPT_CHOICE If this is set to 0, a package installation will be aborted on conflicts. + @item @code{CPT_COLOR} +@vindex CPT_COLOR If this is set to 1, @samp{cpt} tools will be forced to display coloured output. If set to 0, they will be forced to display them without colours. Otherwise, @samp{cpt} will output colour as long as it is outputting to a terminal. + @item @code{CPT_DEBUG} +@vindex CPT_DEBUG If set to 1, temporary directories will not be removed after the operation. + +@item @code{CPT_DOWNLOADER} +The tool to be used to download package sources. One of @samp{curl}, @samp{wget}, +@samp{wget2}, @samp{axel}, @samp{aria2c}. Defaults to the first one found in that order. + @item @code{CPT_FETCH} +@vindex CPT_FETCH If set to 0, @code{cpt-update} will not fetch repositories. + @item @code{CPT_FORCE} +@vindex CPT_FORCE If set to 1, @samp{cpt} tools will force operation. + @item @code{CPT_HOOK} +@vindex CPT_HOOK Absolute path to the package manager hook file. + @item @code{CPT_KEEPLOG} +@vindex CPT_KEEPLOG If set to 1, @samp{cpt} will keep logs regardless of operation success. + +@item @code{CPT_NOSTRIP} +@vindex CPT_NOSTRIP +If set to 1, @samp{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 @code{-g} flag to your @code{$C@{XX@}FLAGS} + @item @code{CPT_PID} +@vindex CPT_PID Set the temporary build directory name. + @item @code{CPT_PROMPT} +@vindex CPT_PROMPT If set to 0, @samp{cpt} will not prompt you for anything. + +@item @code{CPT_REPO_CACHE} +@vindex CPT_REPO_CACHE +If set to 0, @samp{cpt} will not use or write repository information cache. + @item @code{CPT_ROOT} +@vindex CPT_ROOT If this variable is set, @samp{cpt} will assume the given path as the system root. + @item @code{CPT_TEST} +@vindex CPT_TEST If set to 1, @code{cpt-build} will run tests whenever available. + @item @code{CPT_TMPDIR} +@vindex CPT_TMPDIR The directory to create the temporary directories. + +@item @code{CPT_VERBOSE} +@vindex CPT_VERBOSE +If this variable is set to 1, the package manager will print more information. @end table @menu @@ -311,6 +402,7 @@ The directory to create the temporary directories. @node @samp{CPT_PATH} @subsection @samp{CPT_PATH} +@cindex Setting up repositories Similar to the @samp{PATH} variable, @samp{cpt} find repositories from the @samp{CPT_PATH} variable. Here is an example: @@ -330,9 +422,10 @@ This example brings us to the next section of this document. @enumerate @item -Repository preferences +@anchor{Repository preferences}Repository preferences +@cindex package conflicts When you are using multiple repositories from multiple vendors, you will find out that some repositories have the same packages. @samp{cpt} doesn't care about conflicting packages. If you want to build a package that exists on multiple @@ -347,7 +440,7 @@ CPT_PATH=$HOME/repos/personal:$HOME/repos/carbs/extra @end example @item -Setting the @samp{CPT_PATH} +@anchor{Setting the @samp{CPT_PATH}}Setting the @samp{CPT_PATH} You can set the @samp{CPT_PATH} variable on your shell configuration or your @@ -442,10 +535,14 @@ Run if the @code{test} script fails Run before a package is installed for each package @item post-install Run after a package is installed for each package +@item end-install +Run after all given packages are installed @item pre-remove Run before a package is removed for each package @item post-remove Run after a package is removed for each package +@item end-remove +Run after all given packages are removed @item pre-fetch Run before all repositories are fetched @item post-fetch @@ -505,8 +602,8 @@ EOF @node Packaging System @chapter Packaging System -A package is formed of several files, from these files, only @code{build}, -@code{checksums}, and @code{version} files are mandatory. +A package is a directory formed of several files, from these files, only +@code{build}, @code{checksums}, and @code{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 @@ -514,11 +611,58 @@ of the package maintainer. Everything in the package directory will also be added to the package database that is located on @samp{/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. + +@multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaa} {aaaaaaaaa} +@headitem File +@tab Language +@tab Executable +@tab Mandatory +@item build +@tab any +@tab yes +@tab yes +@item checksums +@tab generated by @samp{cpt-checksum} +@tab no +@tab no +@item meta +@tab key-value pairs as in RFC822@footnote{@uref{https://datatracker.ietf.org/doc/html/rfc822#section-3.2}} +@tab no +@tab no@footnote{Not mandatory for the packaging system, but mandatory for inclusion in +the repositories} +@item depends +@tab custom format +@tab no +@tab no +@item sources +@tab custom format +@tab no +@tab no +@item version +@tab custom format +@tab no +@tab yes +@item message +@tab plaintext +@tab no +@tab no +@item post-install +@tab any +@tab yes +@tab no +@item test +@tab any +@tab yes +@tab no +@end multitable + @menu * build:: The build script * sources:: The file containing package sources * checksums:: The file containing sha256sum of the sources -* version:: The file containing the version and the release numbers of a package +* version:: The file containing version information for a package * depends:: The file containing the dependencies of a package * meta:: File containing more information on packages * post-install:: The post-installation script @@ -644,6 +788,9 @@ license: MIT maintainer: Linux User <linux-user@@example.com> @end example +Even though @samp{meta} is not mandatory by the packaging system, it is a mandatory +file for submitting packages to Carbs Linux repositories. + @node post-install @section post-install @@ -660,13 +807,35 @@ installed. @node test @section test +@vindex CPT_TEST Test files are mainly for the repository maintainer to test the packages, and will only run if the user has the @samp{CPT_TEST} variable set, or the build is run with the @samp{-t} or @samp{--test} options. This script is run on the build directory. It is run right after the build script is finished. +@node Package Repositories +@chapter Package Repositories + +@strong{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 @ref{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. + +@menu +* Rsync Repositories:: Information on using or creating rsync repositories +* Fossil repositories:: Advantages and disadvantages of Fossil +* Message of the Day:: Communicate with the users using your repository +@end menu + @node Rsync Repositories -@chapter Rsync Repositories +@section Rsync Repositories Rsync repositories are simple to serve and simple to use. In the repository directory, there needs to be a @samp{.rsync} file that points to the remote of the @@ -715,7 +884,7 @@ is an individual repository, and the package manager will fetch accordingly. @end menu @node Setting up an Rsync repository -@section Setting up an Rsync repository +@subsection 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 @@ -766,6 +935,33 @@ Create a service file at @samp{/etc/sv/rsync/run} (runit): exec rsync --daemon --no-detach @end example +@node Fossil repositories +@section Fossil repositories + +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 (@samp{emacs} and @samp{emacs-nox}, or @samp{libelf} and @samp{libdw} from +elfutils). If symbolic links are too big of a deal for your repository, this can +be a huge issue for you. + +@node Message of the Day +@section Message of the Day + +If a file named @samp{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. + @node Comparison Between CPT and KISS @chapter Comparison Between CPT and KISS @@ -788,11 +984,12 @@ through environment variables. Additionally, all @code{cpt} tools can receive fl that alter their functionality. @code{kiss} does not accept flags. @item Package Repositories -In addition to git repositories, @code{cpt} also makes use of @ref{Rsync Repositories, , rsync repositories}. +In addition to git repositories, @code{cpt} also supports Rsync, Fossil, and +Mercurial repositories. @item Package Sources -In addition to git repositories for sources, @code{cpt} also supports mercurial -repositories. +In addition to git repositories for sources, @code{cpt} also supports Mercurial and +Fossil repositories. @item Post-Installation Messages @code{kiss} and @code{cpt} interact with @samp{post-install} messages differently. @code{kiss} @@ -818,6 +1015,7 @@ package manager library. @menu * Calling the library:: Including the library on your code +* Variables:: * Option parsing:: Easy way of parsing options with cpt-lib * Message functions:: Communicate to users * Text functions:: Manipulate or check text @@ -840,6 +1038,65 @@ files: This will load the library inside your script, and will set some environment variables that are used inside the package manager. +@node Variables +@section 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 @ref{Environment Variables, , variables} section above. + +@vindex cpt_version +@table @asis +@item @samp{$cpt_version} +Package manager version. +@end table +@vindex cpt_confdir +@table @asis +@item @samp{$cpt_confdir} +Location of the CPT system configuration directory. This is usually either +@samp{/etc/cpt} or @samp{PREFIX/etc/cpt}. +@end table +@vindex pkg_db +@table @asis +@item @samp{$pkg_db} +Location of the package database without the root (@samp{var/db/cpt/installed}). +@end table +@vindex sys_db +@vindex CPT_ROOT +@table @asis +@item @samp{$sys_db} +Location of the package manager database, making use of the current +@samp{$CPT_ROOT} (@samp{$CPT_ROOT/$pkg_db}). This is the database you probably want to +use. +@end table +@cindex Base packages +@vindex cpt_base +@table @asis +@item @samp{$cpt_base} +Location of the file that defines the base packages. +@end table + +@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 @samp{$CPT_CACHE} or @samp{$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 +@table @asis +@item @samp{$cac_dir} +Cache directory used by the package manager. +@item @samp{$src_dir} +Directory containing downloaded sources for packages. +@item @samp{$log_dir} +Directory where logs are saved. +@item @samp{$bin_dir} +Directory where built package tarballs are saved. +@item @samp{$tmp_dir} +Temporary directory for the package manager operations. +@end table + @node Option parsing @section Option parsing @@ -885,7 +1142,7 @@ parser_definition() @{ The @samp{global_options()} function is a simple convenience call to include flags that can be used inside most @samp{cpt} tools. It defines the following flags: -@multitable {aaaa} {aaaaaaaaaaaaa} {aaaaaaaaaaaa} +@multitable {aaaa} {aaaaaaaaaaaaa} {aaaaaaaaaaaaa} @headitem Flag @tab Long Option @tab Calls @@ -904,8 +1161,22 @@ that can be used inside most @samp{cpt} tools. It defines the following flags: @item @code{-v} @tab @code{--version} @tab @samp{version()} +@item +@tab @code{--verbose} +@tab @samp{CPT_VERBOSE} @end multitable +This function can take two arguments: + +@table @asis +@item @samp{silent} +If this argument is specified, the function does not print the usage +information defined by its flags. +@item @samp{compact} +If this argument is specified, the function only prints the help +output of the @code{--help} and @code{--version} flags. +@end table + @node Message functions @section Message functions @@ -1224,7 +1495,7 @@ SEARCH_PATH=$PATH pkg_find 'cpt-*' all -x @node @samp{pkg_get_base()} @subsection @samp{pkg_get_base()} -This function returns the base packages as defined in @samp{/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 @ref{CPT Base} for more information on base packages. @@ -1250,7 +1521,7 @@ Print all packages in a single line instead of a package per line. @enumerate @item -Examples +@anchor{Examples}Examples This example uses the @samp{cpt} package for Carbs Linux. The package itself is @@ -1282,14 +1553,27 @@ rsync curl zlib ca-certificates bearssl This function is used to query the @ref{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 @samp{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 @samp{meta} file or the file does not contain the +requested key, the function will return with 1. @example $ pkg_query_meta cpt description Carbs Packaging Tools + +$ pkg_query_meta /path/to/cpt license +MIT @end example +@node Concept Index +@chapter Concept Index + +@printindex cp + +@node Variable Index +@chapter Variable Index + +@printindex vr + @bye
\ No newline at end of file diff --git a/docs/cpt.txt b/docs/cpt.txt index c04a52f..08433e9 100644 --- a/docs/cpt.txt +++ b/docs/cpt.txt @@ -1,10 +1,10 @@ - _______________________ + _______________________ - CARBS PACKAGING TOOLS - User Manual + CARBS PACKAGING TOOLS + User Manual - Cem Keylan - _______________________ + Cem Keylan + _______________________ Table of Contents @@ -14,7 +14,9 @@ _________________ 2. Preface 3. Usage 4. Configuration -.. 1. CPT Base +.. 1. Configuration directory +..... 1. CPT Base +..... 2. Systemwide hooks .. 2. Environment Variables ..... 1. `CPT_PATH' ..... 2. `CPT_COMPRESS' @@ -32,32 +34,36 @@ _________________ .. 7. post-install .. 8. message .. 9. test -6. Rsync Repositories -.. 1. Setting up an Rsync repository +6. Package Repositories +.. 1. Rsync Repositories +..... 1. Setting up an Rsync repository +.. 2. Fossil repositories +.. 3. Message of the Day 7. Comparison Between CPT and KISS 8. CPT Library .. 1. Calling the library -.. 2. Option parsing +.. 2. Variables +.. 3. Option parsing ..... 1. Defining a parser ..... 2. `global_options()' -.. 3. Message functions +.. 4. Message functions ..... 1. `out()' ..... 2. `log()' ..... 3. `die()' ..... 4. `warn()' ..... 5. `prompt()' -.. 4. Text functions +.. 5. Text functions ..... 1. `contains()' ..... 2. `regesc()' ..... 3. `pop()' ..... 4. `sepchar()' -.. 5. Portability functions +.. 6. Portability functions ..... 1. `_seq()' ..... 2. `_stat()' ..... 3. `_readlinkf()' -.. 6. System Functions +.. 7. System Functions ..... 1. `as_root()' -.. 7. Package Functions +.. 8. Package Functions ..... 1. `pkg_build()' ..... 2. `pkg_depends()' ..... 3. `pkg_order()' @@ -71,11 +77,11 @@ _________________ This is a reference document containing both the user-guide and the -development manual for *Carbs Packaging Tools*. For development logs see -[the git repository]. +development manual for *Carbs Packaging Tools* version Fossil. For +development logs see [the fossil repository]. -[the git repository] <https://git.carbslinux.org/cpt> +[the fossil repository] <https://fossil.carbslinux.org/cpt> 1 Copying @@ -103,9 +109,15 @@ development manual for *Carbs Packaging Tools*. For development logs see 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 [open a ticket]. + [kiss] <https://github.com/kisslinux/kiss> +[open a ticket] <https://fossil.carbslinux.org/cpt/tktnew> + 3 Usage ======= @@ -175,17 +187,31 @@ development manual for *Carbs Packaging Tools*. For development logs see package manager. -4.1 CPT Base -~~~~~~~~~~~~ +4.1 Configuration directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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'. + Some features of the package manager can be configured from the files + found under `/etc/cpt/'. 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). + + +4.1.1 CPT Base +-------------- + + The file `/etc/cpt/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'. ,---- | # 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 @@ -211,6 +237,16 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- +4.1.2 Systemwide hooks +---------------------- + + A collection of hooks can be installed under `/etc/cpt/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 `/usr/share/cpt/examples/hooks/' + directory. + + 4.2 Environment Variables ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -223,40 +259,72 @@ development manual for *Carbs Packaging Tools*. For development logs see `CPT_PATH' Set the locations of your repositories. It is similar to the `PATH' variable. + `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_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' 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' If set to 0, `cpt-update' will not fetch repositories. + `CPT_FORCE' If set to 1, `cpt' tools will force operation. + `CPT_HOOK' Absolute path to the package manager hook file. + `CPT_KEEPLOG' If set to 1, `cpt' will keep logs regardless of operation success. + + `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' Set the temporary build directory name. + `CPT_PROMPT' If set to 0, `cpt' will not prompt you for anything. + + `CPT_REPO_CACHE' + If set to 0, `cpt' will not use or write repository information + cache. + `CPT_ROOT' If this variable is set, `cpt' will assume the given path 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_VERBOSE' + If this variable is set to 1, the package manager will print + more information. + 4.2.1 `CPT_PATH' ---------------- @@ -383,10 +451,14 @@ development manual for *Carbs Packaging Tools*. For development logs see 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 @@ -446,8 +518,8 @@ development manual for *Carbs Packaging Tools*. For development logs see 5 Packaging System ================== - 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 @@ -456,6 +528,21 @@ development manual for *Carbs Packaging Tools*. For development logs see 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[1] no no[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 + 5.1 build ~~~~~~~~~ @@ -579,8 +666,11 @@ development manual for *Carbs Packaging Tools*. For development logs see | maintainer: Linux User <linux-user@example.com> `---- + Even though `meta' is not mandatory by the packaging system, it is a + mandatory file for submitting packages to Carbs Linux repositories. -[pkg_query_meta()] See section 8.7.10 + +[pkg_query_meta()] See section 8.8.10 5.7 post-install @@ -608,8 +698,24 @@ development manual for *Carbs Packaging Tools*. For development logs see script is finished. -6 Rsync Repositories -==================== +6 Package Repositories +====================== + + *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. + + In the broad sense, a package repository is any directory that + contains packages that were described in 5. 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. + + +6.1 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 @@ -658,8 +764,8 @@ development manual for *Carbs Packaging Tools*. For development logs see fetch accordingly. -6.1 Setting up an Rsync repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +6.1.1 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 @@ -712,6 +818,37 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- +6.2 Fossil repositories +~~~~~~~~~~~~~~~~~~~~~~~ + + 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. + + +6.3 Message of the Day +~~~~~~~~~~~~~~~~~~~~~~ + + 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. + + 7 Comparison Between CPT and KISS ================================= @@ -736,12 +873,12 @@ development manual for *Carbs Packaging Tools*. For development logs see functionality. `kiss' does not accept flags. Package Repositories - In addition to git repositories, `cpt' also makes use of [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. + Mercurial and Fossil repositories. Post-Installation Messages `kiss' and `cpt' interact with `post-install' messages @@ -761,9 +898,6 @@ development manual for *Carbs Packaging Tools*. For development logs see favour of portability. -[rsync repositories] See section 6 - - 8 CPT Library ============= @@ -787,7 +921,52 @@ development manual for *Carbs Packaging Tools*. For development logs see environment variables that are used inside the package manager. -8.2 Option parsing +8.2 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 [variables] section + above. + + `$cpt_version' + Package manager version. + `$cpt_confdir' + Location of the CPT system configuration directory. This is + usually either `/etc/cpt' or `PREFIX/etc/cpt'. + `$pkg_db' + Location of the package database without the root + (`var/db/cpt/installed'). + `$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. + `$cpt_base' + Location of the file that defines the base packages. + + 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). + + `$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. + + +[variables] See section 4.2 + + +8.3 Option parsing ~~~~~~~~~~~~~~~~~~ `cpt-lib' includes a POSIX-shell option parser inside named @@ -799,7 +978,7 @@ development manual for *Carbs Packaging Tools*. For development logs see [documentation] <https://github.com/ko1nksm/getoptions/blob/v2.5.0/README.md> -8.2.1 Defining a parser +8.3.1 Defining a parser ----------------------- Some functions are called and set automatically when you call @@ -826,29 +1005,39 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.2.2 `global_options()' +8.3.2 `global_options()' ------------------------ 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. -8.3 Message functions +8.4 Message functions ~~~~~~~~~~~~~~~~~~~~~ `cpt' has various functions to print information to users. -8.3.1 `out()' +8.4.1 `out()' ------------- `out()' is a really simple function that prints messages to the @@ -863,7 +1052,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.3.2 `log()' +8.4.2 `log()' ------------- `log()' is the most commonly used message function in the package @@ -881,7 +1070,7 @@ development manual for *Carbs Packaging Tools*. For development logs see above. -8.3.3 `die()' +8.4.3 `die()' ------------- `die()' wraps the `log()' function and exits with an error (1). It @@ -889,14 +1078,14 @@ development manual for *Carbs Packaging Tools*. For development logs see function. The third argument for `log()' is set as `!>'. -8.3.4 `warn()' +8.4.4 `warn()' -------------- `warn()' is another function that wraps `log()'. In place of the third argument, it uses the word `WARNING'. -8.3.5 `prompt()' +8.4.5 `prompt()' ---------------- `prompt()' is an interactive function that waits for user input to @@ -906,14 +1095,14 @@ development manual for *Carbs Packaging Tools*. For development logs see `CPT_PROMPT' to 0. -8.4 Text functions +8.5 Text functions ~~~~~~~~~~~~~~~~~~ Following functions are used to manipulate, check, or interact with text. -8.4.1 `contains()' +8.5.1 `contains()' ------------------ `contains' function can be used to check whether a list variable @@ -929,7 +1118,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.4.2 `regesc()' +8.5.2 `regesc()' ---------------- `regesc()' can be used to escape regular expression characters that @@ -941,7 +1130,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.4.3 `pop()' +8.5.3 `pop()' ------------- `pop()' can be used to remove a word from a "string list" without a @@ -955,7 +1144,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.4.4 `sepchar()' +8.5.4 `sepchar()' ----------------- This function can be used to separate characters from the given string @@ -975,7 +1164,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.5 Portability functions +8.6 Portability functions ~~~~~~~~~~~~~~~~~~~~~~~~~ These helper functions are used so that we don't depend on non-POSIX @@ -983,7 +1172,7 @@ development manual for *Carbs Packaging Tools*. For development logs see character. -8.5.1 `_seq()' +8.6.1 `_seq()' -------------- This function is similar to `seq(1)' except that it only takes a @@ -997,7 +1186,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.5.2 `_stat()' +8.6.2 `_stat()' --------------- This function imitates `stat %U'. `stat' isn't defined by POSIX, and @@ -1005,7 +1194,7 @@ development manual for *Carbs Packaging Tools*. For development logs see file. If the owner cannot be found, it will return `root'. -8.5.3 `_readlinkf()' +8.6.3 `_readlinkf()' -------------------- This function was taken from [POSIX sh readlinkf library by Koichi @@ -1017,10 +1206,10 @@ development manual for *Carbs Packaging Tools*. For development logs see <https://github.com/ko1nksm/readlinkf> -8.6 System Functions +8.7 System Functions ~~~~~~~~~~~~~~~~~~~~ -8.6.1 `as_root()' +8.7.1 `as_root()' ----------------- `as_root()' calls the rest of the arguments as a different @@ -1037,7 +1226,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `$CPT_SU' variable. -8.7 Package Functions +8.8 Package Functions ~~~~~~~~~~~~~~~~~~~~~ Obviously, package functions are the most important ones for @@ -1045,7 +1234,7 @@ development manual for *Carbs Packaging Tools*. For development logs see manipulate, or to otherwise interact with packages. -8.7.1 `pkg_build()' +8.8.1 `pkg_build()' ------------------- This function builds all given packages. It resolves dependencies for @@ -1063,7 +1252,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.7.2 `pkg_depends()' +8.8.2 `pkg_depends()' --------------------- This function calculates the dependencies for the requested package, @@ -1072,17 +1261,17 @@ development manual for *Carbs Packaging Tools*. For development logs see packages. -[pkg_order()] See section 8.7.3 +[pkg_order()] See section 8.8.3 -8.7.3 `pkg_order()' +8.8.3 `pkg_order()' ------------------- This function receives package names and returns `$order' and `$redro' variables that can be used for building and removing packages. -8.7.4 `pkg_owner()' +8.8.4 `pkg_owner()' ------------------- This function can be used to determine the owner of a package. The @@ -1103,7 +1292,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.7.5 `pkg_isbuilt()' +8.8.5 `pkg_isbuilt()' --------------------- This function returns with success when the given package has a built @@ -1111,7 +1300,7 @@ development manual for *Carbs Packaging Tools*. For development logs see repository. -8.7.6 `pkg_lint()' +8.8.6 `pkg_lint()' ------------------ This function checks whether a given package fits the proper package @@ -1119,7 +1308,7 @@ development manual for *Carbs Packaging Tools*. For development logs see outright* if it fails. -8.7.7 `pkg_find()' +8.8.7 `pkg_find()' ------------------ `pkg_find()' is the tool for searching packages. It accepts up to 3 @@ -1152,17 +1341,17 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.7.8 `pkg_get_base()' +8.8.8 `pkg_get_base()' ---------------------- - This function returns the base packages as defined in - `/etc/cpt-base'. 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 4.1 for more information on base + 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 4.1.1 for more information on base packages. -8.7.9 `pkg_gentree()' +8.8.9 `pkg_gentree()' --------------------- This function generates a dependency tree for the given package. The @@ -1182,7 +1371,7 @@ development manual for *Carbs Packaging Tools*. For development logs see line. -* 8.7.9.1 Examples +* 8.8.9.1 Examples This example uses the `cpt' package for Carbs Linux. The package itself is listed to depend on `curl' and `rsync'. Here is the output @@ -1208,20 +1397,34 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.7.10 `pkg_query_meta()' +8.8.10 `pkg_query_meta()' ------------------------- This function is used to query the [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. + 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. ,---- | $ pkg_query_meta cpt description | Carbs Packaging Tools + | + | $ pkg_query_meta /path/to/cpt license + | MIT `---- [meta file] See section 5.6 + + + +Footnotes +_________ + +[1] <https://datatracker.ietf.org/doc/html/rfc822#section-3.2> + +[2] Not mandatory for the packaging system, but mandatory for +inclusion in the repositories |