1.. 2 Copyright (C) 2015 Red Hat, Inc. 3 4 This copyrighted material is made available to anyone wishing to use, 5 modify, copy, or redistribute it subject to the terms and conditions of 6 the GNU General Public License v.2, or (at your option) any later version. 7 This program is distributed in the hope that it will be useful, but WITHOUT 8 ANY WARRANTY expressed or implied, including the implied warranties of 9 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 10 Public License for more details. You should have received a copy of the 11 GNU General Public License along with this program; if not, write to the 12 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 13 02110-1301, USA. Any Red Hat trademarks that are incorporated in the 14 source code or documentation are not subject to the GNU General Public 15 License and may only be used or replicated with the express permission of 16 Red Hat, Inc. 17 18############### 19 DNF Use Cases 20############### 21 22.. contents:: 23 24============== 25 Introduction 26============== 27 28Every feature present in DNF should be based on a reasonable use case. All the 29supported use cases are supposed to be enumerated in this document. 30 31In case you use DNF to achieve a goal which is not documented here, either you 32found an error in the documentation or you misuse DNF. In either case we would 33appreciate if you share the case with us so we can help you to use DNF in the 34correct way or add the case to the list. You can only benefit from such a 35report because then you can be sure that the behavior that you expect will not 36change without prior notice in the :doc:`release_notes` and that the behavior 37will be covered by our test suite. 38 39.. IMPORTANT:: 40 41 Please consult every usage of DNF with our reference documentation to be sure 42 what are you doing. The examples mentioned here are supposed to be as simple 43 as possible and may ignore some minor corner cases. 44 45.. WARNING:: 46 47 The list is not complete yet - the use cases are being added incrementally 48 these days. 49 50===================== 51 General assumptions 52===================== 53 54The user in question must have the appropriate permissions. 55 56.. _install_use_case-label: 57 58======================================================================================== 59 Ensure that my system contains given mix of features (packages/files/providers/groups) 60======================================================================================== 61 62A system administrator has a list of features that has to be present in an 63operating system. The features must be provided by RPM packages in system 64repositories that must be accessible. 65 66A feature may be for example a concrete version of a package 67(``hawkey-0.5.3-1.fc21.i686``), a pathname of a binary RPM file 68(``/var/lib/mock/fedora-21-i386/result/hawkey-0.5.3-2.20150116gitd002c90.fc21.i686.rpm``), 69an URL of a binary RPM file 70(``http://jenkins.cloud.fedoraproject.org/job/DNF/lastSuccessfulBuild/artifact/fedora-21-i386-build/hawkey-0.5.3-99.649.20150116gitd002c90233fc96893806836a258f14a50ee0cf47.fc21.i686.rpm``), 71a configuration file (``/etc/yum.repos.d/fedora-rawhide.repo``), a language 72interpreter (``ruby(runtime_executable)``), an extension (``python3-dnf``), a 73support for building modules for the current running kernel 74(``kernel-devel-uname-r = $(uname -r)``), an executable (``*/binaryname``) or a 75collection of packages specified by any available identifier (``kde-desktop``). 76 77The most recent packages that provide the missing features and suit 78installation (that are not obsoleted and do not conflict with each other or 79with the other installed packages) are installed if the given feature is not 80present already. If any of the packages cannot be installed, the operation 81fails. 82 83----- 84 CLI 85----- 86 87:: 88 89 SPECS="hawkey-0.5.3-1.fc21.i686 @kde-desktop" # Set the features here. 90 91 dnf install $SPECS 92 93----------------- 94 Plugins/CLI API 95----------------- 96 97.. include:: examples/install_plugin.py 98 :code: python 99 :start-line: 16 100 101If it makes a sense, the plugin can do the operation in appropriate hooks 102instead of registering a new command that needs to be called from the command 103line. 104 105--------------- 106 Extension API 107--------------- 108 109.. include:: examples/install_extension.py 110 :code: python 111 :start-line: 16 112 113========================================================================= 114Get a list of available packages filtered by their relation to the system 115========================================================================= 116 117A system user wants to obtain a list of available RPM packages for their 118consecutive automatic processing or for informative purpose only. 119The list of RPM packages is filtered by requested relation to the system 120or user provided <package-name-specs>. The obtained list of packages 121is based on available data supplied by accessible system repositories. 122 123A relation to the system might be for example one of the following: 124 125installed - packages already installed on the system 126 127available - packages available in any accessible repository 128 129extras - packages installed on the system not available in any known 130repository 131 132obsoletes - installed packages that are obsoleted by packages in any 133accessible repository 134 135recent - packages recently added into accessible repositories 136 137upgrades - available packages upgrading some installed packages 138 139----- 140CLI 141----- 142 143:: 144 145 dnf list *dnf* 146 dnf list installed *debuginfo 147 dnf list available gtk*devel 148 dnf list extras 149 dnf list obsoletes 150 dnf list recent 151 dnf list upgrades 152 153----------------- 154Plugins/CLI API 155----------------- 156 157.. include:: examples/list_obsoletes_plugin.py 158 :code: python 159 :start-line: 16 160 161--------------- 162Extension API 163--------------- 164 165.. include:: examples/list_extras_extension.py 166 :code: python 167 :start-line: 16 168