From c162907eab36d3099e32f737a26c14d99d91579b Mon Sep 17 00:00:00 2001 From: Marek Blaha Date: Fri, 13 Sep 2024 10:58:39 +0200 Subject: [PATCH] doc: Document arch override for API users We have documentation for CLI users (dnf5-forcearch(7)), but it's not clear how to do the same thing through API. This patch fills the gap. --- doc/misc/forcearch.7.rst | 7 ++++++ doc/tutorial/bindings/python3/session.rst | 14 +++++++++++ doc/tutorial/session.rst | 16 ++++++++++++ .../libdnf5/tutorial/session/force_arch.py | 24 ++++++++++++++++++ .../python3/libdnf5/tutorial/test_tutorial.py | 7 ++++++ test/tutorial/session/force_arch.cpp | 25 +++++++++++++++++++ test/tutorial/test_tutorial.cpp | 5 ++++ test/tutorial/test_tutorial.hpp | 2 ++ 8 files changed, 100 insertions(+) create mode 100644 test/python3/libdnf5/tutorial/session/force_arch.py create mode 100644 test/tutorial/session/force_arch.cpp diff --git a/doc/misc/forcearch.7.rst b/doc/misc/forcearch.7.rst index ba6a41fc8..3cfd0984e 100644 --- a/doc/misc/forcearch.7.rst +++ b/doc/misc/forcearch.7.rst @@ -41,3 +41,10 @@ Examples ``dnf5 repoquery --forcearch=aarch64 --arch=aarch64`` Query all packages available for the AArch64 architecture. If your system has a different native architecture, then both ``--arch`` and ``--forcearch`` are necessary here. ``--arch`` will filter for only packages with the ``aarch64`` architecture, and ``--forcearch`` sets the "arch" and "basearch" substitution variables to ensure the correct repositories are queried. + + +See Also +======== + + | :ref:`Tutorial to override the system architecture for C++ API users ` + | :ref:`Tutorial to override the system architecture for Python API users ` diff --git a/doc/tutorial/bindings/python3/session.rst b/doc/tutorial/bindings/python3/session.rst index 8858a2c44..4f7310478 100644 --- a/doc/tutorial/bindings/python3/session.rst +++ b/doc/tutorial/bindings/python3/session.rst @@ -7,3 +7,17 @@ Creating and configuring a session .. literalinclude:: ../../tests/bindings/python3/session/create_base.py :language: python :linenos: + + +.. _tutorial-bindings-python3-session-force-arch-label: + +Override the system architecture +-------------------------------- + +For the `dnf5` command-line tool, the +:ref:`--forcearch `, :manpage:`dnf5-forcearch(7)` +option is available. Here's how you can achieve the same effect using the Python API: + +.. literalinclude:: ../../tests/bindings/python3/session/force_arch.py + :language: python + :linenos: diff --git a/doc/tutorial/session.rst b/doc/tutorial/session.rst index 655c938f9..f6aa9cefb 100644 --- a/doc/tutorial/session.rst +++ b/doc/tutorial/session.rst @@ -8,3 +8,19 @@ Creating and configuring a session :language: c++ :linenos: :lines: 2,4- + + +.. _tutorial-session-force-arch-label: + +Override the system architecture +-------------------------------- + +For the `dnf5` command-line tool, the +:ref:`--forcearch `, :manpage:`dnf5-forcearch(7)` +option is available. Here's how you can achieve the same effect using the API: + + +.. literalinclude:: tests/session/force_arch.cpp + :language: c++ + :linenos: + :lines: 2,4- diff --git a/test/python3/libdnf5/tutorial/session/force_arch.py b/test/python3/libdnf5/tutorial/session/force_arch.py new file mode 100644 index 000000000..0c98afaee --- /dev/null +++ b/test/python3/libdnf5/tutorial/session/force_arch.py @@ -0,0 +1,24 @@ +import libdnf5 + +# Create a new Base object +base = libdnf5.base.Base() + +# Optionally load configuration from the config files. +base.load_config() + +# Override the detected system architecture, similar to how the +# `--forcearch=aarch64` switch works in the dnf5 command line tool. +vars = base.get_vars().get() +vars.set("arch", "aarch64") + +# This is sufficient for loading repositories and querying packages using the +# `aarch64` architecture. +# However, if you also want to run a transaction (e.g., you want to modify a +# foreign system from "outside" using `installroot`), you need to set the +# `ignorearch` option to instruct RPM to permit packages that are incompatible +# with the system architecture. +base.get_config().get_ignorearch_option().set(True) + +# The base.setup() call configures the architecture for the solver, so the +# `arch` variable needs to be set beforehand. +base.setup() diff --git a/test/python3/libdnf5/tutorial/test_tutorial.py b/test/python3/libdnf5/tutorial/test_tutorial.py index 3beee9942..558a8d601 100644 --- a/test/python3/libdnf5/tutorial/test_tutorial.py +++ b/test/python3/libdnf5/tutorial/test_tutorial.py @@ -90,3 +90,10 @@ def test_transaction(self): exec(file, {'installroot': self.installroot, 'cachedir': self.cachedir, 'baseurl': self.baseurl}) + + def test_force_arch(self): + file = "" + with open("tutorial/session/force_arch.py", "r") as f: + file += f.read() + + exec(file, {'installroot': self.installroot, 'cachedir': self.cachedir}) diff --git a/test/tutorial/session/force_arch.cpp b/test/tutorial/session/force_arch.cpp new file mode 100644 index 000000000..490912b9d --- /dev/null +++ b/test/tutorial/session/force_arch.cpp @@ -0,0 +1,25 @@ +/* includes; won't compile in tests, in the docs we leave out the comment lines to show them +#include +*/ + +// Create a new Base object. +libdnf5::Base base; + +// Optionally load configuration from the config files. +base.load_config(); + +// Override the detected system architecture, similar to how the +// `--forcearch=aarch64` switch works in the dnf5 command line tool. +base.get_vars()->set("arch", "aarch64"); + +// This is sufficient for loading repositories and querying packages using the +// `aarch64` architecture. +// However, if you also want to run a transaction (e.g., you want to modify a +// foreign system from "outside" using `installroot`), you need to set the +// `ignorearch` option to instruct RPM to permit packages that are incompatible +// with the system architecture. +base.get_config().get_ignorearch_option().set(true); + +// The base.setup() call configures the architecture for the solver, so the +// `arch` variable needs to be set beforehand. +base.setup(); diff --git a/test/tutorial/test_tutorial.cpp b/test/tutorial/test_tutorial.cpp index d0348fe2f..e19863c66 100644 --- a/test/tutorial/test_tutorial.cpp +++ b/test/tutorial/test_tutorial.cpp @@ -80,3 +80,8 @@ void TutorialTest::test_transaction() { #include "repo/load_repo.cpp" #include "transaction/transaction.cpp" } + + +void TutorialTest::test_force_arch() { +#include "session/force_arch.cpp" +} diff --git a/test/tutorial/test_tutorial.hpp b/test/tutorial/test_tutorial.hpp index bd273bda7..cdc6ddeea 100644 --- a/test/tutorial/test_tutorial.hpp +++ b/test/tutorial/test_tutorial.hpp @@ -39,6 +39,7 @@ class TutorialTest : public CppUnit::TestCase { CPPUNIT_TEST(test_query); CPPUNIT_TEST(test_transaction); + CPPUNIT_TEST(test_force_arch); CPPUNIT_TEST_SUITE_END(); @@ -51,6 +52,7 @@ class TutorialTest : public CppUnit::TestCase { void test_load_system_repos(); void test_query(); void test_transaction(); + void test_force_arch(); private: std::string baseurl = PROJECT_BINARY_DIR "/test/data/repos-rpm/rpm-repo1/";