diff --git a/docs/emcc.txt b/docs/emcc.txt index 55afc30fa550a..ea768325837c2 100644 --- a/docs/emcc.txt +++ b/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 diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst index 8dc995529543e..f39c6ddfaeb84 100644 --- a/site/source/docs/tools_reference/emcc.rst +++ b/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: diff --git a/test/other/ports/external.py b/test/other/ports/external.py index 3df5adb6c190d..b6854509625d4 100644 --- a/test/other/ports/external.py +++ b/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', diff --git a/test/test_other.py b/test/test_other.py index fc99e5c69283c..ca0bd0e5d0bc1 100644 --- a/test/test_other.py +++ b/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 diff --git a/tools/ports/__init__.py b/tools/ports/__init__.py index 6aa46a834b47f..594d6dd1d02b3 100644 --- a/tools/ports/__init__.py +++ b/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: