scripts/build_image.py

# Copyright 2022 The Chromium OS Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

"""build_image is used to build a Chromium OS image.

Chromium OS comes in many different forms. This script can be used to build
the following:

base - Pristine Chromium OS image. As similar to Chrome OS as possible.
dev [default] - Developer image. Like base but with additional dev packages.
test - Like dev, but with additional test specific packages and can be easily
  used for automated testing using scripts like test_that, etc.
factory_install - Install shim for bootstrapping the factory test process.
  Cannot be built along with any other image.

Examples:

build_image --board=<board> dev test - builds developer and test images.
build_image --board=<board> factory_install - builds a factory install shim.

Note if you want to build an image with custom size partitions, either consider
adding a new disk layout in build_library/legacy_disk_layout.json OR use
adjust-part. Here are a few examples:

adjust-part='STATE:+1G' -- add one GB to the size the stateful partition
adjust-part='ROOT-A:-1G' -- remove one GB from the primary rootfs partition
adjust-part='STATE:=1G' --  make the stateful partition 1 GB
"""

import argparse
import os
from pathlib import Path
from typing import List, Optional, Tuple

from chromite.lib import commandline
from chromite.lib import constants
from chromite.lib import cros_build_lib
from chromite.service import image
from chromite.utils import timer


def build_shell_bool_style_args(
    parser: commandline.ArgumentParser,
    name: str,
    default_val: bool,
    help_str: str,
    deprecation_note: str,
    alternate_name: Optional[str] = None,
    additional_neg_options: Optional[List[str]] = None,
) -> None:
    """Build the shell boolean input argument equivalent.

    There are two cases which we will need to handle,
    case 1: A shell boolean arg, which doesn't need to be re-worded in python.
    case 2: A shell boolean arg, which needs to be re-worded in python.
    Example below.
    For Case 1, for a given input arg name 'argA', we create three python
    arguments.
    --argA, --noargA, --no-argA. The arguments --argA and --no-argA will be
    retained after deprecating --noargA.
    For Case 2, for a given input arg name 'arg_A' we need to use alternate
    argument name 'arg-A'. we create four python arguments in this case.
    --arg_A, --noarg_A, --arg-A, --no-arg-A. The first two arguments will be
    deprecated later.
    TODO(b/232566937): Remove the creation of --noargA in case 1 and --arg_A and
    --noarg_A in case 2.

    Args:
      parser: The parser to update.
      name: The input argument name. This will be used as 'dest' variable name.
      default_val: The default value to assign.
      help_str: The help string for the input argument.
      deprecation_note: A deprecation note to use.
      alternate_name: Alternate argument to be used after deprecation.
      additional_neg_options: Additional negative alias options to use.
    """
    arg = f"--{name}"
    shell_narg = f"--no{name}"
    py_narg = f"--no-{name}"
    alt_arg = f"--{alternate_name}" if alternate_name else None
    alt_py_narg = f"--no-{alternate_name}" if alternate_name else None
    default_val_str = f"{help_str} (Default: %(default)s)."

    if alternate_name:
        _alternate_narg_list = [alt_py_narg]
        if additional_neg_options:
            _alternate_narg_list.extend(additional_neg_options)

        parser.add_argument(
            alt_arg,
            action="store_true",
            default=default_val,
            dest=name,
            help=default_val_str,
        )
        parser.add_argument(
            *_alternate_narg_list,
            action="store_false",
            dest=name,
            help="Don't " + help_str.lower(),
        )

    parser.add_argument(
        arg,
        action="store_true",
        default=default_val,
        dest=name,
        deprecated=deprecation_note % alt_arg if alternate_name else None,
        help=default_val_str if not alternate_name else argparse.SUPPRESS,
    )
    parser.add_argument(
        shell_narg,
        action="store_false",
        dest=name,
        deprecated=deprecation_note
        % (alt_py_narg if alternate_name else py_narg),
        help=argparse.SUPPRESS,
    )

    if not alternate_name:
        _py_narg_list = [py_narg]
        if additional_neg_options:
            _py_narg_list.extend(additional_neg_options)

        parser.add_argument(
            *_py_narg_list,
            action="store_false",
            dest=name,
            help="Don't " + help_str.lower(),
        )


def build_shell_string_style_args(
    parser: commandline.ArgumentParser,
    name: str,
    default_val: Optional[str],
    help_str: str,
    deprecation_note: str,
    alternate_name: str,
) -> None:
    """Build the shell string input argument equivalent.

    Args:
      parser: The parser to update.
      name: The input argument name. This will be used as 'dest' variable name.
      default_val: The default value to assign.
      help_str: The help string for the input argument.
      deprecation_note: A deprecation note to use.
      alternate_name: Alternate argument to be used after deprecation.
    """
    default_val_str = (
        f"{help_str} (Default: %(default)s)." if default_val else help_str
    )

    parser.add_argument(
        f"--{alternate_name}",
        dest=f"{name}",
        default=default_val,
        help=default_val_str,
    )
    parser.add_argument(
        f"--{name}",
        deprecated=deprecation_note % f"--{alternate_name}",
        help=argparse.SUPPRESS,
    )


def get_parser() -> commandline.ArgumentParser:
    """Creates the cmdline argparser, populates the options and description.

    Returns:
      Argument parser.
    """
    deprecation_note = "Argument will be removed January, 2023. Use %s instead."
    parser = commandline.ArgumentParser(description=__doc__)

    parser.add_argument(
        "-b",
        "--board",
        "--build-target",
        dest="board",
        default=cros_build_lib.GetDefaultBoard(),
        help="The board to build images for.",
    )
    build_shell_string_style_args(
        parser,
        "adjust_part",
        None,
        "Adjustments to apply to partition table (LABEL:[+-=]SIZE) "
        "e.g. ROOT-A:+1G.",
        deprecation_note,
        "adjust-partition",
    )
    build_shell_string_style_args(
        parser,
        "output_root",
        Path(constants.DEFAULT_BUILD_ROOT) / "images",
        "Directory in which to place image result directories "
        "(named by version).",
        deprecation_note,
        "output-root",
    )
    build_shell_string_style_args(
        parser,
        "builder_path",
        None,
        "The build name to be installed on DUT during hwtest.",
        deprecation_note,
        "builder-path",
    )
    build_shell_string_style_args(
        parser,
        "disk_layout",
        "default",
        "The disk layout type to use for this image.",
        deprecation_note,
        "disk-layout",
    )

    # Kernel related options.
    group = parser.add_argument_group("Kernel Options")
    build_shell_string_style_args(
        group,
        "enable_serial",
        None,
        "Enable serial port for printks. Example values: ttyS0.",
        deprecation_note,
        "enable-serial",
    )
    group.add_argument(
        "--kernel-loglevel",
        type=int,
        default=7,
        help="The loglevel to add to the kernel command line. "
        "(Default: %(default)s).",
    )
    group.add_argument(
        "--loglevel",
        dest="kernel_loglevel",
        type=int,
        deprecated=deprecation_note % "kernel-loglevel",
        help=argparse.SUPPRESS,
    )

    # Bootloader related options.
    group = parser.add_argument_group("Bootloader Options")
    build_shell_string_style_args(
        group,
        "boot_args",
        "noinitrd",
        "Additional boot arguments to pass to the commandline.",
        deprecation_note,
        "boot-args",
    )
    build_shell_bool_style_args(
        group,
        "enable_bootcache",
        False,
        "Make all bootloaders to use boot cache.",
        deprecation_note,
        "enable-bootcache",
    )
    build_shell_bool_style_args(
        group,
        "enable_rootfs_verification",
        True,
        "Make all bootloaders to use kernel based root-fs integrity checking.",
        deprecation_note,
        "enable-rootfs-verification",
        ["-r"],
    )

    # Advanced options.
    group = parser.add_argument_group("Advanced Options")
    group.add_argument(
        "--build-attempt",
        type=int,
        default=1,
        help="The build attempt for this image build. (Default: %(default)s).",
    )
    group.add_argument(
        "--build_attempt",
        type=int,
        deprecated=deprecation_note % "build-attempt",
        help=argparse.SUPPRESS,
    )
    build_shell_string_style_args(
        group,
        "build_root",
        Path(constants.DEFAULT_BUILD_ROOT) / "images",
        "Directory in which to compose the image, before copying it to "
        "output_root.",
        deprecation_note,
        "build-root",
    )
    group.add_argument(
        "-j",
        "--jobs",
        dest="jobs",
        type=int,
        default=os.cpu_count(),
        help="Number of packages to build in parallel at maximum. "
        "(Default: %(default)s).",
    )
    build_shell_bool_style_args(
        group,
        "replace",
        False,
        "Overwrite existing output, if any.",
        deprecation_note,
    )
    group.add_argument(
        "--symlink",
        default="latest",
        help="Symlink name to use for this image. (Default: %(default)s).",
    )
    group.add_argument(
        "--version",
        default=None,
        help="Overrides version number in name to this version.",
    )
    build_shell_string_style_args(
        group,
        "output_suffix",
        None,
        "Add custom suffix to output directory.",
        deprecation_note,
        "output-suffix",
    )
    group.add_argument(
        "--eclean",
        action="store_true",
        default=True,
        dest="eclean",
        deprecated=(
            "eclean is being removed from build_images. Argument will be "
            "removed January, 2023."
        ),
        help=argparse.SUPPRESS,
    )
    group.add_argument(
        "--noeclean",
        action="store_false",
        dest="eclean",
        deprecated=(
            "eclean is being removed from build_images. Argument will be "
            "removed January, 2023."
        ),
        help=argparse.SUPPRESS,
    )
    group.add_argument(
        "--no-eclean",
        action="store_false",
        dest="eclean",
        deprecated=(
            "eclean is being removed from build_images. Argument will be "
            "removed January, 2023."
        ),
        help=argparse.SUPPRESS,
    )

    parser.add_argument(
        "images",
        nargs="*",
        default=["dev"],
        help="list of images to build. (Default: %(default)s).",
    )

    return parser


def parse_args(
    argv: List[str],
) -> Tuple[commandline.ArgumentParser, commandline.ArgumentNamespace]:
    """Parse and validate CLI arguments.

    Args:
      argv: Arguments passed via CLI.

    Returns:
      Tuple having the below two,
      Argument Parser
      Validated argument namespace.
    """
    parser = get_parser()
    opts = parser.parse_args(argv)

    opts.build_run_config = image.BuildConfig(
        adjust_partition=opts.adjust_part,
        output_root=opts.output_root,
        builder_path=opts.builder_path,
        disk_layout=opts.disk_layout,
        enable_serial=opts.enable_serial,
        kernel_loglevel=opts.kernel_loglevel,
        boot_args=opts.boot_args,
        enable_bootcache=opts.enable_bootcache,
        enable_rootfs_verification=opts.enable_rootfs_verification,
        build_attempt=opts.build_attempt,
        build_root=opts.build_root,
        jobs=opts.jobs,
        replace=opts.replace,
        symlink=opts.symlink,
        version=opts.version,
        output_dir_suffix=opts.output_suffix,
    )
    opts.Freeze()

    return parser, opts


@timer.timed("Elapsed time (build_image)")
def main(argv: Optional[List[str]] = None) -> Optional[int]:
    commandline.RunInsideChroot()
    parser, opts = parse_args(argv)

    # If the opts.board is not set, then it means user hasn't specified a default
    # board in 'src/scripts/.default_board' and didn't specify it as input
    # argument.
    if not opts.board:
        parser.error("--board is required")

    invalid_image = [
        x for x in opts.images if x not in constants.IMAGE_TYPE_TO_NAME
    ]
    if invalid_image:
        parser.error(f"Invalid image type argument(s) {invalid_image}")

    result = image.Build(opts.board, opts.images, opts.build_run_config)
    if result.run_error:
        cros_build_lib.Die(
            f"Error running build_image. Exit Code : {result.return_code}"
        )