EDK2 PyTool Extensions

Common errors

• EDK2_PATH environment variable not set or invalid.

  cause The `EDK2_PATH` (and usually `WORKSPACE`) environment variable is either not defined or points to a directory that doesn't contain a valid EDK2 source tree as expected by the tools.
  fix Set the `EDK2_PATH` and `WORKSPACE` environment variables to the root directory of your EDK2 source code before running any EDK2-PyTool-Extensions commands or scripts. Example: `export EDK2_PATH=/path/to/edk2/source` and `export WORKSPACE=/path/to/edk2/source` (Linux/macOS) or `set EDK2_PATH=C:\path\to\edk2\source` (Windows).

• FileNotFoundError: [Errno 2] No such file or directory: 'nasm'

  cause The EDK2 build process, orchestrated by this library, requires external executables (like `nasm`, `cl.exe`, `gcc`, `iasl`) that are not found in your system's PATH.
  fix Install the necessary EDK2 toolchain components (e.g., NASM assembler, Visual Studio Build Tools for MSVC, or GCC for GCC toolchain) and ensure their installation directory is added to your system's PATH environment variable.

• AttributeError: module 'edk2toolext' has no attribute 'invocables'

  cause This usually means you're trying to directly import a submodule like `edk2toolext.invocables.edk2_setup` programmatically when it's primarily designed for command-line invocation via `python -m`.
  fix For tools like `edk2_setup`, use the `python -m` command-line invocation (e.g., `python -m edk2toolext.invocables.edk2_setup`). For programmatic access, ensure you are importing specific classes like `UefiBuilder` from their correct paths (`from edk2toolext.environment.uefi_build import UefiBuilder`).

Warnings

• gotcha EDK2-PyTool-Extensions relies heavily on specific environment variables (e.g., `WORKSPACE`, `EDK2_PATH`) to locate your EDK2 source tree and associated packages. Incorrect or unset variables are a primary cause of build failures.
  Fix: Ensure `WORKSPACE` and `EDK2_PATH` point to valid EDK2 source roots. Consult EDK2 documentation for correct setup specific to your project.
• gotcha Building EDK2 firmware requires a complete external toolchain (e.g., NASM, MSVC/GCC, IASL, etc.) to be discoverable in your system's PATH. The Python library orchestrates these tools but does not provide them.
  Fix: Install all required EDK2 toolchain components for your target platform and ensure their executables are accessible via the system PATH.
• breaking As a pre-1.0 library (currently 0.x.x), API interfaces and internal behaviors may change between minor versions without explicit deprecation warnings, potentially requiring code adjustments.
  Fix: Review the `CHANGELOG.md` in the GitHub repository when upgrading to a new minor version (e.g., from 0.30.x to 0.31.x) and test your build scripts thoroughly.

Install

• pip install edk2-pytool-extensions Install latest version

Imports

• UefiBuilder

  from edk2toolext.environment.uefi_build import UefiBuilder

• edk2_setup (command-line)
  wrong:

  from edk2toolext.invocables import edk2_setup

  correct:

  python -m edk2toolext.invocables.edk2_setup

  The `edk2_setup` tool is designed for command-line invocation via `python -m`, not direct programmatic import.

Quickstart

This quickstart demonstrates both the command-line usage of the `edk2_setup` tool (by showing its help) and the programmatic instantiation of the core `UefiBuilder` class. It sets up a minimal dummy EDK2 environment to ensure the code is runnable, but a full EDK2 build requires a properly configured external EDK2 source tree and toolchain.

import os
import tempfile
import shutil
from pathlib import Path
import subprocess
import sys

# --- Create a dummy EDK2 environment for demonstration ---
# In a real scenario, EDK2_PATH and WORKSPACE would point to
# your actual EDK2 source code and build workspace.

temp_dir = Path(tempfile.mkdtemp())
edk2_path = temp_dir / "edk2"
workspace_path = temp_dir / "MyWorkspace"

edk2_path.mkdir(exist_ok=True)
workspace_path.mkdir(exist_ok=True)

# Simulate minimal EDK2 structure needed for some checks
(edk2_path / "MdePkg").mkdir(exist_ok=True)
(edk2_path / "MdePkg" / "MdePkg.dsc").write_text("# Dummy DSC file")
(workspace_path / "MyPlatformPkg").mkdir(exist_ok=True)
(workspace_path / "MyPlatformPkg" / "MyPlatform.dsc").write_text("# Dummy Platform DSC file")

os.environ['EDK2_PATH'] = str(edk2_path)
os.environ['WORKSPACE'] = str(workspace_path)

try:
    # --- 1. Demonstrate using the EDK2 setup tool (command-line) ---
    # This tool helps download external dependencies for EDK2 builds.
    print("\n--- Running EDK2 Setup Tool (displaying help) ---")
    setup_result = subprocess.run(
        [sys.executable, "-m", "edk2toolext.invocables.edk2_setup", "--help"],
        capture_output=True, text=True, check=False
    )
    print("EDK2 Setup Tool Help Output (truncated):\n" + setup_result.stdout[:500] + "...")
    if setup_result.returncode != 0:
        print(f"Error running setup tool help: {setup_result.stderr}")

    # --- 2. Demonstrate programmatic use of UefiBuilder ---
    # UefiBuilder is a core class for orchestrating EDK2 builds.
    print("\n--- Demonstrating programmatic import of UefiBuilder ---")
    from edk2toolext.environment.uefi_build import UefiBuilder

    builder_instance = UefiBuilder()
    print(f"Successfully instantiated UefiBuilder: {builder_instance.__class__.__name__}")
    print("Note: A real build would require valid EDK2 source, toolchains, ")
    print("and potentially specific platform configuration files, which are ")
    print("outside the scope of this minimal quickstart example.")

except ImportError as e:
    print(f"Error importing EDK2 PyTool Extensions. Ensure it's installed: {e}")
except Exception as e:
    print(f"An unexpected error occurred during quickstart: {e}")
finally:
    # Clean up dummy environment
    if temp_dir.exists():
        shutil.rmtree(temp_dir)
    print("\n--- Quickstart demonstration complete. --- ")