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

@@ -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 <tutorial-session-force-arch-label>`
+    | :ref:`Tutorial to override the system architecture for Python API users <tutorial-bindings-python3-session-force-arch-label>`

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 <forcearch_misc_ref-label>`, :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:

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 <forcearch_misc_ref-label>`, :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-

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()

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})

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 <libdnf5/base/base.hpp>
+*/
+
+// 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();

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"
+}

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/";