aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authormerakor <cem@ckyln.com>2021-03-26 14:57:59 +0000
committermerakor <cem@ckyln.com>2021-03-26 14:57:59 +0000
commitc1faf64caeaffbf9b75ea7d49d9f5ac34edb013f (patch)
treeee9eee45d9a5d0256eca4a37e19d016764e5412b /docs
parent481f73fb6e6ee3fccef88f8a27f13f3b390dc476 (diff)
downloadcpt-c1faf64caeaffbf9b75ea7d49d9f5ac34edb013f.tar.gz
docs: update
FossilOrigin-Name: 894886784b54484eadea0b9377feed1f25397b3a51241b3289dcc1efdbf7df18
Diffstat (limited to 'docs')
-rw-r--r--docs/cpt.org81
-rw-r--r--docs/cpt.texi101
-rw-r--r--docs/cpt.txt132
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