Interaction with Mock
---------------------

`Mock`_ is crucial component for building in Koji. Most build types use mock to
prepare a fresh, isolated environment for building content.

For further reading on the mock tool itself,
see the `mock documentation <https://rpm-software-management.github.io/mock/>`_.



Mock config files
=================

For each buildroot Koji prepares a configuration file for mock to use.
The content of the file depends in part on some administrator's decisions
and can be tweaked by options in the build tag.
These files are managed by kojid and stored under ``/etc/mock/koji`` on
the build host.

Since Koji 1.34.1, builds will save the mock configuration file as a log named
``mock_config.log`` and store it alongside other logs from the build.

The contents of this file are generated by Koji and are affected by:

* :ref:`kojid configuration <mock_kojid_conf>`
* the build tag
* the build arch
* the repo used for the build
* build tag options, see :ref:`tuning-mock-per-tag`
* the controlling build task (e.g. buildArch for rpms)

You can generate mock configs locally in the same way that kojid does.
See :ref:`cli_mock_config`


Site defaults
=============

In addition to the mock configuration file for the buildroot, the mock command
also consults ``/etc/mock/site-defaults.cfg`` on the build host.
You can use this file to set global defaults on your builders.

The following settings are recommended for use with Koji:

   - ``use_bootstrap = False`` - Bootstrap is a) not needed in most cases b)
     slows down the build c) e.g. in combination with next option could lead to
     unreproducible build. While this feature is pretty useful in some cases,
     it should be turned off as default and could be selectively turned on for
     specific buildroots per tag configuration.

   - ``use_bootstrap_image`` - As noted before, this is generally unsafe
     option, especially if used with image tags which are expected to be moved
     (e.g. "latest"). Note, that to use this option (even via tag's
     configuration), you need to explicitly allow it in :doc:`kojid.conf
     <kojid_conf>` via ``mock_bootstrap_image = True``.

   - ``nspawn_args`` - if you want to apply rlimit settings for mock with nspawn
     isolation, you will need to use this option. See :ref:`rlimits_mock` below.

   - ``macros`` - some rpm macros could be defined every time for every build
     based on builder itself. Typical usecase is to limit usage of CPUs on
     given builder by setting ``config_opts['macros']['%_smp_ncpus_max'] = 2``.

   - ``plugin_conf`` - Various plugins could be enabled and configured to be
     available in build environment. Example is `rpmautospec`_ which allows
     various ``%auto*`` macros in spec files.


.. _rlimits_mock:

RLIMIT settings
^^^^^^^^^^^^^^^

When mock uses simple isolation (aka old-chroot), the
:ref:`RLIMIT_* settings <rlimits_kojid>` from ``kojid.conf`` will propagate
to mock.

However, when mock uses nspawn isolation (aka new-chroot, controlled by the
``mock.new_chroot`` tag extra option), these limits are not propagated automatically.
To apply such limits to the mock nspawn chroots, you can add them to the
``nspawn_args`` option in ``site-defaults.cfg``.
For example, you might set:

::

    config_opts['nspawn_args'] = ['--rlimit=RLIMIT_NOFILE=16384:16384']

If your system uses a mix of mock isolation settings, then you will likely want
to apply rlimit settings in *both* ``kojid.conf`` and ``site-defaults.cfg`` for
consistency.


.. _cli_mock_config:

Local mock configs
==================

The ``koji mock-config`` command can be used to generate a mock config file locally
in the same way that the builders do. These can be useful for local testing or debugging.

::

    $ koji mock-config --help
    Usage: koji mock-config [options]
    (Specify the --help global option for a list of other help options)

    Options:
      -h, --help            show this help message and exit
      -a ARCH, --arch=ARCH  Specify the arch
      -n NAME, --name=NAME  Specify the name for the buildroot
      --tag=TAG             Create a mock config for a tag
      --target=TARGET       Create a mock config for a build target
      --task=TASK           Duplicate the mock config of a previous task
      --latest              use the latest redirect url
      --buildroot=BUILDROOT
                            Duplicate the mock config for the specified buildroot
                            id
      --mockdir=DIR         Specify mockdir
      --topdir=DIR          Specify topdir, topdir tops the topurl
      --topurl=URL          URL under which Koji files are accessible, when topdir
                            is specified, topdir tops the topurl
      --distribution=DISTRIBUTION
                            Change the distribution macro
      --yum-proxy=YUM_PROXY
                            Specify a yum proxy
      -o FILE               Output to a file


.. _Mock: https://rpm-software-management.github.io/mock/
.. _rpmautospec: https://docs.pagure.org/fedora-infra.rpmautospec/