Added a way to get more information a port (#21376)

Author: ypujante

docs/emcc.txt

@@ -475,8 +475,9 @@ Options that are modified or new in *emcc* are listed below:
    port=sdl2 --use-port=bzip2"). A port can have options separated by
    ":" (ex: "--use-port=sdl2_image:formats=png,jpg"). To use an
    external port, you provide the path to the port directly (ex: "--
-   use-port=/path/to/my_port.py"). To get the list of available ports,
-   use "--show-ports".
+   use-port=/path/to/my_port.py"). To get more information about a
+   port, use the "help" option (ex: "--use-port=sdl2_image:help"). To
+   get the list of available ports, use "--show-ports".
 
 "--clear-ports"
    [general] Manually clears the local copies of ports from the

site/source/docs/tools_reference/emcc.rst

@@ -466,8 +466,9 @@ Options that are modified or new in *emcc* are listed below:
   can have options separated by ``:``
   (ex: ``--use-port=sdl2_image:formats=png,jpg``). To use an  external port,
   you provide the path to the port directly
-  (ex: ``--use-port=/path/to/my_port.py``). To get the list of available ports,
-  use ``--show-ports``.
+  (ex: ``--use-port=/path/to/my_port.py``). To get more information about a
+  port, use the ``help`` option (ex: ``--use-port=sdl2_image:help``).
+  To get the list of available ports, use ``--show-ports``.
 
 .. _emcc-clear-ports:
 

test/other/ports/external.py

@@ -6,6 +6,10 @@
 import os
 from typing import Dict, Optional
 
+URL = 'https://emscripten.org'
+DESCRIPTION = 'Test Description'
+LICENSE = 'Test License'
+
 OPTIONS = {
   'value1': 'Value for define TEST_VALUE_1',
   'value2': 'Value for define TEST_VALUE_2',

test/test_other.py

@@ -2435,6 +2435,16 @@ def test_external_ports(self):
     stderr = self.expect_fail([EMCC, test_file('other/test_external_ports.c'), f'--use-port={external_port_path}:dependency=invalid', '-o', 'a4.out.js'])
     self.assertFalse(os.path.exists('a4.out.js'))
     self.assertContained('unknown dependency `invalid` for port `external`', stderr)
+    # testing help
+    stdout = self.run_process([EMCC, test_file('other/test_external_ports.c'), f'--use-port={external_port_path}:help'], stdout=PIPE).stdout
+    self.assertContained('''external (--use-port=external; Test License)
+Test Description
+Options:
+* value1: Value for define TEST_VALUE_1
+* value2: Value for define TEST_VALUE_2
+* dependency: A dependency
+More info: https://emscripten.org
+''', stdout)
 
   def test_link_memcpy(self):
     # memcpy can show up *after* optimizations, so after our opportunity to link in libc, so it must be special-cased

tools/ports/__init__.py

@@ -9,6 +9,7 @@
 import shutil
 import glob
 import importlib.util
+import sys
 from typing import Set
 from tools import cache
 from tools import config
@@ -405,6 +406,21 @@ def handle_use_port_error(arg, message):
   utils.exit_with_error(f'error with `--use-port={arg}` | {message}')
 
 
+def show_port_help_and_exit(port):
+  print(port.show())
+  if hasattr(port, 'DESCRIPTION'):
+    print(port.DESCRIPTION)
+  if hasattr(port, 'OPTIONS'):
+    print("Options:")
+    for option, desc in port.OPTIONS.items():
+      print(f'* {option}: {desc}')
+  else:
+    print("No options.")
+  if hasattr(port, 'URL'):
+    print(f'More info: {port.URL}')
+  sys.exit(0)
+
+
 def handle_use_port_arg(settings, arg, error_handler=None):
   if not error_handler:
     def error_handler(message):
@@ -425,6 +441,8 @@ def error_handler(message):
   ports_needed.add(name)
   if options:
     port = ports_by_name[name]
+    if options == 'help':
+      show_port_help_and_exit(port)
     if not hasattr(port, 'handle_options'):
       error_handler(f'no options available for port `{name}`')
     else: