Add --use-port option (#21214)

Author: ypujante

ChangeLog.md

@@ -20,6 +20,11 @@ See docs/process.md for more on how version tagging works.
 
 3.1.54 (in development)
 -----------------------
+- 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
 -----------------

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>"
+   [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
    Emscripten Ports repos (sdl2, etc.). This also clears the cache, to

emcc.py

@@ -1405,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

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
 -----------------
 

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>``
+  [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``.
+
 .. _emcc-clear-ports:
 
 ``--clear-ports``

site/source/docs/tools_reference/settings_reference.rst

@@ -1849,6 +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: --use-port=sdl2
 
 .. note:: Applicable during both linking and compilation
 
@@ -1894,6 +1895,7 @@ USE_ICU
 =======
 
 1 = use icu from emscripten-ports
+Alternate syntax: --use-port=icu
 
 .. note:: Applicable during both linking and compilation
 
@@ -1903,6 +1905,7 @@ USE_ZLIB
 ========
 
 1 = use zlib from emscripten-ports
+Alternate syntax: --use-port=zlib
 
 .. note:: Applicable during both linking and compilation
 
@@ -1912,6 +1915,7 @@ USE_BZIP2
 =========
 
 1 = use bzip2 from emscripten-ports
+Alternate syntax: --use-port=bzip2
 
 .. note:: Applicable during both linking and compilation
 
@@ -1921,6 +1925,7 @@ USE_GIFLIB
 ==========
 
 1 = use giflib from emscripten-ports
+Alternate syntax: --use-port=giflib
 
 .. note:: Applicable during both linking and compilation
 
@@ -1930,6 +1935,7 @@ USE_LIBJPEG
 ===========
 
 1 = use libjpeg from emscripten-ports
+Alternate syntax: --use-port=libjpeg
 
 .. note:: Applicable during both linking and compilation
 
@@ -1939,6 +1945,7 @@ USE_LIBPNG
 ==========
 
 1 = use libpng from emscripten-ports
+Alternate syntax: --use-port=libpng
 
 .. note:: Applicable during both linking and compilation
 
@@ -1948,6 +1955,7 @@ USE_REGAL
 =========
 
 1 = use Regal from emscripten-ports
+Alternate syntax: --use-port=regal
 
 .. note:: Applicable during both linking and compilation
 
@@ -1957,6 +1965,7 @@ USE_BOOST_HEADERS
 =================
 
 1 = use Boost headers from emscripten-ports
+Alternate syntax: --use-port=boost_headers
 
 .. note:: Applicable during both linking and compilation
 
@@ -1966,6 +1975,7 @@ USE_BULLET
 ==========
 
 1 = use bullet from emscripten-ports
+Alternate syntax: --use-port=bullet
 
 .. note:: Applicable during both linking and compilation
 
@@ -1975,6 +1985,7 @@ USE_VORBIS
 ==========
 
 1 = use vorbis from emscripten-ports
+Alternate syntax: --use-port=vorbis
 
 .. note:: Applicable during both linking and compilation
 
@@ -1984,6 +1995,7 @@ USE_OGG
 =======
 
 1 = use ogg from emscripten-ports
+Alternate syntax: --use-port=ogg
 
 .. note:: Applicable during both linking and compilation
 
@@ -1993,6 +2005,7 @@ USE_MPG123
 ==========
 
 1 = use mpg123 from emscripten-ports
+Alternate syntax: --use-port=mpg123
 
 .. note:: Applicable during both linking and compilation
 
@@ -2002,6 +2015,7 @@ USE_FREETYPE
 ============
 
 1 = use freetype from emscripten-ports
+Alternate syntax: --use-port=freetype
 
 .. note:: Applicable during both linking and compilation
 
@@ -2021,6 +2035,7 @@ USE_HARFBUZZ
 ============
 
 1 = use harfbuzz from harfbuzz upstream
+Alternate syntax: --use-port=harfbuzz
 
 .. note:: Applicable during both linking and compilation
 
@@ -2030,6 +2045,7 @@ USE_COCOS2D
 ===========
 
 3 = use cocos2d v3 from emscripten-ports
+Alternate syntax: --use-port=cocos2d
 
 .. note:: Applicable during both linking and compilation
 
@@ -2039,6 +2055,7 @@ USE_MODPLUG
 ===========
 
 1 = use libmodplug from emscripten-ports
+Alternate syntax: --use-port=libmodplug
 
 .. note:: Applicable during both linking and compilation
 
@@ -2063,6 +2080,7 @@ USE_SQLITE3
 ===========
 
 1 = use sqlite3 from emscripten-ports
+Alternate syntax: --use-port=sqlite3
 
 .. note:: Applicable during both linking and compilation
 

src/settings.js

@@ -1455,6 +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: --use-port=sdl2
 // [compile+link]
 var USE_SDL = 0;
 
@@ -1475,54 +1476,67 @@ var USE_SDL_TTF = 1;
 var USE_SDL_NET = 1;
 
 // 1 = use icu from emscripten-ports
+// Alternate syntax: --use-port=icu
 // [compile+link]
 var USE_ICU = false;
 
 // 1 = use zlib from emscripten-ports
+// Alternate syntax: --use-port=zlib
 // [compile+link]
 var USE_ZLIB = false;
 
 // 1 = use bzip2 from emscripten-ports
+// Alternate syntax: --use-port=bzip2
 // [compile+link]
 var USE_BZIP2 = false;
 
 // 1 = use giflib from emscripten-ports
+// Alternate syntax: --use-port=giflib
 // [compile+link]
 var USE_GIFLIB = false;
 
 // 1 = use libjpeg from emscripten-ports
+// Alternate syntax: --use-port=libjpeg
 // [compile+link]
 var USE_LIBJPEG = false;
 
 // 1 = use libpng from emscripten-ports
+// Alternate syntax: --use-port=libpng
 // [compile+link]
 var USE_LIBPNG = false;
 
 // 1 = use Regal from emscripten-ports
+// Alternate syntax: --use-port=regal
 // [compile+link]
 var USE_REGAL = false;
 
 // 1 = use Boost headers from emscripten-ports
+// Alternate syntax: --use-port=boost_headers
 // [compile+link]
 var USE_BOOST_HEADERS = false;
 
 // 1 = use bullet from emscripten-ports
+// Alternate syntax: --use-port=bullet
 // [compile+link]
 var USE_BULLET = false;
 
 // 1 = use vorbis from emscripten-ports
+// Alternate syntax: --use-port=vorbis
 // [compile+link]
 var USE_VORBIS = false;
 
 // 1 = use ogg from emscripten-ports
+// Alternate syntax: --use-port=ogg
 // [compile+link]
 var USE_OGG = false;
 
 // 1 = use mpg123 from emscripten-ports
+// Alternate syntax: --use-port=mpg123
 // [compile+link]
 var USE_MPG123 = false;
 
 // 1 = use freetype from emscripten-ports
+// Alternate syntax: --use-port=freetype
 // [compile+link]
 var USE_FREETYPE = false;
 
@@ -1532,14 +1546,17 @@ var USE_FREETYPE = false;
 var USE_SDL_MIXER = 1;
 
 // 1 = use harfbuzz from harfbuzz upstream
+// Alternate syntax: --use-port=harfbuzz
 // [compile+link]
 var USE_HARFBUZZ = false;
 
 // 3 = use cocos2d v3 from emscripten-ports
+// Alternate syntax: --use-port=cocos2d
 // [compile+link]
 var USE_COCOS2D = 0;
 
 // 1 = use libmodplug from emscripten-ports
+// Alternate syntax: --use-port=libmodplug
 // [compile+link]
 var USE_MODPLUG = false;
 
@@ -1553,6 +1570,7 @@ var SDL2_IMAGE_FORMATS = [];
 var SDL2_MIXER_FORMATS = ["ogg"];
 
 // 1 = use sqlite3 from emscripten-ports
+// Alternate syntax: --use-port=sqlite3
 // [compile+link]
 var USE_SQLITE3 = false;