From: Michael Tremer Date: Tue, 9 Nov 2021 12:50:06 +0000 (+0000) Subject: man: Add documentation for dependencies X-Git-Tag: 0.9.28~883 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7e1245f463ba9fc600bfb88cad8f411953dd4133;p=pakfire.git man: Add documentation for dependencies Signed-off-by: Michael Tremer --- diff --git a/Makefile.am b/Makefile.am index 060edb10a..3d177420c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -567,11 +567,14 @@ dist_macros_DATA = \ # ------------------------------------------------------------------------------ MANPAGES = \ - man/pakfire.8 + man/pakfire.8 \ + man/pakfire-deps.5 -MANPAGES_TXT = $(patsubst %.8,%.txt,$(MANPAGES)) -MANPAGES_HTML = $(patsubst %.txt,%.html,$(MANPAGES_TXT)) -MANPAGES_XML = $(patsubst %.txt,%.xml,$(MANPAGES_TXT)) +MANPAGES_TXT = $(MANPAGES_TXT_5) $(MANPAGES_TXT_8) +MANPAGES_TXT_5 = $(patsubst %.5,%.txt,$(MANPAGES)) +MANPAGES_TXT_8 = $(patsubst %.8,%.txt,$(MANPAGES)) +MANPAGES_HTML = $(patsubst %.txt,%.html,$(MANPAGES_TXT)) +MANPAGES_XML = $(patsubst %.txt,%.xml,$(MANPAGES_TXT)) AM_V_ASCIIDOC = $(AM_V_ASCIIDOC_$(V)) AM_V_ASCIIDOC_ = $(AM_V_ASCIIDOC_$(AM_DEFAULT_VERBOSITY)) @@ -617,6 +620,9 @@ man/%.xml: man/%.txt man/asciidoc.conf -f $(abs_srcdir)/man/asciidoc.conf \ -d manpage -b docbook -o $@ $< +man/%.5: man/%.xml + $(XSLTPROC_COMMAND_MAN) + man/%.8: man/%.xml $(XSLTPROC_COMMAND_MAN) diff --git a/man/pakfire-deps.txt b/man/pakfire-deps.txt new file mode 100644 index 000000000..943a0cdc9 --- /dev/null +++ b/man/pakfire-deps.txt @@ -0,0 +1,152 @@ += pakfire-deps(5) + +== NAME +pakfire-deps - Information about dependencies in Pakfire + +== DESCRIPTION +This page describes how dependencies between packages are expressed in Pakfire. + +Pakfire has a versatile and powerful dependency solving mechanism that is based +on a SAT solver which will always find the best solution in the dependency tree +if one is available. It does that in very short time as well. + +In order to figure out a solution in the dependency graph, the algorithm has to +be fed with a lot of information which is described in this document. + +== DEFINITIONS + +'EVR':: + Short for epoch, version and release. For example 1.0-42, or 1:47.11-1. + +'Capability':: + A name (e.g. `bash`) of a package with an optional operator and EVR. + + + For example: `bash = 5.2` or `bash >= 5.0` + +Dependencies are divided into two categories: Strong vs. weak dependencies + +Strong dependencies have to be fulfilled at all times, whereas weak dependencies +can be optional and are being used to give "recommendations" to the solver and +the user. + +== STRONG DEPENDENCIES + +'Requires':: + A list of dependencies that all have to be fulfilled in order to install this + package. + +'Provides':: + A list of capabilities provided by this package. Requires of other packages + are being matched against this list. + +'Conflicts':: + The package cannot be installed if one or more of capabilities on this list + match. + +'Obsoletes':: + When this package is installed, all other packages that match any of the + capabilities will be uninstalled. + +== WEAK DEPENDENCIES + +'Recommends':: + A weak version of 'Requires'. Packages that match will be installed, but + ignored if they cannot be installed. + +'Suggests':: + Suggests are hints for the user, but not handled during dependency resolution. + + + "Customers who bought this also bought..." + +== REVERSE DEPENDENCIES + +'Supplements':: + A reverse version of 'Recommends'. This package will be installed if another + package that provides a matching capability is being installed. + +'Enhances':: + A reverse version of 'Suggests'. + +== RELATIONS + +Package dependencies can be expressed in various ways. The most simple one is to +list the name of another package. For example: `python3`. This will cause that +a package that provides `python3` is being installed. + +You can use operators and EVRs to select a specific version: + +'package = EVR':: + The package must be exactly the given version. + +'package >= EVR':: + The package must be the given version or newer. + +'package <= EVR':: + The package can be up to and including this version. + +'package > EVR':: + The package must be newer than this version. + +'package < EVR':: + The package must be older than this version. + +'package':: + This package can be of any version. + +In addition to the version comparison operators, Pakfire supports boolean operators +which are also called "Rich Dependencies". They have to be wrapped in brackets. + +'(package and package)':: + Requires all operands to be true for the entire term to be true. + + + For example: `Conflicts: (foo and bar)` + +'(package or package)':: + Requires at least one of the operands to be true. + + + For example: `Requires: (foo >= 3.2 or bar)` + +'(package if package)':: + Requires the first operand to be fulfilled if the second is + (reverse implication). + + + For example: `Recommends: (foo-feature if feature)` + +'(package if package else package)':: + Same as above, but requires the third operand to be fulfilled if the second is not. + + + For example: `Requires: (foo-feature if feature else foo-other-feature)` + +'(package unless package)':: + Requires the first operand to be fulfilled if the second is not + (reverse negative implication). + + + For example: `Conflicts: (foo-feature unless feature)` + +'(package unless package else package)':: + Same as above, but requires the third operand to be fulfulled if the second is. + + + For example: `Conflicts: (foo-feature1 unless feature2 else foo-feature2)` + +'(package with package)':: + Requires all operands to be fulfilled by the same package for the term to be true. + + + For example: `Requires: (pkg-foo with pkg-bar)` + +'(package without package)':: + Requires a single package that satisfies the first operand but not the second + (set subtraction). + + + For example: `Requires: (pkg-foo without pkg-bar)` + +The 'if' operator cannot be used in the same context with 'or' and the 'unless' operator +cannot be used in the same context with 'and'. + +Rich dependencies can be nested like so: + +* `Requires: (foo or bar or baz)` +* `Requires: (foo or (bar and baz))` +* `Requires: ((pkg1 with feature2) or (pkg2 without feature1))` + +== AUTHORS +Michael Tremer