{"id":7199,"library":"edk2-pytool-extensions","title":"EDK2 PyTool Extensions","description":"EDK2 PyTool Extensions is a collection of Python-based tools designed to support the development of UEFI EDK2 firmware. It orchestrates common build tasks, manages external dependencies, and provides a programmatic interface for EDK2 builds. The current version is 0.31.0, with an active development cadence featuring frequent updates and bug fixes.","status":"active","version":"0.31.0","language":"en","source_language":"en","source_url":"https://github.com/microsoft/edk2-pytool-extensions","tags":["UEFI","EDK2","firmware","build-tools","toolchain"],"install":[{"cmd":"pip install edk2-pytool-extensions","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"UefiBuilder","correct":"from edk2toolext.environment.uefi_build import UefiBuilder"},{"note":"The `edk2_setup` tool is designed for command-line invocation via `python -m`, not direct programmatic import.","wrong":"from edk2toolext.invocables import edk2_setup","symbol":"edk2_setup (command-line)","correct":"python -m edk2toolext.invocables.edk2_setup"}],"quickstart":{"code":"import os\nimport tempfile\nimport shutil\nfrom pathlib import Path\nimport subprocess\nimport sys\n\n# --- Create a dummy EDK2 environment for demonstration ---\n# In a real scenario, EDK2_PATH and WORKSPACE would point to\n# your actual EDK2 source code and build workspace.\n\ntemp_dir = Path(tempfile.mkdtemp())\nedk2_path = temp_dir / \"edk2\"\nworkspace_path = temp_dir / \"MyWorkspace\"\n\nedk2_path.mkdir(exist_ok=True)\nworkspace_path.mkdir(exist_ok=True)\n\n# Simulate minimal EDK2 structure needed for some checks\n(edk2_path / \"MdePkg\").mkdir(exist_ok=True)\n(edk2_path / \"MdePkg\" / \"MdePkg.dsc\").write_text(\"# Dummy DSC file\")\n(workspace_path / \"MyPlatformPkg\").mkdir(exist_ok=True)\n(workspace_path / \"MyPlatformPkg\" / \"MyPlatform.dsc\").write_text(\"# Dummy Platform DSC file\")\n\nos.environ['EDK2_PATH'] = str(edk2_path)\nos.environ['WORKSPACE'] = str(workspace_path)\n\ntry:\n    # --- 1. Demonstrate using the EDK2 setup tool (command-line) ---\n    # This tool helps download external dependencies for EDK2 builds.\n    print(\"\\n--- Running EDK2 Setup Tool (displaying help) ---\")\n    setup_result = subprocess.run(\n        [sys.executable, \"-m\", \"edk2toolext.invocables.edk2_setup\", \"--help\"],\n        capture_output=True, text=True, check=False\n    )\n    print(\"EDK2 Setup Tool Help Output (truncated):\\n\" + setup_result.stdout[:500] + \"...\")\n    if setup_result.returncode != 0:\n        print(f\"Error running setup tool help: {setup_result.stderr}\")\n\n    # --- 2. Demonstrate programmatic use of UefiBuilder ---\n    # UefiBuilder is a core class for orchestrating EDK2 builds.\n    print(\"\\n--- Demonstrating programmatic import of UefiBuilder ---\")\n    from edk2toolext.environment.uefi_build import UefiBuilder\n\n    builder_instance = UefiBuilder()\n    print(f\"Successfully instantiated UefiBuilder: {builder_instance.__class__.__name__}\")\n    print(\"Note: A real build would require valid EDK2 source, toolchains, \")\n    print(\"and potentially specific platform configuration files, which are \")\n    print(\"outside the scope of this minimal quickstart example.\")\n\nexcept ImportError as e:\n    print(f\"Error importing EDK2 PyTool Extensions. Ensure it's installed: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during quickstart: {e}\")\nfinally:\n    # Clean up dummy environment\n    if temp_dir.exists():\n        shutil.rmtree(temp_dir)\n    print(\"\\n--- Quickstart demonstration complete. --- \")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `WORKSPACE` and `EDK2_PATH` point to valid EDK2 source roots. Consult EDK2 documentation for correct setup specific to your project.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install all required EDK2 toolchain components for your target platform and ensure their executables are accessible via the system PATH.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"< 1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","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.","error":"EDK2_PATH environment variable not set or invalid."},{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'nasm'"},{"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`).","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`.","error":"AttributeError: module 'edk2toolext' has no attribute 'invocables'"}]}