Edk2 invocable

edk2_invocable

Edk2 Invocable Interface to be overriden in a subclass.

Provides two main classes, the Edk2InvocableSettingsInterface and the Edk2Invocable, which should be used as subclasses to create invocables that perform tasks associated with the EDK2 build system. Any Edk2Invocable subclass should be platform agnostic and work for any platform. Platform specific data is provided via the Edk2InvocableSettingsInterface.

Edk2InvocableSettingsInterface

Settings APIs to support an Edk2Invocable.

This is an interface definition only to show which functions are required to be implemented and can be implemented in a settings manager.

Example of Overriding Edk2InvocableSettingsInterface

import os
import logging
import argparse
from typing import Iterable, Tuple
from edk2toolext.edk2_invocable import Edk2InvocableSettingsInterface

class NewInvocableSettingsManager(Edk2InvocableSettingsInterface):
    def GetWorkspaceRoot(self) -> str:
        return os.path.abspath(__file__)
    def GetPackagesPath(self) -> Iterable[os.PathLike]
        return ["C:/src/MU_BASECORE", "Common/MU"]
    def GetActiveScopes(self) -> Tuple[str]:
        return ("edk2-build", "pipbuild-win")
    def GetLoggingLevel(self, loggerType: str) -> str:
        if loggerType == 'txt':
            return logging.WARNING
        else:
            return logging.INFO
    def AddCommandLineOptions(self, parserObj: object) -> None:
        parserObj.add_argument('-a', "--arch", dest="build_arch", type=str, default="IA32,X64")
    def RetrieveCommandLineOptions(self, args: object) -> None:
        self.arch = args.build_arch
    def GetSkippedDirectories(self) -> Tuple[str]:
        return ("Downloads/Extra")

Warning

This interface should not be subclassed directly unless you are creating a new invocable Other invocables subclass from this interface, so you have the ability to call the functions in this class as a part of those invocable settings managers.

GetWorkspaceRoot

GetWorkspaceRoot() -> str

Return the workspace root for initializing the SDE, will be mapped as edk2 WORKSPACE.

Tip

Required Override in a subclass

The absolute path to the root of the workspace

Returns:

Type	Description
str	path to workspace root

GetPackagesPath

GetPackagesPath() -> Iterable[os.PathLike]

Provides an iterable of paths which will be mapped as edk2 PACKAGES_PATH.

Tip

Optional Override in a subclass

Path can be, 1. Absolute or 2. Relative to WORKSPACE or 3. Relative to current working dir

See Also, https://github.com/tianocore/tianocore.github.io/wiki/Multiple_Workspace

Returns:

Type	Description
Iterable[PathLike]	paths

GetActiveScopes

GetActiveScopes() -> tuple[str]

Provides scopes that should be active for this process for SDE.

Tip

Optional Override in a subclass

Returns:

Type	Description
Tuple[str]	scopes

GetLoggingLevel

GetLoggingLevel(loggerType: str) -> int

Get the logging level depending on logger type.

Tip

Optional Override in a subclass

Returns:

Type	Description
Level	The logging level

loggerType possible values

"base": lowest logging level supported

"con": logs to screen

"txt": logs to plain text file

AddCommandLineOptions

AddCommandLineOptions(
    parserObj: argparse.ArgumentParser,
) -> None

Add command line options to the argparser.

Tip

Optional override in a subclass

Parameters:

Name	Type	Description	Default
parserObj	ArgumentParser	Argparser object.	required

RetrieveCommandLineOptions

RetrieveCommandLineOptions(
    args: argparse.Namespace,
) -> None

Retrieve Command line options from the argparser.

Tip

Optional override in a subclass

Parameters:

Name	Type	Description	Default
args	Namespace	argparser args namespace containing command line options	required

GetSkippedDirectories

GetSkippedDirectories() -> tuple[str]

Returns a tuple containing workspace-relative directories to be skipped by SDE.

Tip

Optional override in a subclass

Returns:

Type	Description
Tuple[str]	directories to be skipped.

Edk2Invocable

Base class for Edk2 based invocables.

Edk2 means it has common features like workspace, packagespath, scopes, and other name value pairs

Attributes:

Name	Type	Description
PlatformSettings	Edk2InvocableSettingsInterface	A settings class
PlatformModule	object	The platform module
Verbose	bool	CLI Argument to determine whether or not to have verbose

Tip

Checkout BaseAbstractInvocable Attributes to find any additional attributes that might exist.

Warning

This Invocable should only be subclassed if creating a new invocable

collect_python_pip_info classmethod

collect_python_pip_info() -> None

Class method to collect all pip packages names and versions.

Reports them to the global version_aggregator as well as print them to the screen.

collect_rust_info classmethod

collect_rust_info() -> None

Class method to collect Rust tool versions.

Reports them to the global version_aggregator as well as print them to the screen.

GetWorkspaceRoot

GetWorkspaceRoot() -> os.PathLike

Returns the absolute path to the workspace root.

Note

Workspace Root is platform specific and thus provided by the PlatformSettings

Returns:

Type	Description
PathLike	absolute path to workspace root

GetPackagesPath

GetPackagesPath() -> Iterable[os.PathLike]

Returns an iterable of packages path.

Note

PackagesPath is platform specific and thus provided by the PlatformSettings

Returns:

Type	Description
Iterable[PathLike]	Packages path

GetActiveScopes

GetActiveScopes() -> tuple[str]

Returns an iterable of Active scopes.

Note

Scopes are platform specific and thus provided by the PlatformSettings

This function adds an os specific scope in addition to scopes provided by SettingsManager

Returns:

Type	Description
tuple[str]	active scopes

GetLoggingLevel

GetLoggingLevel(loggerType: str) -> int

Get the logging level for a given logger type.

Note

Logging Level is platform specific and thus provided by the PlatformSettings

Returns:

Type	Description
Level	logging level

AddCommandLineOptions

AddCommandLineOptions(
    parserObj: argparse.ArgumentParser,
) -> None

Add command line options to the argparser.

Note

Optional Override to add functionality

RetrieveCommandLineOptions

RetrieveCommandLineOptions(
    args: argparse.Namespace,
) -> None

Retrieve command line options from the argparser.

Note

Optional Override to add functionality

GetSkippedDirectories

GetSkippedDirectories() -> tuple[str]

Returns a Tuple containing workspace-relative directories that should be skipped.

Tip

Override in a subclass to add invocable specific directories to skip

Note

Skipped Directories are platform specific and thus provided by the PlatformSettings

Returns:

Type	Description
Tuple[str]	skipped directories as relative paths

GetSettingsClass

GetSettingsClass() -> type

The required settings manager for the invocable.

Note

Required override to define Edk2InvocableSettingsInterface subclass specific to the invocable

Returns:

Type	Description
Edk2InvocableSettingsInterface	Subclass of Edk2InvocableSettingsInterface

GetLoggingFolderRelativeToRoot

GetLoggingFolderRelativeToRoot() -> str

Directory containing all logging files.

AddParserEpilog

AddParserEpilog() -> str

Adds an epilog to the end of the argument parser when displaying help information.

Returns:

Type	Description
str	The string to be added to the end of the argument parser.

ParseCommandLineOptions

ParseCommandLineOptions() -> None

Parses command line options.

Sets up argparser specifically to get PlatformSettingsManager instance. Then sets up second argparser and passes it to child class and to PlatformSettingsManager. Finally, parses all known args and then reads the unknown args in to build vars.