From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 8840B1396D0 for ; Wed, 4 Oct 2017 18:33:00 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id C80CB2BC00B; Wed, 4 Oct 2017 18:32:59 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 9AFCA2BC00B for ; Wed, 4 Oct 2017 18:32:59 +0000 (UTC) Received: from oystercatcher.gentoo.org (unknown [IPv6:2a01:4f8:202:4333:225:90ff:fed9:fc84]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 5841D3416BB for ; Wed, 4 Oct 2017 18:32:58 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id E535E746E for ; Wed, 4 Oct 2017 18:32:56 +0000 (UTC) From: "Zac Medico" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Zac Medico" Message-ID: <1507141872.d93c62eab16b1ecb09766448f8dbc12a2e17d933.zmedico@gentoo> Subject: [gentoo-commits] proj/portage:master commit in: pym/_emerge/resolver/, pym/_emerge/ X-VCS-Repository: proj/portage X-VCS-Files: pym/_emerge/depgraph.py pym/_emerge/resolver/package_tracker.py X-VCS-Directories: pym/_emerge/resolver/ pym/_emerge/ X-VCS-Committer: zmedico X-VCS-Committer-Name: Zac Medico X-VCS-Revision: d93c62eab16b1ecb09766448f8dbc12a2e17d933 X-VCS-Branch: master Date: Wed, 4 Oct 2017 18:32:56 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: f7a6d281-983f-4926-b095-727a6e0fe984 X-Archives-Hash: 1b7698a41328588fbea68977238ff8aa commit: d93c62eab16b1ecb09766448f8dbc12a2e17d933 Author: Daniel Robbins funtoo org> AuthorDate: Wed Oct 4 18:10:09 2017 +0000 Commit: Zac Medico gentoo org> CommitDate: Wed Oct 4 18:31:12 2017 +0000 URL: https://gitweb.gentoo.org/proj/portage.git/commit/?id=d93c62ea _dynamic_depgraph_config: new digraph docs Closes: https://github.com/gentoo/portage/pull/217 pym/_emerge/depgraph.py | 41 +++++++++++++++++++++++++++++++++ pym/_emerge/resolver/package_tracker.py | 12 +++++----- 2 files changed, 47 insertions(+), 6 deletions(-) diff --git a/pym/_emerge/depgraph.py b/pym/_emerge/depgraph.py index 0b9b98dbb..751111fb3 100644 --- a/pym/_emerge/depgraph.py +++ b/pym/_emerge/depgraph.py @@ -357,6 +357,47 @@ class _rebuild_config(object): class _dynamic_depgraph_config(object): + """ + ``dynamic_depgraph_config`` is an object that is used to collect settings and important data structures that are + used in calculating Portage dependencies. Each depgraph created by the depgraph.py code gets its own + ``dynamic_depgraph_config``, whereas ``frozen_depgraph_config`` is shared among all depgraphs. + + **self.digraph** + + Of particular importance is the instance variable ``self.digraph``, which is an instance of + ``portage.util.digraph``, a directed graph data structure. ``portage.util.digraph`` is used for a variety of + purposes in the Portage codebase, but in this particular scenario as ``self.digraph``, it is used to create a + dependency tree of Portage packages. So for ``self.digraph``, each *node* of the directed graph is a ``Package``, + while *edges* connect nodes and each edge can have a Priority. The Priority setting is used to help resolve + circular dependencies, and should be interpreted in the direction of parent to child. + + Conceptually, think of ``self.digraph`` as containing user-specified packages or sets at the very top, with + dependencies hanging down as children, and dependencies of those children as children of children, etc. The depgraph + is intended to model dependency relationships, not the order that packages should be installed. + + **resolving the digraph** + + To convert a digraph to an ordered list of packages to merge in an order where all dependencies are properly + satisfied, we would first start by looking at leaf nodes, which are nodes that have no dependencies of their own. We + could then traverse the digraph upwards from the leaf nodes, towards the parents. Along the way, depending on emerge + options, we could make decisions what packages should be installed or rebuilt. This is how ``self.digraph`` is used + in the code. + + **digraph creation** + + The ``depgraph.py`` code creates the digraph by first adding emerge arguments to the digraph as the main parents, + so if ``@world`` is specified, then the world set is added as the main parents. Then, ``emerge`` will determine + the dependencies of these packages, and depending on what options are passed to ``emerge``, will look at installed + packages, binary packages and available ebuilds that could be merged to satisfy dependencies, and these will be + added as children in the digraph. Children of children will be added as dependencies as needed, depending on the + depth setting used by ``emerge``. + + As the digraph is created, it is perfectly fine for Packages to be added to the digraph that conflict with one + another. After the digraph has been fully populated to the necessary depth, code within ``depgraph.py`` will + identify any conflicts that are modeled within the digraph and determine the best way to handle them. + + """ + def __init__(self, depgraph, myparams, allow_backtracking, backtrack_parameters): self.myparams = myparams.copy() self._vdb_loaded = False diff --git a/pym/_emerge/resolver/package_tracker.py b/pym/_emerge/resolver/package_tracker.py index 06163574e..ccb0b11cf 100644 --- a/pym/_emerge/resolver/package_tracker.py +++ b/pym/_emerge/resolver/package_tracker.py @@ -42,13 +42,13 @@ class PackageTracker(object): considering installing on the system, based on the information in Portage's dependency graph. Multiple roots are supported, so that situations can be modeled where ROOT is set to a non-default value (non-``/``). - You can use the add_pkg() method to add a to-be-merged package to the PackageTracker, and ``add_installed_pkg()`` - to add an already-installed package to the package tracker. Typical use of the package tracker involves the - depgraph.py code populating the package tracker with calls to ``add_installed_pkg()`` to add all installed packages - on the system, and then it is initialized and ready for use. At that point, ``depgraph.py`` can use ``add_pkg()`` - to add to-be-installed packages to the system. + You can use the add_pkg() method to add a to-be-merged package to the PackageTracker, and ``add_installed_pkg()`` to + add an already-installed package to the package tracker. Typical use of the package tracker involves the + ``depgraph.py`` code populating the package tracker with calls to ``add_installed_pkg()`` to add all installed + packages on the system, and then it is initialized and ready for use. At that point, ``depgraph.py`` can use + ``add_pkg()`` to add to-be-installed packages to the system. - It's worth mentioning that PackageTracker uses ``Package`` objects as arguments, and stores these objects + It's worth mentioning that ``PackageTracker`` uses ``Package`` objects as arguments, and stores these objects internally. There are parts of the code that ensure that a ``Package`` instance is added to the PackageTracker only once.