Add --use-port option (Contrib ports part 1)

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

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

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/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: ``--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;
 

test/test_other.py

@@ -2259,20 +2259,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'), ['--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', '--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', '--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', '--use-port=libpng'])
 
   @node_pthreads
   def test_libpng_with_pthreads(self):
@@ -2293,23 +2298,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', '--use-port=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', '--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=['--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=['--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=['--use-port=bzip2', '-Wno-pointer-sign'])
 
   @with_both_sjlj
   def test_freetype(self):
@@ -2337,6 +2353,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=['--use-port=freetype', '--embed-file', 'LiberationSansBold.ttf'])
 
   def test_freetype_with_pthreads(self):
     # Verify that freetype supports compilation requiring pthreads
@@ -2349,6 +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', '--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
@@ -11420,6 +11439,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', '--use-port=boost_headers'])
 
   def test_setjmp_em_asm(self):
     create_file('src.c', '''