From 19f05833a8243acc94dce77cb26b70e34aaf7ea1 Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Mon, 29 Jan 2024 16:09:37 -0800
Subject: [PATCH 01/11] added PORTS new settings

- all official ports can be used with this setting
---
 .../tools_reference/settings_reference.rst    | 27 ++++++++
 src/settings.js                               | 24 ++++++++
 test/test_browser.py                          |  4 ++
 tools/ports/__init__.py                       | 61 +++++++++++--------
 tools/ports/boost_headers.py                  |  2 +-
 tools/ports/bullet.py                         |  2 +-
 tools/ports/bzip2.py                          |  2 +-
 tools/ports/cocos2d.py                        |  2 +-
 tools/ports/freetype.py                       |  2 +-
 tools/ports/giflib.py                         |  2 +-
 tools/ports/harfbuzz.py                       |  2 +-
 tools/ports/icu.py                            |  2 +-
 tools/ports/libjpeg.py                        |  2 +-
 tools/ports/libmodplug.py                     |  2 +-
 tools/ports/libpng.py                         |  2 +-
 tools/ports/mpg123.py                         |  2 +-
 tools/ports/ogg.py                            |  2 +-
 tools/ports/regal.py                          |  2 +-
 tools/ports/sdl2.py                           |  2 +-
 tools/ports/sdl2_gfx.py                       |  2 +-
 tools/ports/sdl2_image.py                     |  2 +-
 tools/ports/sdl2_mixer.py                     |  2 +-
 tools/ports/sdl2_net.py                       |  2 +-
 tools/ports/sdl2_ttf.py                       |  2 +-
 tools/ports/sqlite3.py                        |  2 +-
 tools/ports/vorbis.py                         |  2 +-
 tools/ports/zlib.py                           |  2 +-
 tools/settings.py                             |  1 +
 28 files changed, 113 insertions(+), 50 deletions(-)

diff --git a/site/source/docs/tools_reference/settings_reference.rst b/site/source/docs/tools_reference/settings_reference.rst
index 1c1048be5f9d9..f8bad6a12cad1 100644
--- a/site/source/docs/tools_reference/settings_reference.rst
+++ b/site/source/docs/tools_reference/settings_reference.rst
@@ -1700,6 +1700,15 @@ Specify the GLFW version that is being linked against.  Only relevant, if you
 are linking against the GLFW library.  Valid options are 2 for GLFW2 and 3
 for GLFW3.
 
+.. _ports:
+
+PORTS
+=====
+
+Specify which ports to use. If there is only one port to use, it can be
+specified this way -sPORTS=port. If multiple ports are need, you
+specify it that way: -sPORTS=[port1,port2].
+
 .. _wasm:
 
 WASM
@@ -1849,6 +1858,7 @@ Specify the SDL version that is being linked against.
 2 is a port of the SDL C code on emscripten-ports
 When AUTO_JS_LIBRARIES is set to 0 this defaults to 0 and SDL
 is not linked in.
+Alternate syntax for using the port: -sPORTS=sdl2
 
 .. note:: Applicable during both linking and compilation
 
@@ -1894,6 +1904,7 @@ USE_ICU
 =======
 
 1 = use icu from emscripten-ports
+Alternate syntax: -sPORTS=icu
 
 .. note:: Applicable during both linking and compilation
 
@@ -1903,6 +1914,7 @@ USE_ZLIB
 ========
 
 1 = use zlib from emscripten-ports
+Alternate syntax: -sPORTS=zlib
 
 .. note:: Applicable during both linking and compilation
 
@@ -1912,6 +1924,7 @@ USE_BZIP2
 =========
 
 1 = use bzip2 from emscripten-ports
+Alternate syntax: -sPORTS=bzip2
 
 .. note:: Applicable during both linking and compilation
 
@@ -1921,6 +1934,7 @@ USE_GIFLIB
 ==========
 
 1 = use giflib from emscripten-ports
+Alternate syntax: -sPORTS=giflib
 
 .. note:: Applicable during both linking and compilation
 
@@ -1930,6 +1944,7 @@ USE_LIBJPEG
 ===========
 
 1 = use libjpeg from emscripten-ports
+Alternate syntax: -sPORTS=libjpeg
 
 .. note:: Applicable during both linking and compilation
 
@@ -1939,6 +1954,7 @@ USE_LIBPNG
 ==========
 
 1 = use libpng from emscripten-ports
+Alternate syntax: -sPORTS=libpng
 
 .. note:: Applicable during both linking and compilation
 
@@ -1948,6 +1964,7 @@ USE_REGAL
 =========
 
 1 = use Regal from emscripten-ports
+Alternate syntax: -sPORTS=regal
 
 .. note:: Applicable during both linking and compilation
 
@@ -1957,6 +1974,7 @@ USE_BOOST_HEADERS
 =================
 
 1 = use Boost headers from emscripten-ports
+Alternate syntax: -sPORTS=boost_headers
 
 .. note:: Applicable during both linking and compilation
 
@@ -1966,6 +1984,7 @@ USE_BULLET
 ==========
 
 1 = use bullet from emscripten-ports
+Alternate syntax: -sPORTS=bullet
 
 .. note:: Applicable during both linking and compilation
 
@@ -1975,6 +1994,7 @@ USE_VORBIS
 ==========
 
 1 = use vorbis from emscripten-ports
+Alternate syntax: -sPORTS=vorbis
 
 .. note:: Applicable during both linking and compilation
 
@@ -1984,6 +2004,7 @@ USE_OGG
 =======
 
 1 = use ogg from emscripten-ports
+Alternate syntax: -sPORTS=ogg
 
 .. note:: Applicable during both linking and compilation
 
@@ -1993,6 +2014,7 @@ USE_MPG123
 ==========
 
 1 = use mpg123 from emscripten-ports
+Alternate syntax: -sPORTS=mpg123
 
 .. note:: Applicable during both linking and compilation
 
@@ -2002,6 +2024,7 @@ USE_FREETYPE
 ============
 
 1 = use freetype from emscripten-ports
+Alternate syntax: -sPORTS=freetype
 
 .. note:: Applicable during both linking and compilation
 
@@ -2021,6 +2044,7 @@ USE_HARFBUZZ
 ============
 
 1 = use harfbuzz from harfbuzz upstream
+Alternate syntax: -sPORTS=harfbuzz
 
 .. note:: Applicable during both linking and compilation
 
@@ -2030,6 +2054,7 @@ USE_COCOS2D
 ===========
 
 3 = use cocos2d v3 from emscripten-ports
+Alternate syntax: -sPORTS=cocos2d
 
 .. note:: Applicable during both linking and compilation
 
@@ -2039,6 +2064,7 @@ USE_MODPLUG
 ===========
 
 1 = use libmodplug from emscripten-ports
+Alternate syntax: -sPORTS=libmodplug
 
 .. note:: Applicable during both linking and compilation
 
@@ -2063,6 +2089,7 @@ USE_SQLITE3
 ===========
 
 1 = use sqlite3 from emscripten-ports
+Alternate syntax: -sPORTS=sqlite3
 
 .. note:: Applicable during both linking and compilation
 
diff --git a/src/settings.js b/src/settings.js
index bb417e8cc564e..503fbc5679fa7 100644
--- a/src/settings.js
+++ b/src/settings.js
@@ -1339,6 +1339,12 @@ var EMSCRIPTEN_TRACING = false;
 // [link]
 var USE_GLFW = 0;
 
+// Specify which ports to use. If there is only one port to use, it can be
+// specified this way -sPORTS=port. If multiple ports are need, you
+// specify it that way: -sPORTS=[port1,port2].
+// [link]
+var PORTS = [];
+
 // Whether to use compile code to WebAssembly. Set this to 0 to compile to JS
 // instead of wasm.
 //
@@ -1455,6 +1461,7 @@ var LEGALIZE_JS_FFI = true;
 // 2 is a port of the SDL C code on emscripten-ports
 // When AUTO_JS_LIBRARIES is set to 0 this defaults to 0 and SDL
 // is not linked in.
+// Alternate syntax for using the port: -sPORTS=sdl2
 // [compile+link]
 var USE_SDL = 0;
 
@@ -1475,54 +1482,67 @@ var USE_SDL_TTF = 1;
 var USE_SDL_NET = 1;
 
 // 1 = use icu from emscripten-ports
+// Alternate syntax: -sPORTS=icu
 // [compile+link]
 var USE_ICU = false;
 
 // 1 = use zlib from emscripten-ports
+// Alternate syntax: -sPORTS=zlib
 // [compile+link]
 var USE_ZLIB = false;
 
 // 1 = use bzip2 from emscripten-ports
+// Alternate syntax: -sPORTS=bzip2
 // [compile+link]
 var USE_BZIP2 = false;
 
 // 1 = use giflib from emscripten-ports
+// Alternate syntax: -sPORTS=giflib
 // [compile+link]
 var USE_GIFLIB = false;
 
 // 1 = use libjpeg from emscripten-ports
+// Alternate syntax: -sPORTS=libjpeg
 // [compile+link]
 var USE_LIBJPEG = false;
 
 // 1 = use libpng from emscripten-ports
+// Alternate syntax: -sPORTS=libpng
 // [compile+link]
 var USE_LIBPNG = false;
 
 // 1 = use Regal from emscripten-ports
+// Alternate syntax: -sPORTS=regal
 // [compile+link]
 var USE_REGAL = false;
 
 // 1 = use Boost headers from emscripten-ports
+// Alternate syntax: -sPORTS=boost_headers
 // [compile+link]
 var USE_BOOST_HEADERS = false;
 
 // 1 = use bullet from emscripten-ports
+// Alternate syntax: -sPORTS=bullet
 // [compile+link]
 var USE_BULLET = false;
 
 // 1 = use vorbis from emscripten-ports
+// Alternate syntax: -sPORTS=vorbis
 // [compile+link]
 var USE_VORBIS = false;
 
 // 1 = use ogg from emscripten-ports
+// Alternate syntax: -sPORTS=ogg
 // [compile+link]
 var USE_OGG = false;
 
 // 1 = use mpg123 from emscripten-ports
+// Alternate syntax: -sPORTS=mpg123
 // [compile+link]
 var USE_MPG123 = false;
 
 // 1 = use freetype from emscripten-ports
+// Alternate syntax: -sPORTS=freetype
 // [compile+link]
 var USE_FREETYPE = false;
 
@@ -1532,14 +1552,17 @@ var USE_FREETYPE = false;
 var USE_SDL_MIXER = 1;
 
 // 1 = use harfbuzz from harfbuzz upstream
+// Alternate syntax: -sPORTS=harfbuzz
 // [compile+link]
 var USE_HARFBUZZ = false;
 
 // 3 = use cocos2d v3 from emscripten-ports
+// Alternate syntax: -sPORTS=cocos2d
 // [compile+link]
 var USE_COCOS2D = 0;
 
 // 1 = use libmodplug from emscripten-ports
+// Alternate syntax: -sPORTS=libmodplug
 // [compile+link]
 var USE_MODPLUG = false;
 
@@ -1553,6 +1576,7 @@ var SDL2_IMAGE_FORMATS = [];
 var SDL2_MIXER_FORMATS = ["ogg"];
 
 // 1 = use sqlite3 from emscripten-ports
+// Alternate syntax: -sPORTS=sqlite3
 // [compile+link]
 var USE_SQLITE3 = false;
 
diff --git a/test/test_browser.py b/test/test_browser.py
index 5182b42d66a3d..5bbb45bdd388d 100644
--- a/test/test_browser.py
+++ b/test/test_browser.py
@@ -3335,6 +3335,8 @@ def test_sdl2_fog_simple(self):
     shutil.copyfile(test_file('screenshot.png'), 'screenshot.png')
     self.btest('test_sdl2_fog_simple.c', reference='screenshot-fog-simple.png',
                args=['-sUSE_SDL=2', '-sUSE_SDL_IMAGE=2', '-O2', '--minify=0', '--preload-file', 'screenshot.png', '-sLEGACY_GL_EMULATION', '--use-preload-plugins'])
+    self.btest('test_sdl2_fog_simple.c', reference='screenshot-fog-simple.png',
+               args=['-sPORTS=[sdl2,sdl2_image]', '-O2', '--minify=0', '--preload-file', 'screenshot.png', '-sLEGACY_GL_EMULATION', '--use-preload-plugins'])
 
   @no_wasm64('SDL2 + wasm64')
   @requires_graphics_hardware
@@ -3389,6 +3391,8 @@ def test_sdl2_ttf(self):
     shutil.copy2(test_file('freetype/LiberationSansBold.ttf'), self.get_dir())
     self.btest('test_sdl2_ttf.c', reference='browser/test_sdl2_ttf.png',
                args=['-O2', '-sUSE_SDL=2', '-sUSE_SDL_TTF=2', '--embed-file', 'LiberationSansBold.ttf'])
+    self.btest('test_sdl2_ttf.c', reference='browser/test_sdl2_ttf.png',
+               args=['-O2', '-sPORTS=[sdl2,sdl2_ttf]', '--embed-file', 'LiberationSansBold.ttf'])
 
   @no_wasm64('SDL2 + wasm64')
   @requires_graphics_hardware
diff --git a/tools/ports/__init__.py b/tools/ports/__init__.py
index 50b2c333e476a..34001b5cbf49d 100644
--- a/tools/ports/__init__.py
+++ b/tools/ports/__init__.py
@@ -31,39 +31,46 @@
 logger = logging.getLogger('ports')
 
 
+def load_port(name):
+  expected_attrs = ['get', 'clear', 'show', 'needed']
+  port = __import__(name, globals(), level=1)
+  ports.append(port)
+  port.name = name
+  ports_by_name[port.name] = port
+  for a in expected_attrs:
+    assert hasattr(port, a), 'port %s is missing %s' % (port, a)
+  needed = port.needed
+  port.needed = lambda s: needed(s) or name in s.PORTS
+  if not hasattr(port, 'process_dependencies'):
+    port.process_dependencies = lambda x: 0
+  if not hasattr(port, 'linker_setup'):
+    port.linker_setup = lambda x, y: 0
+  if not hasattr(port, 'deps'):
+    port.deps = []
+  if not hasattr(port, 'process_args'):
+    port.process_args = lambda x: []
+  if not hasattr(port, 'variants'):
+    # port variants (default: no variants)
+    port.variants = {}
+
+  for variant, extra_settings in port.variants.items():
+    if variant in port_variants:
+      utils.exit_with_error('duplicate port variant: %s' % variant)
+    port_variants[variant] = (port.name, extra_settings)
+
+
 @ToolchainProfiler.profile()
 def read_ports():
-  expected_attrs = ['get', 'clear', 'show', 'needed']
   for filename in os.listdir(ports_dir):
     if not filename.endswith('.py') or filename == '__init__.py':
       continue
     filename = os.path.splitext(filename)[0]
-    port = __import__(filename, globals(), level=1)
-    ports.append(port)
-    port.name = filename
-    ports_by_name[port.name] = port
-    for a in expected_attrs:
-      assert hasattr(port, a), 'port %s is missing %s' % (port, a)
-    if not hasattr(port, 'process_dependencies'):
-      port.process_dependencies = lambda x: 0
-    if not hasattr(port, 'linker_setup'):
-      port.linker_setup = lambda x, y: 0
-    if not hasattr(port, 'deps'):
-      port.deps = []
-    if not hasattr(port, 'process_args'):
-      port.process_args = lambda x: []
-    if not hasattr(port, 'variants'):
-      # port variants (default: no variants)
-      port.variants = {}
-
-    for variant, extra_settings in port.variants.items():
-      if variant in port_variants:
-        utils.exit_with_error('duplicate port variant: %s' % variant)
-      port_variants[variant] = (port.name, extra_settings)
-
-  for dep in port.deps:
-    if dep not in ports_by_name:
-      utils.exit_with_error('unknown dependency in port: %s' % dep)
+    load_port(filename)
+
+  for port in ports:
+    for dep in port.deps:
+      if dep not in ports_by_name:
+        utils.exit_with_error('unknown dependency in port: %s' % dep)
 
 
 def get_all_files_under(dirname):
diff --git a/tools/ports/boost_headers.py b/tools/ports/boost_headers.py
index 087970563e07d..1bc60c2800a8e 100644
--- a/tools/ports/boost_headers.py
+++ b/tools/ports/boost_headers.py
@@ -44,4 +44,4 @@ def process_args(ports):
 
 
 def show():
-  return 'Boost headers v1.70.0 (USE_BOOST_HEADERS=1; Boost license)'
+  return 'Boost headers v1.70.0 (-sUSE_BOOST_HEADERS=1 or -sPORTS=boost_headers; Boost license)'
diff --git a/tools/ports/bullet.py b/tools/ports/bullet.py
index 0f6dedc1ef9ea..dfabe347ec568 100644
--- a/tools/ports/bullet.py
+++ b/tools/ports/bullet.py
@@ -56,4 +56,4 @@ def process_args(ports):
 
 
 def show():
-  return 'bullet (USE_BULLET=1; zlib license)'
+  return 'bullet (-sUSE_BULLET=1 or -sPORTS=bullet; zlib license)'
diff --git a/tools/ports/bzip2.py b/tools/ports/bzip2.py
index b1b7605563ed8..0eee9d13947aa 100644
--- a/tools/ports/bzip2.py
+++ b/tools/ports/bzip2.py
@@ -35,4 +35,4 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'bzip2 (USE_BZIP2=1; BSD license)'
+  return 'bzip2 (-sUSE_BZIP2=1 or -sPORTS=bzip2; BSD license)'
diff --git a/tools/ports/cocos2d.py b/tools/ports/cocos2d.py
index 6ffe7cb790872..b9c83f9694517 100644
--- a/tools/ports/cocos2d.py
+++ b/tools/ports/cocos2d.py
@@ -74,7 +74,7 @@ def process_args(ports):
 
 
 def show():
-  return 'cocos2d'
+  return 'cocos2d (-sUSE_COCOS2D=3 or -sPORTS=cocos2d)'
 
 
 def make_source_list(cocos2d_root, cocos2dx_root):
diff --git a/tools/ports/freetype.py b/tools/ports/freetype.py
index d419bd53c6189..37c30eaebdc74 100644
--- a/tools/ports/freetype.py
+++ b/tools/ports/freetype.py
@@ -116,7 +116,7 @@ def process_args(ports):
 
 
 def show():
-  return 'freetype (USE_FREETYPE=1; freetype license)'
+  return 'freetype (-sUSE_FREETYPE=1 or -sPORTS=freetype; freetype license)'
 
 
 ftconf_h = r'''/***************************************************************************/
diff --git a/tools/ports/giflib.py b/tools/ports/giflib.py
index efc549ca543b1..adebcdffc531b 100644
--- a/tools/ports/giflib.py
+++ b/tools/ports/giflib.py
@@ -34,4 +34,4 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'giflib (USE_GIFLIB=1; MIT license)'
+  return 'giflib (-sUSE_GIFLIB=1 or -sPORTS=giflib; MIT license)'
diff --git a/tools/ports/harfbuzz.py b/tools/ports/harfbuzz.py
index 73d35c7d8a127..acab723a83940 100644
--- a/tools/ports/harfbuzz.py
+++ b/tools/ports/harfbuzz.py
@@ -152,4 +152,4 @@ def process_args(ports):
 
 
 def show():
-  return 'harfbuzz (USE_HARFBUZZ=1; MIT license)'
+  return 'harfbuzz (-sUSE_HARFBUZZ=1 or -sPORTS=harfbuzz; MIT license)'
diff --git a/tools/ports/icu.py b/tools/ports/icu.py
index 9dfef378090db..25d9119e9f001 100644
--- a/tools/ports/icu.py
+++ b/tools/ports/icu.py
@@ -100,4 +100,4 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'icu (USE_ICU=1; Unicode License)'
+  return 'icu (-sUSE_ICU=1 or -sPORTS=icu; Unicode License)'
diff --git a/tools/ports/libjpeg.py b/tools/ports/libjpeg.py
index 291716a932362..c166ce0417323 100644
--- a/tools/ports/libjpeg.py
+++ b/tools/ports/libjpeg.py
@@ -38,7 +38,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'libjpeg (USE_LIBJPEG=1; BSD license)'
+  return 'libjpeg (-sUSE_LIBJPEG=1 or -sPORTS=libjpeg; BSD license)'
 
 
 jconfig_h = '''/* jconfig.h.  Generated from jconfig.cfg by configure.  */
diff --git a/tools/ports/libmodplug.py b/tools/ports/libmodplug.py
index e1e67954fc8b9..24b363fd9c318 100644
--- a/tools/ports/libmodplug.py
+++ b/tools/ports/libmodplug.py
@@ -88,7 +88,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'libmodplug (USE_MODPLUG=1; public domain)'
+  return 'libmodplug (-sUSE_MODPLUG=1 or -sPORTS=libmodplug; public domain)'
 
 
 config_h = '''/* src/config.h.  Generated from config.h.in by configure.  */
diff --git a/tools/ports/libpng.py b/tools/ports/libpng.py
index 24ac177d029e6..df115f5571a39 100644
--- a/tools/ports/libpng.py
+++ b/tools/ports/libpng.py
@@ -58,7 +58,7 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'libpng (-sUSE_LIBPNG; zlib license)'
+  return 'libpng (-sUSE_LIBPNG or -sPORTS=libpng; zlib license)'
 
 
 pnglibconf_h = r'''/* pnglibconf.h - library build configuration */
diff --git a/tools/ports/mpg123.py b/tools/ports/mpg123.py
index b641b91969c12..65476765d54e5 100644
--- a/tools/ports/mpg123.py
+++ b/tools/ports/mpg123.py
@@ -81,7 +81,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'mpg123 (USE_MPG123=1; zlib license)'
+  return 'mpg123 (-sUSE_MPG123=1 or -sPORTS=mpg123; zlib license)'
 
 
 config_h = r'''/* src/config.h.  Generated from config.h.in by configure.  */
diff --git a/tools/ports/ogg.py b/tools/ports/ogg.py
index 9eff54d289d81..47007ba1b7e04 100644
--- a/tools/ports/ogg.py
+++ b/tools/ports/ogg.py
@@ -30,7 +30,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'ogg (USE_OGG=1; zlib license)'
+  return 'ogg (-sUSE_OGG=1 or -sPORTS=ogg; zlib license)'
 
 
 config_types_h = '''\
diff --git a/tools/ports/regal.py b/tools/ports/regal.py
index e699c4e72a94b..9652cb878b265 100644
--- a/tools/ports/regal.py
+++ b/tools/ports/regal.py
@@ -126,4 +126,4 @@ def linker_setup(ports, settings):
 
 
 def show():
-  return 'regal (USE_REGAL=1; Regal license)'
+  return 'regal (-sUSE_REGAL=1 or -sPORTS=regal; Regal license)'
diff --git a/tools/ports/sdl2.py b/tools/ports/sdl2.py
index 3378084372e64..ee7f3d7c1d012 100644
--- a/tools/ports/sdl2.py
+++ b/tools/ports/sdl2.py
@@ -91,4 +91,4 @@ def process_args(ports):
 
 
 def show():
-  return 'SDL2 (USE_SDL=2; zlib license)'
+  return 'SDL2 (-sUSE_SDL=2 or -sPORTS=sdl2; zlib license)'
diff --git a/tools/ports/sdl2_gfx.py b/tools/ports/sdl2_gfx.py
index 74b5aad3d4e25..14b8691866851 100644
--- a/tools/ports/sdl2_gfx.py
+++ b/tools/ports/sdl2_gfx.py
@@ -37,4 +37,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'SDL2_gfx (zlib license)'
+  return 'SDL2_gfx (-sUSE_SDL_GFX=2 or -sPORTS=sdl2_gfx; zlib license)'
diff --git a/tools/ports/sdl2_image.py b/tools/ports/sdl2_image.py
index 90fb2834094d1..fad9842c2bd5f 100644
--- a/tools/ports/sdl2_image.py
+++ b/tools/ports/sdl2_image.py
@@ -73,4 +73,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'SDL2_image (USE_SDL_IMAGE=2; zlib license)'
+  return 'SDL2_image (-sUSE_SDL_IMAGE=2 or -sPORTS=sdl2_image; zlib license)'
diff --git a/tools/ports/sdl2_mixer.py b/tools/ports/sdl2_mixer.py
index b759c3b43a2a2..968db1b7df27c 100644
--- a/tools/ports/sdl2_mixer.py
+++ b/tools/ports/sdl2_mixer.py
@@ -115,4 +115,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'SDL2_mixer (USE_SDL_MIXER=2; zlib license)'
+  return 'SDL2_mixer (-sUSE_SDL_MIXER=2 or -sPORTS=sdl2_mixer; zlib license)'
diff --git a/tools/ports/sdl2_net.py b/tools/ports/sdl2_net.py
index ec62e1a2e55cd..988381ee7d68c 100644
--- a/tools/ports/sdl2_net.py
+++ b/tools/ports/sdl2_net.py
@@ -38,4 +38,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'SDL2_net (zlib license)'
+  return 'SDL2_net (-sUSE_SDL_NET=2 or -sPORTS=sdl2_net; zlib license)'
diff --git a/tools/ports/sdl2_ttf.py b/tools/ports/sdl2_ttf.py
index db7674ff3f2c6..e7cffc61778d1 100644
--- a/tools/ports/sdl2_ttf.py
+++ b/tools/ports/sdl2_ttf.py
@@ -42,4 +42,4 @@ def process_args(ports):
 
 
 def show():
-  return 'SDL2_ttf (-sUSE_SDL_TTF=2; zlib license)'
+  return 'SDL2_ttf (-sUSE_SDL_TTF=2 or -sPORTS=sdl2_ttf; zlib license)'
diff --git a/tools/ports/sqlite3.py b/tools/ports/sqlite3.py
index 8bc49dbe2861d..f22f32c1da806 100644
--- a/tools/ports/sqlite3.py
+++ b/tools/ports/sqlite3.py
@@ -78,4 +78,4 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'sqlite (USE_SQLITE3=1); public domain)'
+  return 'sqlite (-sUSE_SQLITE3=1 or -sPORTS=sqlite3); public domain)'
diff --git a/tools/ports/vorbis.py b/tools/ports/vorbis.py
index 0f95756c1394e..d12ef97650de4 100644
--- a/tools/ports/vorbis.py
+++ b/tools/ports/vorbis.py
@@ -37,4 +37,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'vorbis (-sUSE_VORBIS; zlib license)'
+  return 'vorbis (-sUSE_VORBIS or -sPORTS=vorbis; zlib license)'
diff --git a/tools/ports/zlib.py b/tools/ports/zlib.py
index d78fb7e0fb62e..d614541ddbc7b 100644
--- a/tools/ports/zlib.py
+++ b/tools/ports/zlib.py
@@ -34,7 +34,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'zlib (USE_ZLIB=1; zlib license)'
+  return 'zlib (-sUSE_ZLIB=1 or -sPORTS=zlib; zlib license)'
 
 
 zconf_h = r'''/* zconf.h -- configuration of the zlib compression library
diff --git a/tools/settings.py b/tools/settings.py
index 67d01f2b98859..75668a7dd7d42 100644
--- a/tools/settings.py
+++ b/tools/settings.py
@@ -52,6 +52,7 @@
     'SDL2_MIXER_FORMATS',
     'SDL2_IMAGE_FORMATS',
     'USE_SQLITE3',
+    'PORTS'
 }
 
 # Subset of settings that apply only when generating JS

From d135cd47269e456d1b1b05def593a515867f165c Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Tue, 30 Jan 2024 06:01:28 -0800
Subject: [PATCH 02/11] check for valid port name

- added tests
---
 emcc.py                 |  2 ++
 test/test_browser.py    |  4 ----
 test/test_other.py      | 20 ++++++++++++++++++++
 tools/ports/__init__.py | 15 ++++++++++++---
 4 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/emcc.py b/emcc.py
index 8870027348fcf..b8c89fd55098f 100644
--- a/emcc.py
+++ b/emcc.py
@@ -287,6 +287,8 @@ def apply_user_settings():
     if key == 'WASM_OBJECT_FILES':
       settings.LTO = 0 if value else 'full'
 
+    ports.check_ports_settings(settings)
+
 
 def cxx_to_c_compiler(cxx):
   # Convert C++ compiler name into C compiler name
diff --git a/test/test_browser.py b/test/test_browser.py
index 5bbb45bdd388d..5182b42d66a3d 100644
--- a/test/test_browser.py
+++ b/test/test_browser.py
@@ -3335,8 +3335,6 @@ def test_sdl2_fog_simple(self):
     shutil.copyfile(test_file('screenshot.png'), 'screenshot.png')
     self.btest('test_sdl2_fog_simple.c', reference='screenshot-fog-simple.png',
                args=['-sUSE_SDL=2', '-sUSE_SDL_IMAGE=2', '-O2', '--minify=0', '--preload-file', 'screenshot.png', '-sLEGACY_GL_EMULATION', '--use-preload-plugins'])
-    self.btest('test_sdl2_fog_simple.c', reference='screenshot-fog-simple.png',
-               args=['-sPORTS=[sdl2,sdl2_image]', '-O2', '--minify=0', '--preload-file', 'screenshot.png', '-sLEGACY_GL_EMULATION', '--use-preload-plugins'])
 
   @no_wasm64('SDL2 + wasm64')
   @requires_graphics_hardware
@@ -3391,8 +3389,6 @@ def test_sdl2_ttf(self):
     shutil.copy2(test_file('freetype/LiberationSansBold.ttf'), self.get_dir())
     self.btest('test_sdl2_ttf.c', reference='browser/test_sdl2_ttf.png',
                args=['-O2', '-sUSE_SDL=2', '-sUSE_SDL_TTF=2', '--embed-file', 'LiberationSansBold.ttf'])
-    self.btest('test_sdl2_ttf.c', reference='browser/test_sdl2_ttf.png',
-               args=['-O2', '-sPORTS=[sdl2,sdl2_ttf]', '--embed-file', 'LiberationSansBold.ttf'])
 
   @no_wasm64('SDL2 + wasm64')
   @requires_graphics_hardware
diff --git a/test/test_other.py b/test/test_other.py
index 7191bc1120e82..36f7df166f9e8 100644
--- a/test/test_other.py
+++ b/test/test_other.py
@@ -2250,20 +2250,25 @@ def test_sdl_scan_code_from_key(self):
 
   def test_sdl2_mixer_wav(self):
     self.emcc(test_file('browser/test_sdl2_mixer_wav.c'), ['-sUSE_SDL_MIXER=2'], output_filename='a.out.js')
+    self.emcc(test_file('browser/test_sdl2_mixer_wav.c'), ['-sPORTS=sdl2_mixer'], output_filename='a.out.js')
 
   def test_sdl2_linkable(self):
     # Ensure that SDL2 can be built with LINKABLE.  This implies there are no undefined
     # symbols in the library (because LINKABLE includes the entire library).
     self.emcc(test_file('browser/test_sdl2_misc.c'), ['-sLINKABLE', '-sUSE_SDL=2'], output_filename='a.out.js')
+    self.emcc(test_file('browser/test_sdl2_misc.c'), ['-sLINKABLE', '-sPORTS=sdl2'], output_filename='a.out.js')
 
   def test_sdl2_gfx_linkable(self):
     # Same as above but for sdl2_gfx library
     self.emcc(test_file('browser/test_sdl2_misc.c'), ['-Wl,-fatal-warnings', '-sLINKABLE', '-sUSE_SDL_GFX=2'], output_filename='a.out.js')
+    self.emcc(test_file('browser/test_sdl2_misc.c'), ['-Wl,-fatal-warnings', '-sLINKABLE', '-sPORTS=sdl2_gfx'], output_filename='a.out.js')
 
   def test_libpng(self):
     shutil.copyfile(test_file('third_party/libpng/pngtest.png'), 'pngtest.png')
     self.do_runf('third_party/libpng/pngtest.c', 'libpng passes test',
                  emcc_args=['--embed-file', 'pngtest.png', '-sUSE_LIBPNG'])
+    self.do_runf('third_party/libpng/pngtest.c', 'libpng passes test',
+                 emcc_args=['--embed-file', 'pngtest.png', '-sPORTS=libpng'])
 
   @node_pthreads
   def test_libpng_with_pthreads(self):
@@ -2284,23 +2289,34 @@ def test_giflib(self):
                  'GIF file terminated normally',
                  emcc_args=['--embed-file', 'treescap.gif', '-sUSE_GIFLIB', '-sMAIN_MODULE'],
                  args=['treescap.gif'])
+    self.do_runf('third_party/giflib/giftext.c',
+                 'GIF file terminated normally',
+                 emcc_args=['--embed-file', 'treescap.gif', '-sPORTS=giflib'],
+                 args=['treescap.gif'])
 
   def test_libjpeg(self):
     shutil.copyfile(test_file('screenshot.jpg'), 'screenshot.jpg')
     self.do_runf('jpeg_test.c', 'Image is 600 by 450 with 3 components',
                  emcc_args=['--embed-file', 'screenshot.jpg', '-sUSE_LIBJPEG'],
                  args=['screenshot.jpg'])
+    self.do_runf('jpeg_test.c', 'Image is 600 by 450 with 3 components',
+                 emcc_args=['--embed-file', 'screenshot.jpg', '-sPORTS=libjpeg'],
+                 args=['screenshot.jpg'])
 
   def test_bullet(self):
     self.do_runf('bullet_hello_world.cpp', 'BULLET RUNNING', emcc_args=['-sUSE_BULLET'])
+    self.do_runf('bullet_hello_world.cpp', 'BULLET RUNNING', emcc_args=['-sPORTS=bullet'])
 
   def test_vorbis(self):
     # This will also test if ogg compiles, because vorbis depends on ogg
     self.do_runf('vorbis_test.c', 'ALL OK', emcc_args=['-sUSE_VORBIS'])
+    self.do_runf('vorbis_test.c', 'ALL OK', emcc_args=['-sPORTS=vorbis'])
 
   def test_bzip2(self):
     self.do_runf('bzip2_test.c', 'usage: unzcrash filename',
                  emcc_args=['-sUSE_BZIP2', '-Wno-pointer-sign'])
+    self.do_runf('bzip2_test.c', 'usage: unzcrash filename',
+                 emcc_args=['-sPORTS=bzip2', '-Wno-pointer-sign'])
 
   @with_both_sjlj
   def test_freetype(self):
@@ -2328,6 +2344,8 @@ def test_freetype(self):
     # build test program with the font file embed in it
     self.do_runf('freetype_test.c', expectedOutput,
                  emcc_args=['-sUSE_FREETYPE', '--embed-file', 'LiberationSansBold.ttf'])
+    self.do_runf('freetype_test.c', expectedOutput,
+                 emcc_args=['-sPORTS=freetype', '--embed-file', 'LiberationSansBold.ttf'])
 
   def test_freetype_with_pthreads(self):
     # Verify that freetype supports compilation requiring pthreads
@@ -2340,6 +2358,7 @@ def test_icu(self):
   def test_sdl2_ttf(self):
     # This is a compile-only to test to verify that sdl2-ttf (and freetype and harfbuzz) are buildable.
     self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['-sUSE_SDL=2', '-sUSE_SDL_TTF=2'], output_filename='a.out.js')
+    self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['-sPORTS=sdl2_ttf'], output_filename='a.out.js')
 
   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
@@ -11411,6 +11430,7 @@ def test_em_asm_invalid(self):
 
   def test_boost_graph(self):
     self.do_runf('test_boost_graph.cpp', emcc_args=['-std=c++14', '-sUSE_BOOST_HEADERS'])
+    self.do_runf('test_boost_graph.cpp', emcc_args=['-std=c++14', '-sPORTS=boost_headers'])
 
   def test_setjmp_em_asm(self):
     create_file('src.c', '''
diff --git a/tools/ports/__init__.py b/tools/ports/__init__.py
index 34001b5cbf49d..dbe866c4891fa 100644
--- a/tools/ports/__init__.py
+++ b/tools/ports/__init__.py
@@ -32,15 +32,18 @@
 
 
 def load_port(name):
-  expected_attrs = ['get', 'clear', 'show', 'needed']
+  expected_attrs = ['get', 'clear', 'show']
   port = __import__(name, globals(), level=1)
   ports.append(port)
   port.name = name
   ports_by_name[port.name] = port
   for a in expected_attrs:
     assert hasattr(port, a), 'port %s is missing %s' % (port, a)
-  needed = port.needed
-  port.needed = lambda s: needed(s) or name in s.PORTS
+  if not hasattr(port, 'needed'):
+    port.needed = lambda s: name in s.PORTS
+  else:
+    needed = port.needed
+    port.needed = lambda s: needed(s) or name in s.PORTS
   if not hasattr(port, 'process_dependencies'):
     port.process_dependencies = lambda x: 0
   if not hasattr(port, 'linker_setup'):
@@ -368,6 +371,12 @@ def add_deps(node):
     add_deps(port)
 
 
+def check_ports_settings(settings):
+  for name in settings.PORTS:
+    if name not in ports_by_name:
+      utils.exit_with_error(f'Invalid port name: {name}')
+
+
 def get_needed_ports(settings):
   # Start with directly needed ports, and transitively add dependencies
   needed = set(p for p in ports if p.needed(settings))

From 831c52339a976e6fc876ecf5892a573ba40db23b Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Wed, 31 Jan 2024 07:15:28 -0800
Subject: [PATCH 03/11] use --use-port instead of -sPORTS

---
 emcc.py                                       |  4 +-
 site/source/docs/tools_reference/emcc.rst     |  8 ++++
 .../tools_reference/settings_reference.rst    | 45 ++++++++-----------
 src/settings.js                               | 42 ++++++++---------
 src/settings_internal.js                      |  4 ++
 test/test_other.py                            | 24 +++++-----
 tools/ports/__init__.py                       | 10 ++---
 tools/ports/boost_headers.py                  |  2 +-
 tools/ports/bullet.py                         |  2 +-
 tools/ports/bzip2.py                          |  2 +-
 tools/ports/cocos2d.py                        |  2 +-
 tools/ports/freetype.py                       |  2 +-
 tools/ports/giflib.py                         |  2 +-
 tools/ports/harfbuzz.py                       |  2 +-
 tools/ports/icu.py                            |  2 +-
 tools/ports/libjpeg.py                        |  2 +-
 tools/ports/libmodplug.py                     |  2 +-
 tools/ports/libpng.py                         |  2 +-
 tools/ports/mpg123.py                         |  2 +-
 tools/ports/ogg.py                            |  2 +-
 tools/ports/regal.py                          |  2 +-
 tools/ports/sdl2.py                           |  2 +-
 tools/ports/sdl2_gfx.py                       |  2 +-
 tools/ports/sdl2_image.py                     |  2 +-
 tools/ports/sdl2_mixer.py                     |  2 +-
 tools/ports/sdl2_net.py                       |  2 +-
 tools/ports/sdl2_ttf.py                       |  2 +-
 tools/ports/sqlite3.py                        |  2 +-
 tools/ports/vorbis.py                         |  2 +-
 tools/ports/zlib.py                           |  2 +-
 30 files changed, 90 insertions(+), 93 deletions(-)

diff --git a/emcc.py b/emcc.py
index b8c89fd55098f..9f6afb7d54109 100644
--- a/emcc.py
+++ b/emcc.py
@@ -287,8 +287,6 @@ def apply_user_settings():
     if key == 'WASM_OBJECT_FILES':
       settings.LTO = 0 if value else 'full'
 
-    ports.check_ports_settings(settings)
-
 
 def cxx_to_c_compiler(cxx):
   # Convert C++ compiler name into C compiler name
@@ -1407,6 +1405,8 @@ def consume_arg_file():
       options.target = consume_arg()
       if options.target not in ('wasm32', 'wasm64', 'wasm64-unknown-emscripten', 'wasm32-unknown-emscripten'):
         exit_with_error(f'unsupported target: {options.target} (emcc only supports wasm64-unknown-emscripten and wasm32-unknown-emscripten)')
+    elif check_arg('--use-port'):
+      ports.handle_use_port_arg(settings, consume_arg())
     elif arg == '-mllvm':
       # Ignore the next argument rather than trying to parse it.  This is needed
       # because llvm args could, for example, start with `-o` and we don't want
diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst
index 8527aa4f3f531..010c5dcca9604 100644
--- a/site/source/docs/tools_reference/emcc.rst
+++ b/site/source/docs/tools_reference/emcc.rst
@@ -455,6 +455,14 @@ Options that are modified or new in *emcc* are listed below:
   By default this will also clear any download ports since the ports directory
   is usually within the cache directory.
 
+.. _emcc-use-port:
+
+``--use-port=<port>``
+  [link]
+  Use the specified port. If you need to use more than one port you can use this
+  argument multiple times. For example: ``--user-port=sdl2 --user-port=bzip2``.
+  To get the list of available ports, use ``--show-ports``.
+
 .. _emcc-clear-ports:
 
 ``--clear-ports``
diff --git a/site/source/docs/tools_reference/settings_reference.rst b/site/source/docs/tools_reference/settings_reference.rst
index f8bad6a12cad1..2e399acfda1d6 100644
--- a/site/source/docs/tools_reference/settings_reference.rst
+++ b/site/source/docs/tools_reference/settings_reference.rst
@@ -1700,15 +1700,6 @@ Specify the GLFW version that is being linked against.  Only relevant, if you
 are linking against the GLFW library.  Valid options are 2 for GLFW2 and 3
 for GLFW3.
 
-.. _ports:
-
-PORTS
-=====
-
-Specify which ports to use. If there is only one port to use, it can be
-specified this way -sPORTS=port. If multiple ports are need, you
-specify it that way: -sPORTS=[port1,port2].
-
 .. _wasm:
 
 WASM
@@ -1858,7 +1849,7 @@ Specify the SDL version that is being linked against.
 2 is a port of the SDL C code on emscripten-ports
 When AUTO_JS_LIBRARIES is set to 0 this defaults to 0 and SDL
 is not linked in.
-Alternate syntax for using the port: -sPORTS=sdl2
+Alternate syntax for using the port: --use-port=sdl2
 
 .. note:: Applicable during both linking and compilation
 
@@ -1904,7 +1895,7 @@ USE_ICU
 =======
 
 1 = use icu from emscripten-ports
-Alternate syntax: -sPORTS=icu
+Alternate syntax: --use-port=icu
 
 .. note:: Applicable during both linking and compilation
 
@@ -1914,7 +1905,7 @@ USE_ZLIB
 ========
 
 1 = use zlib from emscripten-ports
-Alternate syntax: -sPORTS=zlib
+Alternate syntax: --use-port=zlib
 
 .. note:: Applicable during both linking and compilation
 
@@ -1924,7 +1915,7 @@ USE_BZIP2
 =========
 
 1 = use bzip2 from emscripten-ports
-Alternate syntax: -sPORTS=bzip2
+Alternate syntax: --use-port=bzip2
 
 .. note:: Applicable during both linking and compilation
 
@@ -1934,7 +1925,7 @@ USE_GIFLIB
 ==========
 
 1 = use giflib from emscripten-ports
-Alternate syntax: -sPORTS=giflib
+Alternate syntax: --use-port=giflib
 
 .. note:: Applicable during both linking and compilation
 
@@ -1944,7 +1935,7 @@ USE_LIBJPEG
 ===========
 
 1 = use libjpeg from emscripten-ports
-Alternate syntax: -sPORTS=libjpeg
+Alternate syntax: --use-port=libjpeg
 
 .. note:: Applicable during both linking and compilation
 
@@ -1954,7 +1945,7 @@ USE_LIBPNG
 ==========
 
 1 = use libpng from emscripten-ports
-Alternate syntax: -sPORTS=libpng
+Alternate syntax: --use-port=libpng
 
 .. note:: Applicable during both linking and compilation
 
@@ -1964,7 +1955,7 @@ USE_REGAL
 =========
 
 1 = use Regal from emscripten-ports
-Alternate syntax: -sPORTS=regal
+Alternate syntax: --use-port=regal
 
 .. note:: Applicable during both linking and compilation
 
@@ -1974,7 +1965,7 @@ USE_BOOST_HEADERS
 =================
 
 1 = use Boost headers from emscripten-ports
-Alternate syntax: -sPORTS=boost_headers
+Alternate syntax: --use-port=boost_headers
 
 .. note:: Applicable during both linking and compilation
 
@@ -1984,7 +1975,7 @@ USE_BULLET
 ==========
 
 1 = use bullet from emscripten-ports
-Alternate syntax: -sPORTS=bullet
+Alternate syntax: --use-port=bullet
 
 .. note:: Applicable during both linking and compilation
 
@@ -1994,7 +1985,7 @@ USE_VORBIS
 ==========
 
 1 = use vorbis from emscripten-ports
-Alternate syntax: -sPORTS=vorbis
+Alternate syntax: --use-port=vorbis
 
 .. note:: Applicable during both linking and compilation
 
@@ -2004,7 +1995,7 @@ USE_OGG
 =======
 
 1 = use ogg from emscripten-ports
-Alternate syntax: -sPORTS=ogg
+Alternate syntax: --use-port=ogg
 
 .. note:: Applicable during both linking and compilation
 
@@ -2014,7 +2005,7 @@ USE_MPG123
 ==========
 
 1 = use mpg123 from emscripten-ports
-Alternate syntax: -sPORTS=mpg123
+Alternate syntax: --use-port=mpg123
 
 .. note:: Applicable during both linking and compilation
 
@@ -2024,7 +2015,7 @@ USE_FREETYPE
 ============
 
 1 = use freetype from emscripten-ports
-Alternate syntax: -sPORTS=freetype
+Alternate syntax: --use-port=freetype
 
 .. note:: Applicable during both linking and compilation
 
@@ -2044,7 +2035,7 @@ USE_HARFBUZZ
 ============
 
 1 = use harfbuzz from harfbuzz upstream
-Alternate syntax: -sPORTS=harfbuzz
+Alternate syntax: --use-port=harfbuzz
 
 .. note:: Applicable during both linking and compilation
 
@@ -2054,7 +2045,7 @@ USE_COCOS2D
 ===========
 
 3 = use cocos2d v3 from emscripten-ports
-Alternate syntax: -sPORTS=cocos2d
+Alternate syntax: --use-port=cocos2d
 
 .. note:: Applicable during both linking and compilation
 
@@ -2064,7 +2055,7 @@ USE_MODPLUG
 ===========
 
 1 = use libmodplug from emscripten-ports
-Alternate syntax: -sPORTS=libmodplug
+Alternate syntax: --use-port=libmodplug
 
 .. note:: Applicable during both linking and compilation
 
@@ -2089,7 +2080,7 @@ USE_SQLITE3
 ===========
 
 1 = use sqlite3 from emscripten-ports
-Alternate syntax: -sPORTS=sqlite3
+Alternate syntax: --use-port=sqlite3
 
 .. note:: Applicable during both linking and compilation
 
diff --git a/src/settings.js b/src/settings.js
index 503fbc5679fa7..df9e86b40e063 100644
--- a/src/settings.js
+++ b/src/settings.js
@@ -1339,12 +1339,6 @@ var EMSCRIPTEN_TRACING = false;
 // [link]
 var USE_GLFW = 0;
 
-// Specify which ports to use. If there is only one port to use, it can be
-// specified this way -sPORTS=port. If multiple ports are need, you
-// specify it that way: -sPORTS=[port1,port2].
-// [link]
-var PORTS = [];
-
 // Whether to use compile code to WebAssembly. Set this to 0 to compile to JS
 // instead of wasm.
 //
@@ -1461,7 +1455,7 @@ var LEGALIZE_JS_FFI = true;
 // 2 is a port of the SDL C code on emscripten-ports
 // When AUTO_JS_LIBRARIES is set to 0 this defaults to 0 and SDL
 // is not linked in.
-// Alternate syntax for using the port: -sPORTS=sdl2
+// Alternate syntax for using the port: --use-port=sdl2
 // [compile+link]
 var USE_SDL = 0;
 
@@ -1482,67 +1476,67 @@ var USE_SDL_TTF = 1;
 var USE_SDL_NET = 1;
 
 // 1 = use icu from emscripten-ports
-// Alternate syntax: -sPORTS=icu
+// Alternate syntax: --use-port=icu
 // [compile+link]
 var USE_ICU = false;
 
 // 1 = use zlib from emscripten-ports
-// Alternate syntax: -sPORTS=zlib
+// Alternate syntax: --use-port=zlib
 // [compile+link]
 var USE_ZLIB = false;
 
 // 1 = use bzip2 from emscripten-ports
-// Alternate syntax: -sPORTS=bzip2
+// Alternate syntax: --use-port=bzip2
 // [compile+link]
 var USE_BZIP2 = false;
 
 // 1 = use giflib from emscripten-ports
-// Alternate syntax: -sPORTS=giflib
+// Alternate syntax: --use-port=giflib
 // [compile+link]
 var USE_GIFLIB = false;
 
 // 1 = use libjpeg from emscripten-ports
-// Alternate syntax: -sPORTS=libjpeg
+// Alternate syntax: --use-port=libjpeg
 // [compile+link]
 var USE_LIBJPEG = false;
 
 // 1 = use libpng from emscripten-ports
-// Alternate syntax: -sPORTS=libpng
+// Alternate syntax: --use-port=libpng
 // [compile+link]
 var USE_LIBPNG = false;
 
 // 1 = use Regal from emscripten-ports
-// Alternate syntax: -sPORTS=regal
+// Alternate syntax: --use-port=regal
 // [compile+link]
 var USE_REGAL = false;
 
 // 1 = use Boost headers from emscripten-ports
-// Alternate syntax: -sPORTS=boost_headers
+// Alternate syntax: --use-port=boost_headers
 // [compile+link]
 var USE_BOOST_HEADERS = false;
 
 // 1 = use bullet from emscripten-ports
-// Alternate syntax: -sPORTS=bullet
+// Alternate syntax: --use-port=bullet
 // [compile+link]
 var USE_BULLET = false;
 
 // 1 = use vorbis from emscripten-ports
-// Alternate syntax: -sPORTS=vorbis
+// Alternate syntax: --use-port=vorbis
 // [compile+link]
 var USE_VORBIS = false;
 
 // 1 = use ogg from emscripten-ports
-// Alternate syntax: -sPORTS=ogg
+// Alternate syntax: --use-port=ogg
 // [compile+link]
 var USE_OGG = false;
 
 // 1 = use mpg123 from emscripten-ports
-// Alternate syntax: -sPORTS=mpg123
+// Alternate syntax: --use-port=mpg123
 // [compile+link]
 var USE_MPG123 = false;
 
 // 1 = use freetype from emscripten-ports
-// Alternate syntax: -sPORTS=freetype
+// Alternate syntax: --use-port=freetype
 // [compile+link]
 var USE_FREETYPE = false;
 
@@ -1552,17 +1546,17 @@ var USE_FREETYPE = false;
 var USE_SDL_MIXER = 1;
 
 // 1 = use harfbuzz from harfbuzz upstream
-// Alternate syntax: -sPORTS=harfbuzz
+// Alternate syntax: --use-port=harfbuzz
 // [compile+link]
 var USE_HARFBUZZ = false;
 
 // 3 = use cocos2d v3 from emscripten-ports
-// Alternate syntax: -sPORTS=cocos2d
+// Alternate syntax: --use-port=cocos2d
 // [compile+link]
 var USE_COCOS2D = 0;
 
 // 1 = use libmodplug from emscripten-ports
-// Alternate syntax: -sPORTS=libmodplug
+// Alternate syntax: --use-port=libmodplug
 // [compile+link]
 var USE_MODPLUG = false;
 
@@ -1576,7 +1570,7 @@ var SDL2_IMAGE_FORMATS = [];
 var SDL2_MIXER_FORMATS = ["ogg"];
 
 // 1 = use sqlite3 from emscripten-ports
-// Alternate syntax: -sPORTS=sqlite3
+// Alternate syntax: --use-port=sqlite3
 // [compile+link]
 var USE_SQLITE3 = false;
 
diff --git a/src/settings_internal.js b/src/settings_internal.js
index 36a1887540a84..678b6ee0fae72 100644
--- a/src/settings_internal.js
+++ b/src/settings_internal.js
@@ -273,3 +273,7 @@ var BULK_MEMORY = false;
 var MINIFY_WHITESPACE = true;
 
 var ASYNCIFY_IMPORTS_EXCEPT_JS_LIBS = [];
+
+// Specify which ports to use. This is set via the --use-port command line
+// option
+var PORTS = [];
diff --git a/test/test_other.py b/test/test_other.py
index 5dc57fd302fcd..e2da26696eb32 100644
--- a/test/test_other.py
+++ b/test/test_other.py
@@ -2250,25 +2250,25 @@ def test_sdl_scan_code_from_key(self):
 
   def test_sdl2_mixer_wav(self):
     self.emcc(test_file('browser/test_sdl2_mixer_wav.c'), ['-sUSE_SDL_MIXER=2'], output_filename='a.out.js')
-    self.emcc(test_file('browser/test_sdl2_mixer_wav.c'), ['-sPORTS=sdl2_mixer'], output_filename='a.out.js')
+    self.emcc(test_file('browser/test_sdl2_mixer_wav.c'), ['--use-port=sdl2_mixer'], output_filename='a.out.js')
 
   def test_sdl2_linkable(self):
     # Ensure that SDL2 can be built with LINKABLE.  This implies there are no undefined
     # symbols in the library (because LINKABLE includes the entire library).
     self.emcc(test_file('browser/test_sdl2_misc.c'), ['-sLINKABLE', '-sUSE_SDL=2'], output_filename='a.out.js')
-    self.emcc(test_file('browser/test_sdl2_misc.c'), ['-sLINKABLE', '-sPORTS=sdl2'], output_filename='a.out.js')
+    self.emcc(test_file('browser/test_sdl2_misc.c'), ['-sLINKABLE', '--use-port=sdl2'], output_filename='a.out.js')
 
   def test_sdl2_gfx_linkable(self):
     # Same as above but for sdl2_gfx library
     self.emcc(test_file('browser/test_sdl2_misc.c'), ['-Wl,-fatal-warnings', '-sLINKABLE', '-sUSE_SDL_GFX=2'], output_filename='a.out.js')
-    self.emcc(test_file('browser/test_sdl2_misc.c'), ['-Wl,-fatal-warnings', '-sLINKABLE', '-sPORTS=sdl2_gfx'], output_filename='a.out.js')
+    self.emcc(test_file('browser/test_sdl2_misc.c'), ['-Wl,-fatal-warnings', '-sLINKABLE', '--use-port=sdl2_gfx'], output_filename='a.out.js')
 
   def test_libpng(self):
     shutil.copyfile(test_file('third_party/libpng/pngtest.png'), 'pngtest.png')
     self.do_runf('third_party/libpng/pngtest.c', 'libpng passes test',
                  emcc_args=['--embed-file', 'pngtest.png', '-sUSE_LIBPNG'])
     self.do_runf('third_party/libpng/pngtest.c', 'libpng passes test',
-                 emcc_args=['--embed-file', 'pngtest.png', '-sPORTS=libpng'])
+                 emcc_args=['--embed-file', 'pngtest.png', '--use-port=libpng'])
 
   @node_pthreads
   def test_libpng_with_pthreads(self):
@@ -2291,7 +2291,7 @@ def test_giflib(self):
                  args=['treescap.gif'])
     self.do_runf('third_party/giflib/giftext.c',
                  'GIF file terminated normally',
-                 emcc_args=['--embed-file', 'treescap.gif', '-sPORTS=giflib'],
+                 emcc_args=['--embed-file', 'treescap.gif', '--use-port=giflib'],
                  args=['treescap.gif'])
 
   def test_libjpeg(self):
@@ -2300,23 +2300,23 @@ def test_libjpeg(self):
                  emcc_args=['--embed-file', 'screenshot.jpg', '-sUSE_LIBJPEG'],
                  args=['screenshot.jpg'])
     self.do_runf('jpeg_test.c', 'Image is 600 by 450 with 3 components',
-                 emcc_args=['--embed-file', 'screenshot.jpg', '-sPORTS=libjpeg'],
+                 emcc_args=['--embed-file', 'screenshot.jpg', '--use-port=libjpeg'],
                  args=['screenshot.jpg'])
 
   def test_bullet(self):
     self.do_runf('bullet_hello_world.cpp', 'BULLET RUNNING', emcc_args=['-sUSE_BULLET'])
-    self.do_runf('bullet_hello_world.cpp', 'BULLET RUNNING', emcc_args=['-sPORTS=bullet'])
+    self.do_runf('bullet_hello_world.cpp', 'BULLET RUNNING', emcc_args=['--use-port=bullet'])
 
   def test_vorbis(self):
     # This will also test if ogg compiles, because vorbis depends on ogg
     self.do_runf('vorbis_test.c', 'ALL OK', emcc_args=['-sUSE_VORBIS'])
-    self.do_runf('vorbis_test.c', 'ALL OK', emcc_args=['-sPORTS=vorbis'])
+    self.do_runf('vorbis_test.c', 'ALL OK', emcc_args=['--use-port=vorbis'])
 
   def test_bzip2(self):
     self.do_runf('bzip2_test.c', 'usage: unzcrash filename',
                  emcc_args=['-sUSE_BZIP2', '-Wno-pointer-sign'])
     self.do_runf('bzip2_test.c', 'usage: unzcrash filename',
-                 emcc_args=['-sPORTS=bzip2', '-Wno-pointer-sign'])
+                 emcc_args=['--use-port=bzip2', '-Wno-pointer-sign'])
 
   @with_both_sjlj
   def test_freetype(self):
@@ -2345,7 +2345,7 @@ def test_freetype(self):
     self.do_runf('freetype_test.c', expectedOutput,
                  emcc_args=['-sUSE_FREETYPE', '--embed-file', 'LiberationSansBold.ttf'])
     self.do_runf('freetype_test.c', expectedOutput,
-                 emcc_args=['-sPORTS=freetype', '--embed-file', 'LiberationSansBold.ttf'])
+                 emcc_args=['--use-port=freetype', '--embed-file', 'LiberationSansBold.ttf'])
 
   def test_freetype_with_pthreads(self):
     # Verify that freetype supports compilation requiring pthreads
@@ -2358,7 +2358,7 @@ def test_icu(self):
   def test_sdl2_ttf(self):
     # This is a compile-only to test to verify that sdl2-ttf (and freetype and harfbuzz) are buildable.
     self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['-sUSE_SDL=2', '-sUSE_SDL_TTF=2'], output_filename='a.out.js')
-    self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['-sPORTS=sdl2_ttf'], output_filename='a.out.js')
+    self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['--use-port=sdl2_ttf'], output_filename='a.out.js')
 
   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
@@ -11430,7 +11430,7 @@ def test_em_asm_invalid(self):
 
   def test_boost_graph(self):
     self.do_runf('test_boost_graph.cpp', emcc_args=['-std=c++14', '-sUSE_BOOST_HEADERS'])
-    self.do_runf('test_boost_graph.cpp', emcc_args=['-std=c++14', '-sPORTS=boost_headers'])
+    self.do_runf('test_boost_graph.cpp', emcc_args=['-std=c++14', '--use-port=boost_headers'])
 
   def test_setjmp_em_asm(self):
     create_file('src.c', '''
diff --git a/tools/ports/__init__.py b/tools/ports/__init__.py
index dbe866c4891fa..f8fd156e6f011 100644
--- a/tools/ports/__init__.py
+++ b/tools/ports/__init__.py
@@ -371,10 +371,10 @@ def add_deps(node):
     add_deps(port)
 
 
-def check_ports_settings(settings):
-  for name in settings.PORTS:
-    if name not in ports_by_name:
-      utils.exit_with_error(f'Invalid port name: {name}')
+def handle_use_port_arg(settings, name):
+  if name not in ports_by_name:
+    utils.exit_with_error(f'Invalid port name: {name} used with --user-port')
+  settings.PORTS.append(name)
 
 
 def get_needed_ports(settings):
@@ -440,7 +440,7 @@ def add_cflags(args, settings): # noqa: U100
 
 def show_ports():
   print('Available ports:')
-  for port in ports:
+  for port in sorted(ports, key=lambda p: p.name):
     print('   ', port.show())
 
 
diff --git a/tools/ports/boost_headers.py b/tools/ports/boost_headers.py
index 1bc60c2800a8e..47288838e79f4 100644
--- a/tools/ports/boost_headers.py
+++ b/tools/ports/boost_headers.py
@@ -44,4 +44,4 @@ def process_args(ports):
 
 
 def show():
-  return 'Boost headers v1.70.0 (-sUSE_BOOST_HEADERS=1 or -sPORTS=boost_headers; Boost license)'
+  return 'boost_headers - Boost headers v1.70.0 (-sUSE_BOOST_HEADERS=1 or --use-port=boost_headers; Boost license)'
diff --git a/tools/ports/bullet.py b/tools/ports/bullet.py
index dfabe347ec568..a91c0b69b6285 100644
--- a/tools/ports/bullet.py
+++ b/tools/ports/bullet.py
@@ -56,4 +56,4 @@ def process_args(ports):
 
 
 def show():
-  return 'bullet (-sUSE_BULLET=1 or -sPORTS=bullet; zlib license)'
+  return 'bullet (-sUSE_BULLET=1 or --use-port=bullet; zlib license)'
diff --git a/tools/ports/bzip2.py b/tools/ports/bzip2.py
index 0eee9d13947aa..a1e8c9d49d267 100644
--- a/tools/ports/bzip2.py
+++ b/tools/ports/bzip2.py
@@ -35,4 +35,4 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'bzip2 (-sUSE_BZIP2=1 or -sPORTS=bzip2; BSD license)'
+  return 'bzip2 (-sUSE_BZIP2=1 or --use-port=bzip2; BSD license)'
diff --git a/tools/ports/cocos2d.py b/tools/ports/cocos2d.py
index b9c83f9694517..685e3b50e0610 100644
--- a/tools/ports/cocos2d.py
+++ b/tools/ports/cocos2d.py
@@ -74,7 +74,7 @@ def process_args(ports):
 
 
 def show():
-  return 'cocos2d (-sUSE_COCOS2D=3 or -sPORTS=cocos2d)'
+  return 'cocos2d (-sUSE_COCOS2D=3 or --use-port=cocos2d)'
 
 
 def make_source_list(cocos2d_root, cocos2dx_root):
diff --git a/tools/ports/freetype.py b/tools/ports/freetype.py
index 37c30eaebdc74..117fdcb7819bc 100644
--- a/tools/ports/freetype.py
+++ b/tools/ports/freetype.py
@@ -116,7 +116,7 @@ def process_args(ports):
 
 
 def show():
-  return 'freetype (-sUSE_FREETYPE=1 or -sPORTS=freetype; freetype license)'
+  return 'freetype (-sUSE_FREETYPE=1 or --use-port=freetype; freetype license)'
 
 
 ftconf_h = r'''/***************************************************************************/
diff --git a/tools/ports/giflib.py b/tools/ports/giflib.py
index adebcdffc531b..ecc554e3edd73 100644
--- a/tools/ports/giflib.py
+++ b/tools/ports/giflib.py
@@ -34,4 +34,4 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'giflib (-sUSE_GIFLIB=1 or -sPORTS=giflib; MIT license)'
+  return 'giflib (-sUSE_GIFLIB=1 or --use-port=giflib; MIT license)'
diff --git a/tools/ports/harfbuzz.py b/tools/ports/harfbuzz.py
index acab723a83940..e376d2743573c 100644
--- a/tools/ports/harfbuzz.py
+++ b/tools/ports/harfbuzz.py
@@ -152,4 +152,4 @@ def process_args(ports):
 
 
 def show():
-  return 'harfbuzz (-sUSE_HARFBUZZ=1 or -sPORTS=harfbuzz; MIT license)'
+  return 'harfbuzz (-sUSE_HARFBUZZ=1 or --use-port=harfbuzz; MIT license)'
diff --git a/tools/ports/icu.py b/tools/ports/icu.py
index 25d9119e9f001..e2c01d3e0f200 100644
--- a/tools/ports/icu.py
+++ b/tools/ports/icu.py
@@ -100,4 +100,4 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'icu (-sUSE_ICU=1 or -sPORTS=icu; Unicode License)'
+  return 'icu (-sUSE_ICU=1 or --use-port=icu; Unicode License)'
diff --git a/tools/ports/libjpeg.py b/tools/ports/libjpeg.py
index c166ce0417323..e99776c789300 100644
--- a/tools/ports/libjpeg.py
+++ b/tools/ports/libjpeg.py
@@ -38,7 +38,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'libjpeg (-sUSE_LIBJPEG=1 or -sPORTS=libjpeg; BSD license)'
+  return 'libjpeg (-sUSE_LIBJPEG=1 or --use-port=libjpeg; BSD license)'
 
 
 jconfig_h = '''/* jconfig.h.  Generated from jconfig.cfg by configure.  */
diff --git a/tools/ports/libmodplug.py b/tools/ports/libmodplug.py
index 24b363fd9c318..e6c1dc3f128e5 100644
--- a/tools/ports/libmodplug.py
+++ b/tools/ports/libmodplug.py
@@ -88,7 +88,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'libmodplug (-sUSE_MODPLUG=1 or -sPORTS=libmodplug; public domain)'
+  return 'libmodplug (-sUSE_MODPLUG=1 or --use-port=libmodplug; public domain)'
 
 
 config_h = '''/* src/config.h.  Generated from config.h.in by configure.  */
diff --git a/tools/ports/libpng.py b/tools/ports/libpng.py
index df115f5571a39..1342f81a0fb54 100644
--- a/tools/ports/libpng.py
+++ b/tools/ports/libpng.py
@@ -58,7 +58,7 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'libpng (-sUSE_LIBPNG or -sPORTS=libpng; zlib license)'
+  return 'libpng (-sUSE_LIBPNG or --use-port=libpng; zlib license)'
 
 
 pnglibconf_h = r'''/* pnglibconf.h - library build configuration */
diff --git a/tools/ports/mpg123.py b/tools/ports/mpg123.py
index 65476765d54e5..50840ec087078 100644
--- a/tools/ports/mpg123.py
+++ b/tools/ports/mpg123.py
@@ -81,7 +81,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'mpg123 (-sUSE_MPG123=1 or -sPORTS=mpg123; zlib license)'
+  return 'mpg123 (-sUSE_MPG123=1 or --use-port=mpg123; zlib license)'
 
 
 config_h = r'''/* src/config.h.  Generated from config.h.in by configure.  */
diff --git a/tools/ports/ogg.py b/tools/ports/ogg.py
index 47007ba1b7e04..f56421bc9ceff 100644
--- a/tools/ports/ogg.py
+++ b/tools/ports/ogg.py
@@ -30,7 +30,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'ogg (-sUSE_OGG=1 or -sPORTS=ogg; zlib license)'
+  return 'ogg (-sUSE_OGG=1 or --use-port=ogg; zlib license)'
 
 
 config_types_h = '''\
diff --git a/tools/ports/regal.py b/tools/ports/regal.py
index 9652cb878b265..7e04da2512818 100644
--- a/tools/ports/regal.py
+++ b/tools/ports/regal.py
@@ -126,4 +126,4 @@ def linker_setup(ports, settings):
 
 
 def show():
-  return 'regal (-sUSE_REGAL=1 or -sPORTS=regal; Regal license)'
+  return 'regal (-sUSE_REGAL=1 or --use-port=regal; Regal license)'
diff --git a/tools/ports/sdl2.py b/tools/ports/sdl2.py
index ee7f3d7c1d012..5dd039b139ff2 100644
--- a/tools/ports/sdl2.py
+++ b/tools/ports/sdl2.py
@@ -91,4 +91,4 @@ def process_args(ports):
 
 
 def show():
-  return 'SDL2 (-sUSE_SDL=2 or -sPORTS=sdl2; zlib license)'
+  return 'sdl2 (-sUSE_SDL=2 or --use-port=sdl2; zlib license)'
diff --git a/tools/ports/sdl2_gfx.py b/tools/ports/sdl2_gfx.py
index 14b8691866851..158ef0026c365 100644
--- a/tools/ports/sdl2_gfx.py
+++ b/tools/ports/sdl2_gfx.py
@@ -37,4 +37,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'SDL2_gfx (-sUSE_SDL_GFX=2 or -sPORTS=sdl2_gfx; zlib license)'
+  return 'sdl2_gfx (-sUSE_SDL_GFX=2 or --use-port=sdl2_gfx; zlib license)'
diff --git a/tools/ports/sdl2_image.py b/tools/ports/sdl2_image.py
index fad9842c2bd5f..f6029de06ad67 100644
--- a/tools/ports/sdl2_image.py
+++ b/tools/ports/sdl2_image.py
@@ -73,4 +73,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'SDL2_image (-sUSE_SDL_IMAGE=2 or -sPORTS=sdl2_image; zlib license)'
+  return 'sdl2_image (-sUSE_SDL_IMAGE=2 or --use-port=sdl2_image; zlib license)'
diff --git a/tools/ports/sdl2_mixer.py b/tools/ports/sdl2_mixer.py
index 968db1b7df27c..5906078ecf57a 100644
--- a/tools/ports/sdl2_mixer.py
+++ b/tools/ports/sdl2_mixer.py
@@ -115,4 +115,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'SDL2_mixer (-sUSE_SDL_MIXER=2 or -sPORTS=sdl2_mixer; zlib license)'
+  return 'sdl2_mixer (-sUSE_SDL_MIXER=2 or --use-port=sdl2_mixer; zlib license)'
diff --git a/tools/ports/sdl2_net.py b/tools/ports/sdl2_net.py
index 988381ee7d68c..28b7f48ad1b84 100644
--- a/tools/ports/sdl2_net.py
+++ b/tools/ports/sdl2_net.py
@@ -38,4 +38,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'SDL2_net (-sUSE_SDL_NET=2 or -sPORTS=sdl2_net; zlib license)'
+  return 'sdl2_net (-sUSE_SDL_NET=2 or --use-port=sdl2_net; zlib license)'
diff --git a/tools/ports/sdl2_ttf.py b/tools/ports/sdl2_ttf.py
index e7cffc61778d1..5c106e9acfb56 100644
--- a/tools/ports/sdl2_ttf.py
+++ b/tools/ports/sdl2_ttf.py
@@ -42,4 +42,4 @@ def process_args(ports):
 
 
 def show():
-  return 'SDL2_ttf (-sUSE_SDL_TTF=2 or -sPORTS=sdl2_ttf; zlib license)'
+  return 'sdl2_ttf (-sUSE_SDL_TTF=2 or --use-port=sdl2_ttf; zlib license)'
diff --git a/tools/ports/sqlite3.py b/tools/ports/sqlite3.py
index f22f32c1da806..efd01f319cd4c 100644
--- a/tools/ports/sqlite3.py
+++ b/tools/ports/sqlite3.py
@@ -78,4 +78,4 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'sqlite (-sUSE_SQLITE3=1 or -sPORTS=sqlite3); public domain)'
+  return 'sqlite3 (-sUSE_SQLITE3=1 or --use-port=sqlite3); public domain)'
diff --git a/tools/ports/vorbis.py b/tools/ports/vorbis.py
index d12ef97650de4..92f5b4a356fb2 100644
--- a/tools/ports/vorbis.py
+++ b/tools/ports/vorbis.py
@@ -37,4 +37,4 @@ def process_dependencies(settings):
 
 
 def show():
-  return 'vorbis (-sUSE_VORBIS or -sPORTS=vorbis; zlib license)'
+  return 'vorbis (-sUSE_VORBIS or --use-port=vorbis; zlib license)'
diff --git a/tools/ports/zlib.py b/tools/ports/zlib.py
index d614541ddbc7b..4d73d023e1673 100644
--- a/tools/ports/zlib.py
+++ b/tools/ports/zlib.py
@@ -34,7 +34,7 @@ def clear(ports, settings, shared):
 
 
 def show():
-  return 'zlib (-sUSE_ZLIB=1 or -sPORTS=zlib; zlib license)'
+  return 'zlib (-sUSE_ZLIB=1 or --use-port=zlib; zlib license)'
 
 
 zconf_h = r'''/* zconf.h -- configuration of the zlib compression library

From 177d603803dc834e7c6a4d04f3ce7b57775d9434 Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Wed, 31 Jan 2024 07:28:27 -0800
Subject: [PATCH 04/11] removed PORTS from settings.py

---
 test/test_other.py | 2 +-
 tools/settings.py  | 3 +--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/test/test_other.py b/test/test_other.py
index 5eed86adcc438..e554d5425cb13 100644
--- a/test/test_other.py
+++ b/test/test_other.py
@@ -2367,7 +2367,7 @@ def test_icu(self):
   def test_sdl2_ttf(self):
     # This is a compile-only to test to verify that sdl2-ttf (and freetype and harfbuzz) are buildable.
     self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['-sUSE_SDL=2', '-sUSE_SDL_TTF=2'], output_filename='a.out.js')
-    self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['--use-port=sdl2_ttf'], output_filename='a.out.js')
+    self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['--use-port=sdl2', '--use-port=sdl2_ttf'], output_filename='a.out.js')
 
   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/settings.py b/tools/settings.py
index 75668a7dd7d42..e99e020c2a6a9 100644
--- a/tools/settings.py
+++ b/tools/settings.py
@@ -51,8 +51,7 @@
     'USE_FREETYPE',
     'SDL2_MIXER_FORMATS',
     'SDL2_IMAGE_FORMATS',
-    'USE_SQLITE3',
-    'PORTS'
+    'USE_SQLITE3'
 }
 
 # Subset of settings that apply only when generating JS

From 7d4383119cd3714f060722cb7630c4eefa435037 Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Wed, 31 Jan 2024 08:02:24 -0800
Subject: [PATCH 05/11] reverted comma

---
 tools/settings.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/settings.py b/tools/settings.py
index e99e020c2a6a9..67d01f2b98859 100644
--- a/tools/settings.py
+++ b/tools/settings.py
@@ -51,7 +51,7 @@
     'USE_FREETYPE',
     'SDL2_MIXER_FORMATS',
     'SDL2_IMAGE_FORMATS',
-    'USE_SQLITE3'
+    'USE_SQLITE3',
 }
 
 # Subset of settings that apply only when generating JS

From 5d0afbb3e4b0f261f0e25abd925f8db4b39d0d8e Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Wed, 31 Jan 2024 11:31:08 -0800
Subject: [PATCH 06/11] changes from code review

---
 ChangeLog.md                              |  3 +++
 site/source/docs/tools_reference/emcc.rst |  2 +-
 src/settings_internal.js                  |  4 ----
 tools/ports/__init__.py                   | 11 +++++++----
 4 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/ChangeLog.md b/ChangeLog.md
index 67af381c95b35..6a1a72835690c 100644
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -20,6 +20,9 @@ See docs/process.md for more on how version tagging works.
 
 3.1.54 (in development)
 -----------------------
+- Added `--use-port` option to `emcc`. You can use `--show-ports` to get the
+  list of available ports that can be used with this new option.
+ 
 
 3.1.53 - 01/29/24
 -----------------
diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst
index 010c5dcca9604..eefbcb834c712 100644
--- a/site/source/docs/tools_reference/emcc.rst
+++ b/site/source/docs/tools_reference/emcc.rst
@@ -460,7 +460,7 @@ Options that are modified or new in *emcc* are listed below:
 ``--use-port=<port>``
   [link]
   Use the specified port. If you need to use more than one port you can use this
-  argument multiple times. For example: ``--user-port=sdl2 --user-port=bzip2``.
+  argument multiple times. For example: ``--use-port=sdl2 --use-port=bzip2``.
   To get the list of available ports, use ``--show-ports``.
 
 .. _emcc-clear-ports:
diff --git a/src/settings_internal.js b/src/settings_internal.js
index 678b6ee0fae72..36a1887540a84 100644
--- a/src/settings_internal.js
+++ b/src/settings_internal.js
@@ -273,7 +273,3 @@ var BULK_MEMORY = false;
 var MINIFY_WHITESPACE = true;
 
 var ASYNCIFY_IMPORTS_EXCEPT_JS_LIBS = [];
-
-// Specify which ports to use. This is set via the --use-port command line
-// option
-var PORTS = [];
diff --git a/tools/ports/__init__.py b/tools/ports/__init__.py
index f8fd156e6f011..637ccda8bc4a4 100644
--- a/tools/ports/__init__.py
+++ b/tools/ports/__init__.py
@@ -22,6 +22,8 @@
 
 ports_by_name = {}
 
+ports_needed = set()
+
 # Variant builds that we want to support for certain ports
 # {variant_name: (port_name, extra_settings)}
 port_variants = {}
@@ -40,10 +42,10 @@ def load_port(name):
   for a in expected_attrs:
     assert hasattr(port, a), 'port %s is missing %s' % (port, a)
   if not hasattr(port, 'needed'):
-    port.needed = lambda s: name in s.PORTS
+    port.needed = lambda s: name in ports_needed
   else:
     needed = port.needed
-    port.needed = lambda s: needed(s) or name in s.PORTS
+    port.needed = lambda s: needed(s) or name in ports_needed
   if not hasattr(port, 'process_dependencies'):
     port.process_dependencies = lambda x: 0
   if not hasattr(port, 'linker_setup'):
@@ -373,8 +375,9 @@ def add_deps(node):
 
 def handle_use_port_arg(settings, name):
   if name not in ports_by_name:
-    utils.exit_with_error(f'Invalid port name: {name} used with --user-port')
-  settings.PORTS.append(name)
+    utils.exit_with_error(f'Invalid port name: {name} used with --use-port')
+  ports_needed.add(name)
+  print(f'ports_needed={ports_needed}')
 
 
 def get_needed_ports(settings):

From ba2a1ff3e44c37b3dd65030a52a5de66f688f41f Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Wed, 31 Jan 2024 11:36:25 -0800
Subject: [PATCH 07/11] removed print statement

---
 tools/ports/__init__.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/tools/ports/__init__.py b/tools/ports/__init__.py
index 637ccda8bc4a4..71df3d0c2c6c4 100644
--- a/tools/ports/__init__.py
+++ b/tools/ports/__init__.py
@@ -377,7 +377,6 @@ def handle_use_port_arg(settings, name):
   if name not in ports_by_name:
     utils.exit_with_error(f'Invalid port name: {name} used with --use-port')
   ports_needed.add(name)
-  print(f'ports_needed={ports_needed}')
 
 
 def get_needed_ports(settings):

From b88e332a97085af932b9d743b34f4b88b9a9fb8a Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Wed, 31 Jan 2024 11:52:12 -0800
Subject: [PATCH 08/11] brute force documentation update

---
 docs/emcc.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/emcc.txt b/docs/emcc.txt
index 25902a2453a87..60d42f930e71a 100644
--- a/docs/emcc.txt
+++ b/docs/emcc.txt
@@ -466,6 +466,12 @@ Options that are modified or new in *emcc* are listed below:
    By default this will also clear any download ports since the ports
    directory is usually within the cache directory.
 
+"--use-port=<port>"
+   [link] Use the specified port. If you need to use more than one
+   port you can use this argument multiple times. For example: "--use-
+   port=sdl2 --use-port=bzip2". To get the list of available ports,
+   use "--show-ports".
+
 "--clear-ports"
    [general] Manually clears the local copies of ports from the
    Emscripten Ports repos (sdl2, etc.). This also clears the cache, to

From aeb2d0a61583e33d5bb23a3fdcc4c1d6519f2f6d Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Wed, 31 Jan 2024 12:10:55 -0800
Subject: [PATCH 09/11] use compile+link

---
 docs/emcc.txt                             | 8 ++++----
 site/source/docs/tools_reference/emcc.rst | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/emcc.txt b/docs/emcc.txt
index 60d42f930e71a..1d2c7900000fa 100644
--- a/docs/emcc.txt
+++ b/docs/emcc.txt
@@ -467,10 +467,10 @@ Options that are modified or new in *emcc* are listed below:
    directory is usually within the cache directory.
 
 "--use-port=<port>"
-   [link] Use the specified port. If you need to use more than one
-   port you can use this argument multiple times. For example: "--use-
-   port=sdl2 --use-port=bzip2". To get the list of available ports,
-   use "--show-ports".
+   [compile+link] Use the specified port. If you need to use more than
+   one port you can use this argument multiple times. For example: "--
+   use-port=sdl2 --use-port=bzip2". 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 eefbcb834c712..7885ed3cbe6b0 100644
--- a/site/source/docs/tools_reference/emcc.rst
+++ b/site/source/docs/tools_reference/emcc.rst
@@ -458,7 +458,7 @@ Options that are modified or new in *emcc* are listed below:
 .. _emcc-use-port:
 
 ``--use-port=<port>``
-  [link]
+  [compile+link]
   Use the specified port. If you need to use more than one port you can use this
   argument multiple times. For example: ``--use-port=sdl2 --use-port=bzip2``.
   To get the list of available ports, use ``--show-ports``.

From 9facf3879b86c08802e7d2100d0915513936b20d Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Thu, 1 Feb 2024 04:55:33 -0800
Subject: [PATCH 10/11] fixed sanity checks

---
 test/test_sanity.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/test/test_sanity.py b/test/test_sanity.py
index 41465a59f5030..4f26ad520bb6a 100644
--- a/test/test_sanity.py
+++ b/test/test_sanity.py
@@ -529,9 +529,9 @@ def test_emcc_ports(self):
     # listing ports
     out = self.do([EMCC, '--show-ports'])
     self.assertContained('Available ports:', out)
-    self.assertContained('SDL2', out)
-    self.assertContained('SDL2_image', out)
-    self.assertContained('SDL2_net', out)
+    self.assertContained('sdl2', out)
+    self.assertContained('sdl2_image', out)
+    self.assertContained('sdl2_net', out)
 
     # using ports
     RETRIEVING_MESSAGE = 'retrieving port'

From 0344a99f7d4a95a05b6d7520c44f4589324f0549 Mon Sep 17 00:00:00 2001
From: Yan Pujante <yan@pongasoft.com>
Date: Thu, 1 Feb 2024 09:34:48 -0800
Subject: [PATCH 11/11] documentation changes

---
 ChangeLog.md                                     |  6 ++++--
 site/source/docs/compiling/Building-Projects.rst | 13 +++++++++----
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/ChangeLog.md b/ChangeLog.md
index 6a1a72835690c..33f14669d0149 100644
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -20,8 +20,10 @@ See docs/process.md for more on how version tagging works.
 
 3.1.54 (in development)
 -----------------------
-- Added `--use-port` option to `emcc`. You can use `--show-ports` to get the
-  list of available ports that can be used with this new option.
+- Added `--use-port` option to `emcc`.  This option allows ports to be enabled 
+  by name and is designed to replace all existing `-sUSE_XXX` settings for 
+  ports. You can use `--show-ports` to get the list of available ports that 
+  can be used with this new option. (#21214)
  
 
 3.1.53 - 01/29/24
diff --git a/site/source/docs/compiling/Building-Projects.rst b/site/source/docs/compiling/Building-Projects.rst
index 18ec988297d1d..fd8b798353a70 100644
--- a/site/source/docs/compiling/Building-Projects.rst
+++ b/site/source/docs/compiling/Building-Projects.rst
@@ -215,17 +215,19 @@ For example, consider the case where a project "project" uses a library "libstuf
 Emscripten Ports
 ================
 
-Emscripten Ports is a collection of useful libraries, ported to Emscripten. They reside `on GitHub <https://github.com/emscripten-ports>`_, and have integration support in *emcc*. When you request that a port be used, emcc will fetch it from the remote server, set it up and build it locally, then link it with your project, add necessary include to your build commands, etc. For example, SDL2 is in ports, and you can request that it be used with ``-sUSE_SDL=2``. For example,
+Emscripten Ports is a collection of useful libraries, ported to Emscripten. They reside `on GitHub <https://github.com/emscripten-ports>`_, and have integration support in *emcc*. When you request that a port be used, emcc will fetch it from the remote server, set it up and build it locally, then link it with your project, add necessary include to your build commands, etc. For example, SDL2 is in ports, and you can request that it be used with ``--use-port=sdl2``. For example,
 
 .. code-block:: bash
 
-  emcc test/sdl2glshader.c -sUSE_SDL=2 -sLEGACY_GL_EMULATION -o sdl2.html
+  emcc test/browser/test_sdl2_glshader.c --use-port=sdl2 -sLEGACY_GL_EMULATION -o sdl2.html
 
 You should see some notifications about SDL2 being used, and built if it wasn't previously. You can then view ``sdl2.html`` in your browser.
 
-.. note:: *SDL_image* has also been added to ports, use it with ``-sUSE_SDL_IMAGE=2``. To see a list of all available ports, run ``emcc --show-ports``. For SDL2_image to be useful, you generally need to specify the image formats you are planning on using with e.g. ``-sSDL2_IMAGE_FORMATS='["bmp","png","xpm"]'`` (note: jpg support is not available yet as of Jun 22 2018 - libjpg needs to be added to emscripten-ports). This will also ensure that ``IMG_Init`` works properly when you specify those formats. Alternatively, you can use ``emcc --use-preload-plugins`` and ``--preload-file`` your images, so the browser codecs decode them (see :ref:`preloading-files`). A code path in the SDL2_image port will load through :c:func:`emscripten_get_preloaded_image_data`, but then your calls to ``IMG_Init`` with those image formats will fail (as while the images will work through preloading, IMG_Init reports no support for those formats, as it doesn't have support compiled in - in other words, IMG_Init does not report support for formats that only work through preloading).```
+To see a list of all available ports, run ``emcc --show-ports``.
 
-.. note:: *SDL_net* has also been added to ports, use it with ``-sUSE_SDL_NET=2``. To see a list of all available ports, run ``emcc --show-ports``.
+.. note:: *SDL_image* has also been added to ports, use it with ``--use-port=sdl2_image``. For ``sdl2_image`` to be useful, you generally need to specify the image formats you are planning on using with e.g. ``-sSDL2_IMAGE_FORMATS='["bmp","png","xpm","jpg"]'``. This will also ensure that ``IMG_Init`` works properly when you specify those formats. Alternatively, you can use ``emcc --use-preload-plugins`` and ``--preload-file`` your images, so the browser codecs decode them (see :ref:`preloading-files`). A code path in the ``sdl2_image`` port will load through :c:func:`emscripten_get_preloaded_image_data`, but then your calls to ``IMG_Init`` with those image formats will fail (as while the images will work through preloading, IMG_Init reports no support for those formats, as it doesn't have support compiled in - in other words, IMG_Init does not report support for formats that only work through preloading).```
+
+.. note:: *SDL_net* has also been added to ports, use it with ``--use-port=sdl2_net``.
 
 .. note:: Emscripten also has support for older SDL1, which is built-in. If you do not specify SDL2 as in the command above, then SDL1 is linked in and the SDL1 include paths are used. SDL1 has support for *sdl-config*, which is present in `system/bin <https://github.com/emscripten-core/emscripten/blob/main/system/bin/sdl-config>`_. Using the native *sdl-config* may result in compilation or missing-symbol errors. You will need to modify the build system to look for files in **emscripten/system** or **emscripten/system/bin** in order to use the Emscripten *sdl-config*.
 
@@ -236,6 +238,9 @@ You should see some notifications about SDL2 being used, and built if it wasn't
     it's better to use the ports version as it is what is tested and known to
     work.
 
+.. note:: Since emscripten 3.1.54, ``--use-port`` is the preferred syntax to use a port in your project. The legacy syntax (for example ``-sUSE_SDL2``, ``-sUSE_SDL_IMAGE=2``) remains available.
+
+
 Adding more ports
 -----------------