Skip to content

Commit 6797625

Browse files
authored
Added a way to get more information a port (#21376)
1 parent 0c070c4 commit 6797625

File tree

5 files changed

+38
-4
lines changed

5 files changed

+38
-4
lines changed

docs/emcc.txt

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -475,8 +475,9 @@ Options that are modified or new in *emcc* are listed below:
475475
port=sdl2 --use-port=bzip2"). A port can have options separated by
476476
":" (ex: "--use-port=sdl2_image:formats=png,jpg"). To use an
477477
external port, you provide the path to the port directly (ex: "--
478-
use-port=/path/to/my_port.py"). To get the list of available ports,
479-
use "--show-ports".
478+
use-port=/path/to/my_port.py"). To get more information about a
479+
port, use the "help" option (ex: "--use-port=sdl2_image:help"). To
480+
get the list of available ports, use "--show-ports".
480481

481482
"--clear-ports"
482483
[general] Manually clears the local copies of ports from the

site/source/docs/tools_reference/emcc.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -466,8 +466,9 @@ Options that are modified or new in *emcc* are listed below:
466466
can have options separated by ``:``
467467
(ex: ``--use-port=sdl2_image:formats=png,jpg``). To use an external port,
468468
you provide the path to the port directly
469-
(ex: ``--use-port=/path/to/my_port.py``). To get the list of available ports,
470-
use ``--show-ports``.
469+
(ex: ``--use-port=/path/to/my_port.py``). To get more information about a
470+
port, use the ``help`` option (ex: ``--use-port=sdl2_image:help``).
471+
To get the list of available ports, use ``--show-ports``.
471472

472473
.. _emcc-clear-ports:
473474

test/other/ports/external.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66
import os
77
from typing import Dict, Optional
88

9+
URL = 'https://emscripten.org'
10+
DESCRIPTION = 'Test Description'
11+
LICENSE = 'Test License'
12+
913
OPTIONS = {
1014
'value1': 'Value for define TEST_VALUE_1',
1115
'value2': 'Value for define TEST_VALUE_2',

test/test_other.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2435,6 +2435,16 @@ def test_external_ports(self):
24352435
stderr = self.expect_fail([EMCC, test_file('other/test_external_ports.c'), f'--use-port={external_port_path}:dependency=invalid', '-o', 'a4.out.js'])
24362436
self.assertFalse(os.path.exists('a4.out.js'))
24372437
self.assertContained('unknown dependency `invalid` for port `external`', stderr)
2438+
# testing help
2439+
stdout = self.run_process([EMCC, test_file('other/test_external_ports.c'), f'--use-port={external_port_path}:help'], stdout=PIPE).stdout
2440+
self.assertContained('''external (--use-port=external; Test License)
2441+
Test Description
2442+
Options:
2443+
* value1: Value for define TEST_VALUE_1
2444+
* value2: Value for define TEST_VALUE_2
2445+
* dependency: A dependency
2446+
More info: https://emscripten.org
2447+
''', stdout)
24382448

24392449
def test_link_memcpy(self):
24402450
# memcpy can show up *after* optimizations, so after our opportunity to link in libc, so it must be special-cased

tools/ports/__init__.py

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
import shutil
1010
import glob
1111
import importlib.util
12+
import sys
1213
from typing import Set
1314
from tools import cache
1415
from tools import config
@@ -405,6 +406,21 @@ def handle_use_port_error(arg, message):
405406
utils.exit_with_error(f'error with `--use-port={arg}` | {message}')
406407

407408

409+
def show_port_help_and_exit(port):
410+
print(port.show())
411+
if hasattr(port, 'DESCRIPTION'):
412+
print(port.DESCRIPTION)
413+
if hasattr(port, 'OPTIONS'):
414+
print("Options:")
415+
for option, desc in port.OPTIONS.items():
416+
print(f'* {option}: {desc}')
417+
else:
418+
print("No options.")
419+
if hasattr(port, 'URL'):
420+
print(f'More info: {port.URL}')
421+
sys.exit(0)
422+
423+
408424
def handle_use_port_arg(settings, arg, error_handler=None):
409425
if not error_handler:
410426
def error_handler(message):
@@ -425,6 +441,8 @@ def error_handler(message):
425441
ports_needed.add(name)
426442
if options:
427443
port = ports_by_name[name]
444+
if options == 'help':
445+
show_port_help_and_exit(port)
428446
if not hasattr(port, 'handle_options'):
429447
error_handler(f'no options available for port `{name}`')
430448
else:

0 commit comments

Comments
 (0)