util.content
============

.. py:module:: util.content

.. autoapi-nested-parse::

   Utility functions for acquiring binary/source CaC/content.

   Content can come from two sources:
    - CONTEST_CONTENT as a git-repo-style directory
    - scap-security-guide RPM

   Each of these has binary/sources on different places:
    - CONTEST_CONTENT
      - binary content needs to be built, is located in build/*
      - source content already exists as the directory itself
    - scap-security-guide RPM
      - binary content already exists in /usr/share
      - source content needs to be downloaded as SRPM

   Unifying these under one API is therefore a significant challenge,
   especially since the scap-security-guide RPM fragments binary content
   to multiple paths in /usr/share.

   This module therefore provides
    - several get_*() functions for getting binary content
      - if CONTEST_CONTENT is used, the content is built as-needed
    - one get_content_source() function for getting source content
      - if scap-security-guide RPM is used, a SRPM gets downloaded + extracted

   The get_*() functions for binary content prefer CONTEST_CONTENT (if it is
   defined) over the scap-security-guide RPM content. This can be overriden
   with a function argument.

   It is assumed only one process/thread is using either content location,
   and downloaded SRPM sources or built CONTEST_CONTENT content is left
   for further tests to be re-used if possible.

   If a test needs binary content built with specific flags/options, or access
   any binary artifacts other than what is provided here via get_*(), it should
   get_source_content() and call build_content() on it, or build it itself.







Module Contents
---------------

.. py:data:: CONTENT_BUILD_DIR
   :value: 'build'


.. py:function:: get_user_content(build=True)

.. py:function:: find_datastreams(force_ssg, content_dir=None)

.. py:function:: get_datastream(force_ssg=False, content_dir=None)

.. py:function:: iter_datastreams(force_ssg=False, content_dir=None)

.. py:function:: find_playbooks(force_ssg=False, content_dir=None)

.. py:function:: find_per_rule_playbooks(force_ssg=False, content_dir=None)

.. py:function:: get_playbook(profile, force_ssg=False, content_dir=None)

.. py:function:: iter_playbooks(force_ssg=False, content_dir=None)

.. py:function:: get_kickstart(profile, content_dir=None)

.. py:function:: build_content(path, extra_cmake_opts=None, force=False)

   Given a CaC/content source as 'path', build it with some sensible CMake
   options.

   Specify any additional ones as 'extra_cmake_opts' (dict); make sure to use
   the full option name with :DATATYPE as visible in CMakeCache.txt.
   See also https://cmake.org/cmake/help/latest/prop_cache/TYPE.html.

   Set 'force=True' to always re-build content, even with compatible options.


.. py:function:: get_source_content()

   Acquire and return a path to a CaC/content style content source distribution
   from either a user-provided directory or a SRPM.