tools/documentation/tfm_cmake_defaults.py

# -----------------------------------------------------------------------------
# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause
#
# -----------------------------------------------------------------------------

# This module is providing the default parameters for manual Documentation
# building. ( Without relying on CMake to determine the enviroment )
#
# It will however be able to communicate parameters when populated
# by CMake (using the tfm_env.py file), and use a best-effort approach
# to determine them when the interface file is not preset.

import os
import re
import json
from subprocess import check_output
from platform import system

# When called after cmake an evniroment variables file will be present
try:
    from tfm_env import cmake_env
except Exception as E:
    print("ERROR: Configuration Exception:", E)
    cmake_env = None

tfm_def_render_cmake = True
tfm_def_copy_files = True
tfm_def_build_doxygen = True


def find_tfm_root(start_dir=os.path.dirname(os.path.abspath(__file__)),
                  target_files=["license.rst",
                                "dco.txt",
                                "toolchain_GNUARM.cmake"],
                  max_depth=5):
    """ Method which attempts to find the root of the project
    by traversing parent directoried and attempts to located each of the
    files included in target_files list"""

    tfm_root = start_dir

    for i in range(max_depth):
        tfm_root = os.path.dirname(tfm_root)
        if set(target_files).issubset(set(os.listdir(tfm_root))):
            return tfm_root
    return None


def find_package(binary_name):
    """ Attempts to resolve the abolute path for a given application or return
    empty string is nothing is found"""

    sys_det = system()

    if sys_det == "Windows":
        cmd = "where"
        # Window's where requires the extension
        binary_name = binary_name + ".exe"
    elif sys_det in ["Darwin", "Linux"]:
        cmd = "which"
    try:
        return check_output([cmd, binary_name]).decode('UTF-8').strip()
    except Exception as E:
        return ""


def render_cmake_file(config_map, in_file, out_file):
    """ Read an input file containing CMAKE variables and try to
    render them based on a configuration map. Variables not listed
    on the map will be cleared """

    # Read the input file
    with open(in_file, "r", encoding='utf-8') as F:
        _data = F.read()

    # Render all config entires included in the map
    for k, v in config_map.items():
        v = v.replace("\\", "\\\\")
        _data = re.sub(r'@%s@' % k, r'%s' % v, _data)

    # Set all remaining entries to blank
    _data = re.sub(r'@[A-Z\_]+@', "", _data)

    # Create output file
    with open(out_file, "w", encoding='utf-8') as F:
        F.write(_data)


# Default output director for reference_manual. It should not be empty
tfm_def_doxy_output_dir = "reference_manual"


if cmake_env is None:
    # #################### Automatic Defaults ( Standalone )################# #

    # Resolve  ../../
    tfm_def_root_dir = find_tfm_root()

    # Set the copy files directory to whatever will be passed to sphynx-build
    tfm_def_copy_dir = os.path.abspath(os.getcwd())

    # Documentation base path
    tfm_def_doc_root = os.path.join(tfm_def_root_dir, "docs")
    tfm_def_copy_doc_root = os.path.join(tfm_def_copy_dir, "docs")

    tfm_def_doxy_root = os.path.join(tfm_def_doc_root, "doxygen")

    tfm_def_doxy_output_dir = os.path.join(tfm_def_copy_dir,
                                           tfm_def_doxy_output_dir)

    # Input files ( Files containing CMAKE variables )
    tfm_def_conf_in_file = os.path.join(tfm_def_doc_root, "conf.py.in")
    tfm_def_doxygen_in_file = os.path.join(tfm_def_doxy_root, "Doxyfile.in")

    # Attempt to detect plantUML
    _ubuntu_plantum_loc = "/usr/share/plantuml/plantuml.jar"
    if "PLANTUML_JAR_PATH" in os.environ.keys():
        tfm_def_plantum_loc = os.environ["PLANTUML_JAR_PATH"]
    elif os.path.isfile(_ubuntu_plantum_loc):
        tfm_def_plantum_loc = _ubuntu_plantum_loc
    else:
        tfm_def_plantum_loc = ""

    # Attempt to detect the java interpreter location
    tfm_def_java_binary = find_package("java")
    tfm_def_doxygen_loc = find_package("doxygen")
    tfm_def_doxygen_dot_loc = find_package("dot")

else:
    # #################### Cmake Defaults ################################## #
    tfm_def_root_dir = os.path.abspath(cmake_env["TFM_ROOT_DIR"])
    tfm_def_copy_dir = os.path.abspath(cmake_env["SPHINX_TMP_DOC_DIR"])
    tfm_def_plantum_loc = os.path.abspath(cmake_env["PLANTUML_JAR_PATH"])
    tfm_def_java_binary = os.path.abspath(cmake_env["Java_JAVA_EXECUTABLE"])
    tfm_def_tfm_version = cmake_env["SPHINXCFG_TFM_VERSION"]
    tfm_def_conf_in_file = cmake_env["SPHINXCFG_TEMPLATE_FILE"]

    tfm_def_copy_files = True if cmake_env["SPHINXCFG_COPY_FILES"] == "True" \
        else False
    tfm_def_render_cmake = True \
        if cmake_env["SPHINXCFG_RENDER_CONF"] == "True" else False

    tfm_def_build_doxygen = True \
        if cmake_env["DOXYCFG_DOXYGEN_BUILD"] == "True" else False

    if tfm_def_build_doxygen:
        tfm_def_doxy_root = cmake_env["DOXYCFG_DOXYGEN_CFG_DIR"]
        tfm_def_doxygen_in_file = os.path.join(tfm_def_doxy_root,
                                               "Doxyfile.in")

    # Documentation base path
    tfm_def_doc_root = os.path.join(tfm_def_root_dir, "docs")
    tfm_def_copy_doc_root = os.path.join(tfm_def_copy_dir, "docs")

    # Disable copyfiles for next invocation
    cmake_env["SPHINXCFG_COPY_FILES"] = "False"
    with open("tfm_env.py", "w", encoding='utf-8') as F:
        F.write("cmake_env =" + json.dumps(cmake_env))


# Version will be retrieved in that order Git -> Cmake -> Boilerplate
try:
    vrex = re.compile(r'(?P<GIT_HASH>[a-f0-9]{40})'
                      r'+\s+tag\s+refs\/tags\/TF-Mv(?P<VER_MAJ>\d+).'
                      r'(?P<VER_MIN>\d+).?(?P<VER_HOT>\d+)(?P<RC>-RC\d+)?')

    tfm_def_tfm_version = check_output("git for-each-ref refs/tags --sort=-taggerdate --count=1",
                                        shell = True, encoding = 'UTF-8')

    _v = vrex.search(tfm_def_tfm_version)
    version  = [ _v.group("VER_MAJ"),
                 _v.group("VER_MIN"),
                 _v.group("VER_HOT"),
                 _v.group("RC")]
    git_hash  = _v.group("GIT_HASH")

    # Sanitize the verison and remove empty entries
    version = [i.replace("-","") for i in version if i]
    tfm_def_tfm_version = "v"+".".join(version)

    vlrex = re.compile(r'^(?P<GIT_HASH_LATEST>[a-f0-9]{40})')

    git_hash_latest = check_output("git rev-parse HEAD",
                                    shell = True, encoding = 'UTF-8')

    git_hash_latest = vlrex.search(git_hash_latest).group('GIT_HASH_LATEST')

    if git_hash != git_hash_latest:
        git_hash_latest = git_hash_latest[:7]
        tfm_def_tfm_version += "+ ({})".format(git_hash_latest)

except Exception as E:
    try:
        tfm_def_tfm_version
    except NameError:
        tfm_def_tfm_version = "Unknown"

# #################### User Defaults ######################################## #

# Directories, referenced by TF-M root, which may contain releval documents
# which need to be broughtt over
document_scan_dirs = ["tools", "platform"]

document_scan_ext = [".rst", ".md", ".jpg", ".png"]

# Other documents that should be added to the root documentation folder
documents_extra = ["license.rst", "dco.txt"]

# Output files ( After CMAKE variables have been evaluated )
tfm_def_conf_out_file = os.path.join(tfm_def_copy_dir, "conf_rendered.py")
if tfm_def_build_doxygen:
    tfm_def_doxygen_out_file = os.path.join(tfm_def_doxy_root,
                                            "DoxyfileCfg.in")

# If env is none, the script is running as standalone. Generate it with the
# auto-detected values set above
if cmake_env is None:
    cmake_env = {"TFM_ROOT_DIR": tfm_def_root_dir,
                 "DOXYGEN_EXECUTABLE": tfm_def_doxygen_loc,
                 "DOXYGEN_DOT_EXECUTABLE": tfm_def_doxygen_dot_loc,
                 "PLANTUML_JAR_PATH": tfm_def_plantum_loc,
                 "SPHINXCFG_TFM_VERSION": tfm_def_tfm_version,
                 "Java_JAVA_EXECUTABLE": tfm_def_java_binary,
                 "DOXYCFG_OUTPUT_PATH": tfm_def_doxy_output_dir,
                 "DOXYCFG_TFM_VERSION": tfm_def_tfm_version,
                 }
# Only Override the version
else:
    cmake_env["SPHINXCFG_TFM_VERSION"] = tfm_def_tfm_version