docs: add pkg_build() documentation

FossilOrigin-Name: ad53d4a9b1bb065a017b65dd1f5a7c32575df62aaec44807b5e2d3f59b4f05d4

3 files changed, 64 insertions, 12 deletions

diff --git a/docs/cpt.org b/docs/cpt.org
index 0e59114..8f96981 100644
--- a/docs/cpt.org
+++ b/docs/cpt.org
@@ -941,6 +941,21 @@ Obviously, package functions are the most important ones for =cpt-lib=, those
 are the ones you will use to build, to query, to manipulate, or to otherwise
 interact with packages.
 
+*** =pkg_build()=
+
+This function builds all given packages. It resolves dependencies for the given
+packages, lints the package, extracts its sources and runs the ~build~ script.
+
+#+begin_src sh
+# Example
+
+# Create the cache directories first, this is where the package will be built.
+create_cache
+
+# Build the package(s) you want to build.
+pkg_build cpt
+#+end_src
+
 *** =pkg_owner()=
 :PROPERTIES:
 :DESCRIPTION: Check which package owns the given file
diff --git a/docs/cpt.texi b/docs/cpt.texi
index 71b4e69..bd397ec 100644
--- a/docs/cpt.texi
+++ b/docs/cpt.texi
@@ -127,6 +127,7 @@ System Functions
 
 Package Functions
 
+* @samp{pkg_build()}::
 * @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
@@ -1096,6 +1097,7 @@ are the ones you will use to build, to query, to manipulate, or to otherwise
 interact with packages.
 
 @menu
+* @samp{pkg_build()}::
 * @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
@@ -1104,6 +1106,22 @@ interact with packages.
 * @samp{pkg_gentree}::           Generate a dependency tree for the given package
 @end menu
 
+@node @samp{pkg_build()}
+@subsection @samp{pkg_build()}
+
+This function builds all given packages. It resolves dependencies for the given
+packages, lints the package, extracts its sources and runs the @code{build} script.
+
+@example
+# Example
+
+# Create the cache directories first, this is where the package will be built.
+create_cache
+
+# Build the package(s) you want to build.
+pkg_build cpt
+@end example
+
 @node @samp{pkg_owner()}
 @subsection @samp{pkg_owner()}
 
diff --git a/docs/cpt.txt b/docs/cpt.txt
index f846f12..522d2ae 100644
--- a/docs/cpt.txt
+++ b/docs/cpt.txt
@@ -57,12 +57,13 @@ _________________
 .. 6. System Functions
 ..... 1. `as_root()'
 .. 7. Package Functions
-..... 1. `pkg_owner()'
-..... 2. `pkg_isbuilt()'
-..... 3. `pkg_lint()'
-..... 4. `pkg_find()'
-..... 5. `pkg_get_base()'
-..... 6. `pkg_gentree'
+..... 1. `pkg_build()'
+..... 2. `pkg_owner()'
+..... 3. `pkg_isbuilt()'
+..... 4. `pkg_lint()'
+..... 5. `pkg_find()'
+..... 6. `pkg_get_base()'
+..... 7. `pkg_gentree'
 
 
 This is a reference document containing both the user-guide and the
@@ -1020,7 +1021,25 @@ development manual for *Carbs Packaging Tools*. For development logs see
   manipulate, or to otherwise interact with packages.
 
 
-8.7.1 `pkg_owner()'
+8.7.1 `pkg_build()'
+-------------------
+
+  This function builds all given packages. It resolves dependencies for
+  the given packages, lints the package, extracts its sources and runs
+  the `build' script.
+
+  ,----
+  | # Example
+  | 
+  | # Create the cache directories first, this is where the package will be built.
+  | create_cache
+  | 
+  | # Build the package(s) you want to build.
+  | pkg_build cpt
+  `----
+
+
+8.7.2 `pkg_owner()'
 -------------------
 
   This function can be used to determine the owner of a package. The
@@ -1041,7 +1060,7 @@ development manual for *Carbs Packaging Tools*. For development logs see
   `----
 
 
-8.7.2 `pkg_isbuilt()'
+8.7.3 `pkg_isbuilt()'
 ---------------------
 
   This function returns with success when the given package has a built
@@ -1049,7 +1068,7 @@ development manual for *Carbs Packaging Tools*. For development logs see
   repository.
 
 
-8.7.3 `pkg_lint()'
+8.7.4 `pkg_lint()'
 ------------------
 
   This function checks whether a given package fits the proper package
@@ -1057,7 +1076,7 @@ development manual for *Carbs Packaging Tools*. For development logs see
   outright* if it fails.
 
 
-8.7.4 `pkg_find()'
+8.7.5 `pkg_find()'
 ------------------
 
   `pkg_find()' is the tool for searching packages. It accepts up to 3
@@ -1090,13 +1109,13 @@ development manual for *Carbs Packaging Tools*. For development logs see
   `----
 
 
-8.7.5 `pkg_get_base()'
+8.7.6 `pkg_get_base()'
 ----------------------
 
   This function returns the base packages as defined in `/etc/cpt-base'.
 
 
-8.7.6 `pkg_gentree'
+8.7.7 `pkg_gentree'
 -------------------
 
   Keep in mind /etc/cpt-base