diff options
Diffstat (limited to 'docs/cpt.txt')
| -rw-r--r-- | docs/cpt.txt | 369 |
1 files changed, 286 insertions, 83 deletions
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 |