commit 220298d53572a618e98dfb9e9ae4220bbbf164c3
Author: Michael Simacek <msimacek(a)redhat.com>
Date: Thu Apr 9 18:30:24 2015 +0200
[doc] Dependency handling
doc/dependency_handling.txt | 78 ++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 77 insertions(+), 1 deletions(-)
---
diff --git a/doc/dependency_handling.txt b/doc/dependency_handling.txt
index e67d6b0..dfe8090 100644
--- a/doc/dependency_handling.txt
+++ b/doc/dependency_handling.txt
@@ -1,5 +1,81 @@
WORK IN PROGRESS
-mizdebsk, 25 Oct 2013
+msimacek, 2015-04-09
Describe RPM Provides and Requires, their interactions especially with relation
to JAR file identification, explain mvn(gId:aId...) strings.
+
+RPM has multiple types of metadata to describe dependency relationships
+between packages. The two basic types are Requires and Provides.
+Requires denote that a package needs something to be present at
+runtime to work correctly and the package manager is supposed to ensure
+that requires are met. A single Requires item can specify a package or
+a virtual provide.
+RPM Provides are a way to express that a package provides certain
+capability that other packages might need. In case of Maven packages,
+the Provides are used to denote that a package contains certain Maven
+artifact. They add more flexibility to
+the dependency management as single package can have any number of
+provides, and they can be moved across different packages without
+breaking other packages' requires.
+Provides are usually generated by automatic tools based on the
+information from the built binaries or package source.
+
+.Dependency handling for Maven packages
+The Java packaging tooling on Fedora provides automatic Requires and
+Provides generation for packages built using XMvn. The Provides are based
+on Maven artifact coordinates of artifacts that were installed by the
+currenlty being built. They are generated for each subpackage
+separately. They follow a general format
+`mvn(groupId:artifactId:extension:classifier:version)`, where the
+extension is omitted if it's `jar` and classifier is omitted if empty.
+Version is present only for compat artifacts, but the trailing colon has
+to be present unless it's a Jar artifact with no classifier.
+
+[source,shell]
+--------------
+# Example provide for Jar artifact
+mvn(org.eclipse.jetty:jetty-server)
+# Example provide for POM artifact
+mvn(org.eclipse.jetty:jetty-parent:pom:)
+# Example provide for Jar artifact with classifier
+mvn(org.sonatype.sisu:sisu-guice::no_aop:)
+--------------
+
+The generated Requires are based on dependencies specified in Maven POMs
+in the project. Only dependencies with `scope` set to either `compile`,
+`runtime` or not set at all are used for Requires generation.
+Requires don't rely on package names and instead always
+use virtual provides that were described above, in exactly the same
+format, in order to be satisfieable by the already existing provides.
+For packages consisting of multiple subpackages, Requires are generated
+separately for each subpackage. Additionally, Requires that point to an
+artifact in a different subpackage of the same source package are
+generated with exact versions to prevent version mismatches between
+artifacts belonging to the same project.
+
+The requires generator also always generates Requires on `java-headless`
+and `javapackages-tools`.
+
+.Querying Requires and Provides of built packages
+The generated Requires and Provides of built packages can be queried
+using `rpm`:
+[source,shell]
+--------------
+rpm -qp --provides path/to/example-1.0.noarch.rpm
+rpm -qp --requires path/to/example-1.0.noarch.rpm
+-------------
+
+[TIP]
+=====
+See also <<querying_repositories, Querying Fedora repositories>>
+=====
+
+.Generating BuildRequires
+While Requires and Provides are automated for Maven projects,
+BuildRequires still remain a manual task. However, it can be at least
+a bit simplified. XMvn ships a script `xmvn-builddep` that takes
+a `build.log` output from mock and prints maven-style BuildRequires on
+artifacts that were actually used during the build. It doesn't help you
+to figure out what the BuildRequires are before you actually build it,
+but it may help you to have a minimal set of BuildRequires that are less
+likely to break, as they don't rely on transitive dependencies.
Show replies by date