diff options
Diffstat (limited to 'docs/cpt.texi')
| -rw-r--r-- | docs/cpt.texi | 338 |
1 files changed, 311 insertions, 27 deletions
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 |