invocables: Update --help information (#754)

1. If a configuration file is provided, will provide all available
   options for architecture (-a), package (-p) and target (-t).

2. Ensures that the CLI env guidance is provided to the user even If
   no configuration file is provided (bugfix).

3. Updates some general help text to be more clear.

.cspell.json

@@ -49,6 +49,7 @@
  "docstring",
  "docstrings",
  "dscs",
+ "edkii",
  "esrt",
  "etree",
  "executables",

edk2toolext/edk2_invocable.py

@@ -185,6 +185,10 @@ class Edk2Invocable(BaseAbstractInvocable):
  !!! warning
  This Invocable should only be subclassed if creating a new invocable
  """
+ def __init__(self) -> None:
+ """Init the Invocable."""
+ super().__init__()
+ self.PlatformSettings = None
 
  @classmethod
  def collect_python_pip_info(cls: 'Edk2Invocable') -> None:
@@ -389,7 +393,11 @@ def ParseCommandLineOptions(self) -> None:
  Finally, parses all known args and then reads the unknown args in to build vars.
  """
  # first argparser will only get settings manager and help will be disabled
- settingsParserObj = argparse.ArgumentParser(add_help=False)
+ settingsParserObj = argparse.ArgumentParser(
+ add_help=False,
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=self.AddParserEpilog(),
+ )
 
  settingsParserObj.add_argument('-h', '--help', dest="help", action="store_true",
  help='show this help message and exit')
@@ -431,8 +439,8 @@ def ParseCommandLineOptions(self) -> None:
  except (FileNotFoundError):
  if settingsArg.help:
  try:
- print("WARNING: Some command line arguments may be missing. Provide a PLATFORM_MODULE file to "
- "ensure all command line arguments are present.\n")
+ print("WARNING: Some command line arguments and possible values for arguments may be missing. "
+ "Provide a PLATFORM_MODULE file to ensure all command line arguments are present.\n")
  self.AddCommandLineOptions(settingsParserObj)
  except Exception:
  pass

edk2toolext/invocables/edk2_multipkg_aware_invocable.py

@@ -178,14 +178,24 @@ def __init__(self) -> None:
  def AddCommandLineOptions(self, parserObj: argparse.ArgumentParser) -> None:
  """Adds command line options to the argparser."""
  # This will parse the packages that we are going to update
+ pkg_options = ""
+ arch_options = ""
+ target_options = ""
+ if self.PlatformSettings:
+ pkg_options = f' \n[{",".join(self.PlatformSettings.GetPackagesSupported())}]'
+ arch_options = f' \n[{",".join(self.PlatformSettings.GetArchitecturesSupported())}]'
+ target_options = f' \n[{",".join(self.PlatformSettings.GetTargetsSupported())}]'
+
  parserObj.add_argument('-p', '--pkg', '--pkg-dir', dest='packageList', type=str,
- help='Optional - A package or folder you want to update (workspace relative).'
- 'Can list multiple by doing -p <pkg1>,<pkg2> or -p <pkg3> -p <pkg4>',
+ help='CSV of EDKII packages / folder containing packages to operate on. '
+ f'{pkg_options}',
  action="append", default=[])
  parserObj.add_argument('-a', '--arch', dest="requested_arch", type=str, default=None,
- help="Optional - CSV of architecture requested to update. Example: -a X64,AARCH64")
+ help='CSV of architectures to operate on.'
+ f'{arch_options}')
  parserObj.add_argument('-t', '--target', dest='requested_target', type=str, default=None,
- help="Optional - CSV of targets requested to update. Example: -t DEBUG,NOOPT")
+ help='CSV of targets to operate on.'
+ f'{target_options}')
 
  def RetrieveCommandLineOptions(self, args: argparse.Namespace) -> None:
  """Retrieve command line options from the argparser ."""

edk2toolext/invocables/edk2_platform_build.py

@@ -59,6 +59,11 @@ def GetName(self) -> str:
 class Edk2PlatformBuild(Edk2Invocable):
  """Invocable that performs some environment setup,Imports UefiBuilder and calls go."""
 
+ def __init__(self) -> None:
+ """Init the Invocable."""
+ super().__init__()
+ self.PlatformBuilder = None
+
  def AddCommandLineOptions(self, parserObj: argparse.ArgumentParser) -> None:
  """Adds command line options to the argparser."""
  # PlatformSettings could also be a subclass of UefiBuilder, who knows!
@@ -86,22 +91,23 @@ def AddParserEpilog(self) -> str:
  epilog = super().AddParserEpilog()
  custom_epilog = ""
 
- variables = self.PlatformBuilder.SetPlatformDefaultEnv()
- if any(variables):
- max_name_len = max(len(var.name) for var in variables)
- max_desc_len = min(max(len(var.description) for var in variables), 55)
-
- custom_epilog += "CLI Env Variables:"
- for v in variables:
- # Setup wrap and print first portion of description
- desc = wrap(v.description, max_desc_len,
- drop_whitespace=True, break_on_hyphens=True, break_long_words=True)
- custom_epilog += f"\n {v.name:<{max_name_len}} - {desc[0]:<{max_desc_len}} [{v.default}]"
-
- # If the line actually wrapped, we can print the rest of the lines here
- for d in desc[1:]:
- custom_epilog += f"\n {'':<{max_name_len}} {d:{max_desc_len}}"
- custom_epilog += '\n\n'
+ if self.PlatformBuilder:
+ variables = self.PlatformBuilder.SetPlatformDefaultEnv()
+ if any(variables):
+ max_name_len = max(len(var.name) for var in variables)
+ max_desc_len = min(max(len(var.description) for var in variables), 55)
+
+ custom_epilog += "CLI Env Variables:"
+ for v in variables:
+ # Setup wrap and print first portion of description
+ desc = wrap(v.description, max_desc_len,
+ drop_whitespace=True, break_on_hyphens=True, break_long_words=True)
+ custom_epilog += f"\n {v.name:<{max_name_len}} - {desc[0]:<{max_desc_len}} [{v.default}]"
+
+ # If the line actually wrapped, we can print the rest of the lines here
+ for d in desc[1:]:
+ custom_epilog += f"\n {'':<{max_name_len}} {d:{max_desc_len}}"
+ custom_epilog += '\n\n'
 
  return custom_epilog + epilog