build/sandbox/config.py

# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Parses config file and provides various ways of using it."""

import xml.etree.ElementTree as ET

# The config file must be in XML with a structure as descibed below.
#
# The top level config element shall contain one or more "target" child
# elements. Each of these may contain one or more build_config child elements.
# The build_config child elements will inherit the properties of the target
# parent.
#
# Each "target" and "build_config" may contain the following:
#
# Attributes:
#
#   name: The name of the target.
#
#   android_target: The name of the android target used with lunch
#
#   allow_readwrite_all: "true" if the full source folder shall be mounted as
#   read/write. It should be accompanied by a comment with the bug describing
#   why it was required.
#
#   tags: A comma-separated list of strings to be associated with the target
#     and any of its nested build_targets. You can use a tag to associate
#     information with a target in your configuration file, and retrieve that
#     information using the get_tags API or the has_tag API.
#
# Child elements:
#
#   fast_merge_config: The configuration options for fast merge.
#
#     Attributes:
#
#       framework_images: Comma-separated list of image names that
#         should come from the framework build.
#
#       misc_info_keys: A path to the newline-separated config file containing
#       keys to obtain from the framework instance of misc_info.txt, used for
#       creating vbmeta.img.
#
#   overlay: An overlay to be mounted while building the target.
#
#     Attributes:
#
#       name: The name of the overlay.
#
#   view: A map (optionally) specifying a filesystem view mapping for each
#     target.
#
#     Attributes:
#
#       name: The name of the view.
#
#   allow_readwrite: A folder to mount read/write
#   inside the Android build nsjail. Each allowed read-write entry should be
#   accompanied by a bug that indicates why it was required and tracks the
#   progress to a fix.
#
#     Attributes:
#
#       path: The path to be allowed read-write mounting.
#
#   build_config: A list of goals to be used while building the target.
#
#     Attributes:
#
#       name: The name of the build config. Defaults to the target name
#         if not set.
#
#     Child elements:
#
#       goal: A build goal.
#
#         Properties:
#
#           name: The name of the build goal. The build tools pass the name
#             attribute as a parameter to make. This can have a value like
#             "droid" or "VAR=value".
#
#           contexts: A comma-separated list of the contexts in which this
#             goal applies. If this attribute is missing or blank, the goal
#             applies to all contexts. Otherwise, it applies only in the
#             requested contexts (see get_build_goals).


class BuildConfig(object):
  """Represents configuration of a build_target.

  Attributes:
    name: name of the build_target used to pull the configuration.
    android_target: The name of the android target used with lunch.
    build_goals: List of goals to be used while building the target.
    overlays: List of overlays to be mounted.
    views: A list of (source, destination) string path tuple to be mounted.
      See view nodes in XML.
    allow_readwrite_all: If true, mount source tree as rw.
    allow_readwrite: List of directories to be mounted as rw.
    allowed_projects_file: a string path name of a file with a containing
      allowed projects.
    fmc_framework_images: For a fast merge config (FMC), the comma-separated
      list of image names that should come from the framework build.
    fmc_misc_info_keys: For a fast merge config (FMC), A path to the
      newline-separated config file containing keys to obtain from the
      framework instance of misc_info.txt, used for creating vbmeta.img.
  """

  def __init__(self,
               name,
               android_target,
               tags=frozenset(),
               build_goals=(),
               overlays=(),
               views=(),
               allow_readwrite_all=False,
               allow_readwrite=(),
               allowed_projects_file=None,
               fmc_framework_images=None,
               fmc_misc_info_keys=None):
    super().__init__()
    self.name = name
    self.android_target = android_target
    self.tags = tags
    self.build_goals = list(build_goals)
    self.overlays = list(overlays)
    self.views = list(views)
    self.allow_readwrite_all = allow_readwrite_all
    self.allow_readwrite = list(allow_readwrite)
    self.allowed_projects_file = allowed_projects_file
    self.fmc_framework_images = fmc_framework_images
    self.fmc_misc_info_keys = fmc_misc_info_keys

  def validate(self):
    """Run tests to validate build configuration"""
    # A valid build_config is required to have at least one goal.
    if not self.build_goals:
      raise ValueError(
          'Error: build_config {} must have at least one goal'.format(self.name))
    if not self.name:
      raise ValueError('Error build_config must have a name.')


  @classmethod
  def from_config(cls, config_elem, fs_view_map, base_config=None):
    """Creates a BuildConfig from a config XML element and an optional
      base_config.

    Args:
      config_elem: the config XML node element to build the configuration
      fs_view_map: A map of view names to list of tuple(source, destination)
        paths.
      base_config: the base BuildConfig to use

    Returns:
      A build config generated from the config element and the base
      configuration if provided.
    """
    if base_config is None:
      # Build a base_config with required elements from the new config_elem
      name = config_elem.get('name')
      base_config = cls(
          name=name, android_target=config_elem.get('android_target', name))

    return cls(
        android_target=config_elem.get('android_target',
                                       base_config.android_target),
        name=config_elem.get('name', base_config.name),
        allowed_projects_file=config_elem.get(
            'allowed_projects_file', base_config.allowed_projects_file),
        build_goals=_get_build_config_goals(config_elem,
                                            base_config.build_goals),
        tags=_get_config_tags(config_elem, base_config.tags),
        overlays=_get_overlays(config_elem, base_config.overlays),
        allow_readwrite=_get_allow_readwrite(config_elem,
                                             base_config.allow_readwrite),
        views=_get_views(config_elem, fs_view_map, base_config.views),
        allow_readwrite_all=_get_allowed_readwrite_all(
            config_elem, base_config.allow_readwrite_all),
        fmc_framework_images=_get_fast_config_framework_images(
            config_elem, base_config.fmc_framework_images),
        fmc_misc_info_keys=_get_fast_config_misc_info_keys(
            config_elem, base_config.fmc_misc_info_keys))


def _get_build_config_goals(config_elem, base=None):
  """Retrieves goals from build_config or target.

  Args:
    config_elem: A build_config or target xml element.
    base: Initial list of goals to prepend to the list

  Returns:
    A list of tuples where the first element of the tuple is the build goal
    name, and the second is a list of the contexts to which this goal applies.
  """

  return base + [(goal.get('name'), set(goal.get('contexts').split(','))
                  if goal.get('contexts') else None)
                 for goal in config_elem.findall('goal')]


def _get_config_tags(config_elem, base=frozenset()):
  """Retrieves tags from build_config or target.

  Args:
    config_elem: A build_config or target xml element.
    base: Initial list of tags to seed the set

  Returns:
    A set of tags for a build_config.
  """
  tags = config_elem.get('tags')
  return base.union(set(tags.split(',')) if tags else set())


def _get_allowed_readwrite_all(config_elem, default=False):
  """Determines if build_config or target is set to allow readwrite for all
    source paths.

  Args:
    config_elem: A build_config or target xml element.
    default: Value to use if element doesn't contain the
      allow_readwrite_all attribute.

  Returns:
    True if build config is set to allow readwrite for all sorce paths
  """
  value = config_elem.get('allow_readwrite_all')
  return value == 'true' if value else default


def _get_overlays(config_elem, base=None):
  """Retrieves list of overlays from build_config or target.

  Args:
    config_elem: A build_config or target xml element.
    base: Initial list of overlays to prepend to the list

  Returns:
    A list of overlays to mount for a build_config or target.
  """
  return base + [o.get('name') for o in config_elem.findall('overlay')]


def _get_views(config_elem, fs_view_map, base=None):
  """Retrieves list of views from build_config or target.

  Args:
    config_elem: A build_config or target xml element.
    base: Initial list of views to prepend to the list

  Returns:
    A list of (source, destination) string path tuple to be mounted. See view
      nodes in XML.
  """
  return base + [fs for o in config_elem.findall('view')
                 for fs in fs_view_map[o.get('name')]]


def _get_allow_readwrite(config_elem, base=None):
  """Retrieves list of directories to be mounted rw from build_config or
    target.

  Args:
    config_elem: A build_config or target xml element.
    base: Initial list of rw directories to prepend to the list

  Returns:
    A list of directories to be mounted rw.
  """
  return (base +
          [o.get('path') for o in config_elem.findall('allow_readwrite')])


def _get_fast_config_framework_images(config_elem, default=None):
  """Retrieves a comma separated string containing framework images to be used
    for merging in fast mode

  Args:
    config_elem: A build_config or target xml element.
    default: Value to use if element doesn't contain the
      fast_merge_config element or framework_images attribute.

  Returns:
    A string of comma separated image names
  """
  fast_merge_config = config_elem.find('fast_merge_config')
  if fast_merge_config is None:
    return default
  images = fast_merge_config.get('framework_images')
  return images if images else default

def _get_fast_config_misc_info_keys(config_elem, default=None):
  """Retrieves the misc_info_keys path setting

  Args:
    config_elem: A build_config or target xml element.
    default: Value to use if element doesn't contain the
      fast_merge_config element or misc_info_keys attribute.

  Returns:
    A path to the misc_info_keys file
  """
  fast_merge_config = config_elem.find('fast_merge_config')
  if fast_merge_config is None:
    return default
  misc_info_keys = fast_merge_config.get('misc_info_keys')
  return misc_info_keys if misc_info_keys else default


def _get_fs_view_map(config):
  """Retrieves the map of filesystem views.

  Args:
    config: An XML Element that is the root of the config XML tree.

  Returns:
    A dict of filesystem views keyed by view name. A filesystem view is a
    list of (source, destination) string path tuples.
  """
  # A valid config file is not required to include FS Views, only overlay
  # targets.
  return {
      view.get('name'): [(path.get('source'), path.get('destination'))
                         for path in view.findall('path')
                        ] for view in config.findall('view')
  }


def _get_build_config_map(config):
  """Retrieves a map of all build config.

  Args:
    config: An XML Element that is the root of the config XML tree.

  Returns:
    A dict of BuildConfig keyed by build_target.
  """
  fs_view_map = _get_fs_view_map(config)
  build_config_map = {}
  for target_config in config.findall('target'):
    base_target = BuildConfig.from_config(target_config, fs_view_map)

    for build_config in target_config.findall('build_config'):
      build_target = BuildConfig.from_config(build_config, fs_view_map,
                                             base_target)
      build_target.validate()
      build_config_map[build_target.name] = build_target

  return build_config_map


class Config:
  """Presents an API to the static XML configuration."""

  def __init__(self, config_filename):
    """Initializes a Config instance from the specificed filename

    This method parses the XML content of the file named by config_filename
    into internal data structures. You can then use various methods to query
    the static config.

    Args:
      config_filename: The name of the file from which to load the config.
    """

    tree = ET.parse(config_filename)
    config = tree.getroot()
    self._build_config_map = _get_build_config_map(config)

  def get_available_build_targets(self):
    """Return a list of available build targets."""
    return sorted(self._build_config_map.keys())

  def get_tags(self, build_target):
    """Given a build_target, return the (possibly empty) set of tags."""
    return self._build_config_map[build_target].tags

  def has_tag(self, build_target, tag):
    """Return true if build_target has tag.

    Args:
      build_target: A string build_target to be queried.
      tag: A string tag that this target may have.

    Returns:
      If the build_target has the tag, True. Otherwise, False.
    """
    return tag in self._build_config_map[build_target].tags

  def get_allowed_projects_file(self, build_target):
    """Given a build_target, return a string with the allowed projects file."""
    return self._build_config_map[build_target].allowed_projects_file

  def get_build_config_android_target(self, build_target):
    """Given a build_target, return an android_target.

    Generally a build_target maps directory to the android_target of the same
    name, but they can differ. In a config.xml file, the name attribute of a
    target element is the android_target (which is used for lunch). The name
    attribute (if any) of a build_config element is the build_target. If a
    build_config element does not have a name attribute, then the build_target
    is the android_target.

    Args:
      build_target: A string build_target to be queried.

    Returns:
      A string android_target that can be used for lunch.
    """
    return self._build_config_map[build_target].android_target

  def get_build_goals(self, build_target, contexts=frozenset()):
    """Given a build_target and a context, return a list of build goals.

    For a given build_target, we may build in a variety of contexts. For
    example we might build in continuous integration, or we might build
    locally, or other contexts defined by the configuration file and scripts
    that use it. The contexts parameter is a set of strings that specify the
    contexts for which this function should retrieve goals.

    In the configuration file, each goal has a contexts attribute, which
    specifies the contexts to which the goal applies. We treat a goal with no
    contexts attribute as applying to all contexts.

    Example:

      <build_config>
        <goal name="droid"/>
        <goal name="dist" contexts="ota"/>
      </build_config>

      Here we have the goal "droid", which matches all contexts, and the goal
      "dist", which matches the "ota" context. Invoking this method with the
      set(['ota']) would return ['droid', 'dist'].

    Args:
      build_target: A string build_target to be queried.
      context: A set of contexts for which to retrieve goals.

    Returns:
      A list of strings, where each string is a goal to be passed to make.
    """

    build_goals = []
    for goal, build_contexts in self._build_config_map[
        build_target].build_goals:
      if not build_contexts:
        build_goals.append(goal)
      elif build_contexts.intersection(contexts):
        build_goals.append(goal)

    return build_goals

  def get_rw_allowlist_map(self):
    """Return read-write allowlist map.

    Returns:
      A dict of string lists of keyed by target name. Each value in the dict is
      a list of allowed read-write paths corresponding to the target.
    """
    return {b.name: b.allow_readwrite for b in self._build_config_map.values()}

  def get_allow_readwrite_all(self, build_target):
    """Return True if the target should mount all its source as read-write.

    Args:
      build_target: A string build_target to be queried.

    Returns:
      True if the target should mount all its source as read-write.
    """
    return self._build_config_map[build_target].allow_readwrite_all

  def get_overlay_map(self):
    """Return the overlay map.

    Returns:
      A dict of keyed by target name. Each value in the dict is a list of
      overlay names corresponding to the target.
    """
    return {b.name : b.overlays for b in self._build_config_map.values()}


  def get_fs_view_map(self):
    """Return the filesystem view map.
    Returns:
      A dict of filesystem views keyed by target name. A filesystem view is a
      list of (source, destination) string path tuples.
    """
    return {b.name : b.views for b in self._build_config_map.values()}


  def get_build_config(self, build_target):
    return self._build_config_map[build_target]


def factory(config_filename):
  """Create an instance of a Config class.

  Args:
    config_filename: The name of the file from which to load the config. This
      can be None, which results in this function returning None.

  Returns:
    If config_filename is None, returns None. Otherwise, a new instance of a
    Config class containing the configuration parsed from config_filename.
  """
  if config_filename is None:
    return None

  return Config(config_filename)