diff options
| -rw-r--r-- | docs/cpt.org | 81 | ||||
| -rw-r--r-- | docs/cpt.texi | 101 | ||||
| -rw-r--r-- | docs/cpt.txt | 132 |
3 files changed, 281 insertions, 33 deletions
diff --git a/docs/cpt.org b/docs/cpt.org index 8f96981..caa35c9 100644 --- a/docs/cpt.org +++ b/docs/cpt.org @@ -481,6 +481,21 @@ the following =depends= file: zlib #+END_EXAMPLE +** meta + +=meta= is a non-mandatory package file that can be used to provide information +otherwise non-relevant to the functions of the package manager. This file can +later be queried with the [[=pkg_query_meta()=][pkg_query_meta()]] function. The file has a simple +markup format, it must adhere to the =KEY: VAL= format. An example for the =cpt= +package would be as follows: + +#+begin_example +description: Carbs Packaging Tools +license: MIT +maintainer: Linux User <linux-user@example.com> +#+end_example + + ** post-install :PROPERTIES: :DESCRIPTION: The post-installation script @@ -956,6 +971,8 @@ create_cache pkg_build cpt #+end_src +*** TODO =pkg_depends()= + *** =pkg_owner()= :PROPERTIES: :DESCRIPTION: Check which package owns the given file @@ -1025,13 +1042,69 @@ pkg_find 'cpt*' all SEARCH_PATH=$PATH pkg_find 'cpt-*' all -x #+end_src -*** TODO =pkg_get_base()= +*** =pkg_get_base()= +:PROPERTIES: +:DESCRIPTION: List system base packages +:END: -This function returns the base packages as defined in =/etc/cpt-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 [[CPT +Base]] for more information on base packages. -*** TODO =pkg_gentree= +*** =pkg_gentree()= :PROPERTIES: :DESCRIPTION: Generate a dependency tree for the given package :END: -Keep in mind /etc/cpt-base +This function generates a dependency tree for the given package. The output and +the dependency generation can be configured through a series of keys given as +the second argument. Those keys are: + +- =b= :: Include the base packages to the dependency tree. +- =f= :: Include the given package itself to the generated tree. +- =x= :: Do not include make dependencies of the package. +- =r= :: Print the generated tree in reverse order. +- =n= :: Print all packages in a single line instead of a package per line. + +**** Examples +:PROPERTIES: +:DESCRIPTION: Example usage for the =pkg_gentree= function +:END: + +This example uses the =cpt= package for Carbs Linux. The package itself is +listed to depend on =curl= and =rsync=. Here is the output of calling the +function for cpt directly: + +#+begin_example +$ pkg_gentree cpt +bearssl +ca-certificates +zlib +curl +rsync +#+end_example + +The example above shows that even though =cpt= itself only depends on =curl= and +=rsync=, we also indirectly need =zlib=, =bearssl= (for =curl=), and +=ca-certificates= (for =bearssl=). + +#+begin_src sh +# Print the dependency tree reverse sorted in a single line: +$ pkg_gentree cpt rn +rsync curl zlib ca-certificates bearssl +#+end_src + +*** =pkg_query_meta()= + +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. + +#+begin_src sh +$ pkg_query_meta cpt description +Carbs Packaging Tools +#+end_src diff --git a/docs/cpt.texi b/docs/cpt.texi index bd397ec..7b04cbb 100644 --- a/docs/cpt.texi +++ b/docs/cpt.texi @@ -77,6 +77,7 @@ Packaging System * checksums:: The file containing sha256sum of the sources * version:: The file containing the version and the release numbers of a package * depends:: The file containing the dependencies of a package +* meta:: * post-install:: The post-installation script * message:: The post-installation message to be displayed * test:: The test script for a package @@ -128,12 +129,14 @@ System Functions Package Functions * @samp{pkg_build()}:: +* @samp{pkg_depends()}:: * @samp{pkg_owner()}:: Check which package owns the given file * @samp{pkg_isbuilt()}:: Check whether the given package is built * @samp{pkg_lint()}:: Check whether a package directory fits the standards * @samp{pkg_find()}:: Query package locations -* @samp{pkg_get_base()}:: -* @samp{pkg_gentree}:: Generate a dependency tree for the given package +* @samp{pkg_get_base()}:: List system base packages +* @samp{pkg_gentree()}:: Generate a dependency tree for the given package +* @samp{pkg_query_meta()}:: @end detailmenu @end menu @@ -516,6 +519,7 @@ can be patches, configuration files, etc. * checksums:: The file containing sha256sum of the sources * version:: The file containing the version and the release numbers of a package * depends:: The file containing the dependencies of a package +* meta:: * post-install:: The post-installation script * message:: The post-installation message to be displayed * test:: The test script for a package @@ -624,6 +628,21 @@ python test zlib @end example +@node meta +@section meta + +@samp{meta} is a non-mandatory package file that can be used to provide information +otherwise non-relevant to the functions of the package manager. This file can +later be queried with the @ref{@samp{pkg_query_meta()}, , pkg@math{_query}@math{_meta}()} function. The file has a simple +markup format, it must adhere to the @samp{KEY: VAL} format. An example for the @samp{cpt} +package would be as follows: + +@example +description: Carbs Packaging Tools +license: MIT +maintainer: Linux User <linux-user@@example.com> +@end example + @node post-install @section post-install @@ -1098,12 +1117,14 @@ interact with packages. @menu * @samp{pkg_build()}:: +* @samp{pkg_depends()}:: * @samp{pkg_owner()}:: Check which package owns the given file * @samp{pkg_isbuilt()}:: Check whether the given package is built * @samp{pkg_lint()}:: Check whether a package directory fits the standards * @samp{pkg_find()}:: Query package locations -* @samp{pkg_get_base()}:: -* @samp{pkg_gentree}:: Generate a dependency tree for the given package +* @samp{pkg_get_base()}:: List system base packages +* @samp{pkg_gentree()}:: Generate a dependency tree for the given package +* @samp{pkg_query_meta()}:: @end menu @node @samp{pkg_build()} @@ -1122,6 +1143,9 @@ create_cache pkg_build cpt @end example +@node @samp{pkg_depends()} +@subsection @samp{pkg_depends()} + @node @samp{pkg_owner()} @subsection @samp{pkg_owner()} @@ -1188,11 +1212,72 @@ 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}. +This function returns the base packages as defined in @samp{/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 @ref{CPT Base} for more information on base packages. + +@node @samp{pkg_gentree()} +@subsection @samp{pkg_gentree()} + +This function generates a dependency tree for the given package. The output and +the dependency generation can be configured through a series of keys given as +the second argument. Those keys are: + +@table @asis +@item @samp{b} +Include the base packages to the dependency tree. +@item @samp{f} +Include the given package itself to the generated tree. +@item @samp{x} +Do not include make dependencies of the package. +@item @samp{r} +Print the generated tree in reverse order. +@item @samp{n} +Print all packages in a single line instead of a package per line. +@end table + +@enumerate +@item +Examples + + +This example uses the @samp{cpt} package for Carbs Linux. The package itself is +listed to depend on @samp{curl} and @samp{rsync}. Here is the output of calling the +function for cpt directly: -@node @samp{pkg_gentree} -@subsection @samp{pkg_gentree} +@example +$ pkg_gentree cpt +bearssl +ca-certificates +zlib +curl +rsync +@end example + +The example above shows that even though @samp{cpt} itself only depends on @samp{curl} and +@samp{rsync}, we also indirectly need @samp{zlib}, @samp{bearssl} (for @samp{curl}), and +@samp{ca-certificates} (for @samp{bearssl}). -Keep in mind /etc/cpt-base +@example +# Print the dependency tree reverse sorted in a single line: +$ pkg_gentree cpt rn +rsync curl zlib ca-certificates bearssl +@end example +@end enumerate + +@node @samp{pkg_query_meta()} +@subsection @samp{pkg_query_meta()} + +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. + +@example +$ pkg_query_meta cpt description +Carbs Packaging Tools +@end example @bye
\ No newline at end of file diff --git a/docs/cpt.txt b/docs/cpt.txt index 522d2ae..57e8c79 100644 --- a/docs/cpt.txt +++ b/docs/cpt.txt @@ -28,9 +28,10 @@ _________________ .. 3. checksums .. 4. version .. 5. depends -.. 6. post-install -.. 7. message -.. 8. test +.. 6. meta +.. 7. post-install +.. 8. message +.. 9. test 6. Rsync Repositories .. 1. Setting up an Rsync repository 7. Comparison Between CPT and KISS @@ -58,12 +59,14 @@ _________________ ..... 1. `as_root()' .. 7. Package Functions ..... 1. `pkg_build()' -..... 2. `pkg_owner()' -..... 3. `pkg_isbuilt()' -..... 4. `pkg_lint()' -..... 5. `pkg_find()' -..... 6. `pkg_get_base()' -..... 7. `pkg_gentree' +..... 2. `pkg_depends()' +..... 3. `pkg_owner()' +..... 4. `pkg_isbuilt()' +..... 5. `pkg_lint()' +..... 6. `pkg_find()' +..... 7. `pkg_get_base()' +..... 8. `pkg_gentree()' +..... 9. `pkg_query_meta()' This is a reference document containing both the user-guide and the @@ -559,7 +562,27 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -5.6 post-install +5.6 meta +~~~~~~~~ + + `meta' is a non-mandatory package file that can be used to provide + information otherwise non-relevant to the functions of the package + manager. This file can later be queried with the [pkg_query_meta()] + function. The file has a simple markup format, it must adhere to the + `KEY: VAL' format. An example for the `cpt' package would be as + follows: + + ,---- + | description: Carbs Packaging Tools + | license: MIT + | maintainer: Linux User <linux-user@example.com> + `---- + + +[pkg_query_meta()] See section 8.7.9 + + +5.7 post-install ~~~~~~~~~~~~~~~~ `post-install' files have the same requirements as the build @@ -567,14 +590,14 @@ development manual for *Carbs Packaging Tools*. For development logs see the user if the user has write permissions on `CPT_ROOT'). -5.7 message +5.8 message ~~~~~~~~~~~ This plaintext file will be outputted with `cat' after every package is installed. -5.8 test +5.9 test ~~~~~~~~ Test files are mainly for the repository maintainer to test the @@ -1039,7 +1062,11 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.7.2 `pkg_owner()' +8.7.2 `pkg_depends()' +--------------------- + + +8.7.3 `pkg_owner()' ------------------- This function can be used to determine the owner of a package. The @@ -1060,7 +1087,7 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.7.3 `pkg_isbuilt()' +8.7.4 `pkg_isbuilt()' --------------------- This function returns with success when the given package has a built @@ -1068,7 +1095,7 @@ development manual for *Carbs Packaging Tools*. For development logs see repository. -8.7.4 `pkg_lint()' +8.7.5 `pkg_lint()' ------------------ This function checks whether a given package fits the proper package @@ -1076,7 +1103,7 @@ development manual for *Carbs Packaging Tools*. For development logs see outright* if it fails. -8.7.5 `pkg_find()' +8.7.6 `pkg_find()' ------------------ `pkg_find()' is the tool for searching packages. It accepts up to 3 @@ -1109,13 +1136,76 @@ development manual for *Carbs Packaging Tools*. For development logs see `---- -8.7.6 `pkg_get_base()' +8.7.7 `pkg_get_base()' ---------------------- - This function returns the base packages as defined in `/etc/cpt-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 + packages. -8.7.7 `pkg_gentree' -------------------- +8.7.8 `pkg_gentree()' +--------------------- + + This function generates a dependency tree for the given package. The + output and the dependency generation can be configured through a + series of keys given as the second argument. Those keys are: + + `b' + Include the base packages to the dependency tree. + `f' + Include the given package itself to the generated tree. + `x' + Do not include make dependencies of the package. + `r' + Print the generated tree in reverse order. + `n' + Print all packages in a single line instead of a package per + line. + + +* 8.7.8.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 + of calling the function for cpt directly: + + ,---- + | $ pkg_gentree cpt + | bearssl + | ca-certificates + | zlib + | curl + | rsync + `---- + + The example above shows that even though `cpt' itself only depends on + `curl' and `rsync', we also indirectly need `zlib', `bearssl' (for + `curl'), and `ca-certificates' (for `bearssl'). + + ,---- + | # Print the dependency tree reverse sorted in a single line: + | $ pkg_gentree cpt rn + | rsync curl zlib ca-certificates bearssl + `---- + + +8.7.9 `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. + + ,---- + | $ pkg_query_meta cpt description + | Carbs Packaging Tools + `---- + - Keep in mind /etc/cpt-base +[meta file] See section 5.6 |