diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cpt.org | 150 | ||||
| -rw-r--r-- | docs/cpt.texi | 143 | ||||
| -rw-r--r-- | docs/default.do | 33 |
3 files changed, 313 insertions, 13 deletions
diff --git a/docs/cpt.org b/docs/cpt.org index bff8ac9..dfddc38 100644 --- a/docs/cpt.org +++ b/docs/cpt.org @@ -48,7 +48,9 @@ manual for *Carbs Packaging Tools*. For development logs see [[https://git.carbs - [[#option-parsing][Option parsing]] - [[#message-functions][Message functions]] - [[#text-functions][Text functions]] + - [[#portability-functions][Portability functions]] - [[#system-functions][System Functions]] + - [[#package-functions][Package Functions]] * Copying :PROPERTIES: @@ -890,11 +892,11 @@ Following functions are used to manipulate, check, or interact with text. given string. If the string is inside the list, it will return 0, otherwise 1. #+begin_src sh - # Usage - contains "$LIST" foo +# Usage +contains "$LIST" foo - contains "foo bar" foo # Returns 0 - contains "foo bar" baz # Returns 1 +contains "foo bar" foo # Returns 0 +contains "foo bar" baz # Returns 1 #+end_src *** =regesc()= @@ -906,7 +908,7 @@ given string. If the string is inside the list, it will return 0, otherwise 1. in POSIX BRE. Those characters are, =$=, =.=, =*=, =[=, =\\=, and =^=. #+begin_src sh - regesc '^[$\' # Returns \^\[\$\\ +regesc '^[$\' # Returns \^\[\$\\ #+end_src *** =pop()= @@ -918,13 +920,75 @@ in POSIX BRE. Those characters are, =$=, =.=, =*=, =[=, =\\=, and =^=. call. Word splitting is intentional when using this function. #+begin_src sh - # Usage - pop foo from $LIST +# Usage +pop foo from $LIST - pop foo from foo baz bar # Returns baz bar +pop foo from foo baz bar # Returns baz bar #+end_src -** System Functions +*** =sepchar()= +:PROPERTIES: +:DESCRIPTION: Separate characters from a string +:END: + +This function can be used to separate characters from the given string without +resorting to external resources. + +#+begin_src sh +sepchar mystring +# Prints: +# m +# y +# s +# t +# r +# i +# n +# g +#+end_src + +** Portability functions +:PROPERTIES: +:DESCRIPTION: Functions to replace non-POSIX commands +:END: + +These helper functions are used so that we don't depend on non-POSIX programs for +certain functionality. They are prefixed with the =_= character. + +*** =_seq()= +:PROPERTIES: +:DESCRIPTION: 'seq(1)' but no newline +:END: + +This function is similar to =seq(1)= except that it only takes a single argument +and doesn't print any newlines. It is suitable to be used in =for= loops. + +#+begin_src sh +_seq 5 +# Prints: +# 1 2 3 4 5 +#+end_src + +*** =_stat()= +:PROPERTIES: +:DESCRIPTION: 'stat %U' replacement +:END: + +This function imitates =stat %U=. =stat= isn't defined by POSIX, and this is +also a GNU extension. This function returns the owner of a file. If the owner +cannot be found, it will return =root=. + +*** =_readlinkf()= +:PROPERTIES: +:DESCRIPTION: 'readlink -f' replacement +:END: + +This function was taken from [[https://github.com/ko1nksm/readlinkf][POSIX sh readlinkf library by Koichi Nakashima]]. +=readlink= is also not defined by POSIX, so this function uses =ls= to follow +symbolic links until it reaches the actual file. + +** TODO System Functions +- [ ] Add description *** =as_root()= :PROPERTIES: :DESCRIPTION: Run a command as the root user @@ -935,6 +999,68 @@ environment variable is set, it will call the following arguments as the root user. It supports the following programs for privilege escalation with the following order: -1. =sudo= -2. =doas= -3. =su= +1. =sls= +2. =sudo= +3. =doas= +4. =su= + +** TODO Package Functions +:PROPERTIES: +:DESCRIPTION: Manipulate, or query anything related to packages +:END: + +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_owner()= +:PROPERTIES: +:DESCRIPTION: Check which package owns the given file +:END: + +This function can be used to determine the owner of a package. The first +argument is used for flags that will be passed to =grep=, and the second one is +for the file query. Rest of the arguments can be used in order to specify the +manifests to be used, but it is optional. =pkg_owner()= will search for all the +installed packages if no other arguments are given. + +#+begin_src sh +# Example +pkg_owner -lFx /usr/bin/grep # Returns 'busybox' + +# An example call made by `pkg_fix_deps()` to figure out whether the built +# package contains the file it depends. +pkg_owner -l "/${dep#/}\$" "$PWD/manifest" >/dev/null && continue +pkg_owner -l "/${dep#/}\$" "$@" ||: +#+end_src + +*** =pkg_isbuilt()= +:PROPERTIES: +:DESCRIPTION: Check whether the given package is built +:END: + +This function returns with success when the given package has a built tarball +with the matching version and release strings from the repository. + +*** =pkg_lint()= +:PROPERTIES: +:DESCRIPTION: Check whether a package directory fits the standards +:END: + +This function checks whether a given package fits the proper package +specification. This function *does not return with failure, it exits outright* +if it fails. + +*** TODO =pkg_find()= +:PROPERTIES: +:DESCRIPTION: Query package locations +:END: + +=pkg_find()= + +*** TODO =pkg_gentree= +:PROPERTIES: +:DESCRIPTION: Generate a dependency tree for the given package +:END: + +Keep in mind /etc/cpt-base diff --git a/docs/cpt.texi b/docs/cpt.texi index 9a9974f..7c1a95f 100644 --- a/docs/cpt.texi +++ b/docs/cpt.texi @@ -106,7 +106,9 @@ CPT Library * Option parsing:: Easy way of parsing options with cpt-lib * Message functions:: Communicate to users * Text functions:: Manipulate or check text +* Portability functions:: Functions to replace non-POSIX commands * System Functions:: +* Package Functions:: Manipulate, or query anything related to packages Option parsing @@ -126,11 +128,26 @@ Text functions * @samp{contains()}:: Check if a "string list" contains a word * @samp{regesc()}:: Escape regular expression characters * @samp{pop()}:: Remove an item from a string list +* @samp{sepchar()}:: Separate characters from a string + +Portability functions + +* @samp{_seq()}:: 'seq(1)' but no newline +* @samp{_stat()}:: 'stat %U' replacement +* @samp{_readlinkf()}:: 'readlink -f' replacement System Functions * @samp{as_root()}:: Run a command as the root user +Package Functions + +* @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_gentree}:: Generate a dependency tree for the given package + @end detailmenu @end menu @@ -888,7 +905,9 @@ package manager library. * Option parsing:: Easy way of parsing options with cpt-lib * Message functions:: Communicate to users * Text functions:: Manipulate or check text +* Portability functions:: Functions to replace non-POSIX commands * System Functions:: +* Package Functions:: Manipulate, or query anything related to packages @end menu @node Calling the library @@ -1048,6 +1067,7 @@ Following functions are used to manipulate, check, or interact with text. * @samp{contains()}:: Check if a "string list" contains a word * @samp{regesc()}:: Escape regular expression characters * @samp{pop()}:: Remove an item from a string list +* @samp{sepchar()}:: Separate characters from a string @end menu @node @samp{contains()} @@ -1087,8 +1107,70 @@ pop foo from $LIST pop foo from foo baz bar # Returns baz bar @end example +@node @samp{sepchar()} +@subsection @samp{sepchar()} + +This function can be used to separate characters from the given string without +resorting to external resources. + +@example +sepchar mystring +# Prints: +# m +# y +# s +# t +# r +# i +# n +# g +@end example + +@node Portability functions +@section Portability functions + +These helper functions are used so that we don't depend on non-POSIX programs for +certain functionality. They are prefixed with the @samp{_} character. + +@menu +* @samp{_seq()}:: 'seq(1)' but no newline +* @samp{_stat()}:: 'stat %U' replacement +* @samp{_readlinkf()}:: 'readlink -f' replacement +@end menu + +@node @samp{_seq()} +@subsection @samp{_seq()} + +This function is similar to @samp{seq(1)} except that it only takes a single argument +and doesn't print any newlines. It is suitable to be used in @samp{for} loops. + +@example +_seq 5 +# Prints: +# 1 2 3 4 5 +@end example + +@node @samp{_stat()} +@subsection @samp{_stat()} + +This function imitates @samp{stat %U}. @samp{stat} isn't defined by POSIX, and this is +also a GNU extension. This function returns the owner of a file. If the owner +cannot be found, it will return @samp{root}. + +@node @samp{_readlinkf()} +@subsection @samp{_readlinkf()} + +This function was taken from @uref{https://github.com/ko1nksm/readlinkf, POSIX sh readlinkf library by Koichi Nakashima}. +@samp{readlink} is also not defined by POSIX, so this function uses @samp{ls} to follow +symbolic links until it reaches the actual file. + @node System Functions -@section System Functions +@section @strong{TODO} System Functions + +@itemize +@item +Add description +@end itemize @menu * @samp{as_root()}:: Run a command as the root user @@ -1104,6 +1186,8 @@ following order: @enumerate @item +@samp{sls} +@item @samp{sudo} @item @samp{doas} @@ -1111,4 +1195,61 @@ following order: @samp{su} @end enumerate +@node Package Functions +@section @strong{TODO} Package Functions + +Obviously, package functions are the most important ones for @samp{cpt-lib}, those +are the ones you will use to build, to query, to manipulate, or to otherwise +interact with packages. + +@menu +* @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_gentree}:: Generate a dependency tree for the given package +@end menu + +@node @samp{pkg_owner()} +@subsection @samp{pkg_owner()} + +This function can be used to determine the owner of a package. The first +argument is used for flags that will be passed to @samp{grep}, and the second one is +for the file query. Rest of the arguments can be used in order to specify the +manifests to be used, but it is optional. @samp{pkg_owner()} will search for all the +installed packages if no other arguments are given. + +@example +# Example +pkg_owner -lFx /usr/bin/grep # Returns 'busybox' + +# An example call made by `pkg_fix_deps()` to figure out whether the built +# package contains the file it depends. +pkg_owner -l "/$@{dep#/@}\$" "$PWD/manifest" >/dev/null && continue +pkg_owner -l "/$@{dep#/@}\$" "$@@" ||: +@end example + +@node @samp{pkg_isbuilt()} +@subsection @samp{pkg_isbuilt()} + +This function returns with success when the given package has a built tarball +with the matching version and release strings from the repository. + +@node @samp{pkg_lint()} +@subsection @samp{pkg_lint()} + +This function checks whether a given package fits the proper package +specification. This function @strong{does not return with failure, it exits outright} +if it fails. + +@node @samp{pkg_find()} +@subsection @strong{TODO} @samp{pkg_find()} + +@samp{pkg_find()} + +@node @samp{pkg_gentree} +@subsection @strong{TODO} @samp{pkg_gentree} + +Keep in mind /etc/cpt-base + @bye
\ No newline at end of file diff --git a/docs/default.do b/docs/default.do new file mode 100644 index 0000000..fcf8802 --- /dev/null +++ b/docs/default.do @@ -0,0 +1,33 @@ +SRC_ROOT=.. +. ../config.rc + +# Extensionless name of file +fn="${1%.*}" + +case "$1" in + all) redo info ;; + allclean) redo ../clean; rm -f cpt.texi ;; + info) redo-ifchange cpt.info cpt.texi cpt.org ;; + *.info) + # Don't bother if makeinfo doesn't exist on the system, exit with success. + if ! command -v $MAKEINFO >/dev/null; then + PHONY + exit 0 + fi + redo-ifchange "$fn.texi" + $MAKEINFO "$fn.texi" -o "$3" + ;; + *.texi) + [ -f "$fn.org" ] || exit 0 + redo-ifchange "$fn.org" + cp "$fn.org" "$3.org" + $EMACS "$3.org" --batch -f org-texinfo-export-to-texinfo + rm -f "$3.org" + mv "$3.texi" "$3" + ;; + *) + echo "Unknown target $1" + exit 99 +esac + +PHONY all info html |