[ports] Enable use of "::" to escape options separator (#21710)

Author: ypujante

ChangeLog.md

@@ -44,6 +44,10 @@ See docs/process.md for more on how version tagging works.
 - TypeScript definitions for Wasm exports, runtime exports, and embind bindings
   can now be generated with `--emit-tsd`. The option `--embind-emit-tsd` has been
   deprecated, use `--emit-tsd` instead.
+- ports changes:
+  - Fixed transitive link dependencies (#21602)
+  - Enable use of options in ports dependencies (#21629)
+  - Enable use of `::` to escape option separator (#21710)
 
 3.1.56 - 03/14/24
 -----------------

test/other/ports/external.py

@@ -13,13 +13,15 @@
 OPTIONS = {
   'value1': 'Value for define TEST_VALUE_1',
   'value2': 'Value for define TEST_VALUE_2',
-  'dependency': 'A dependency'
+  'value3': 'String value',
+  'dependency': 'A dependency',
 }
 
 # user options (from --use-port)
 opts: Dict[str, Optional[str]] = {
   'value1': None,
   'value2': None,
+  'value3': "v3",
   'dependency': None
 }
 
@@ -57,6 +59,7 @@ def process_args(ports):
     args.append(f'-DTEST_VALUE_2={opts["value2"]}')
   if opts['dependency']:
     args.append(f'-DTEST_DEPENDENCY_{opts["dependency"].upper()}')
+  args.append(f'-DTEST_VALUE_3="{opts["value3"]}"')
   return args
 
 

test/other/test_external_ports.c

@@ -24,7 +24,7 @@
 
 int main() {
   assert(my_port_fn(99) == 99); // check that we can call a function from my_port.h
-  printf("value1=%d&value2=%d\n", TEST_VALUE_1, TEST_VALUE_2);
+  printf("value1=%d&value2=%d&value3=%s\n", TEST_VALUE_1, TEST_VALUE_2, TEST_VALUE_3);
 
   // external port declares deps = ['sdl2_image:formats=jpg'] as a dependency
   // this makes sure that the dependency + options gets processed properly

test/test_other.py

@@ -2463,11 +2463,13 @@ def test_external_ports(self):
       self.skipTest("test doesn't work with frozen cache")
     external_port_path = test_file("other/ports/external.py")
     # testing no option
-    self.do_runf('other/test_external_ports.c', 'value1=0&value2=0\n', emcc_args=[f'--use-port={external_port_path}'])
+    self.do_runf('other/test_external_ports.c', 'value1=0&value2=0&value3=v3\n', emcc_args=[f'--use-port={external_port_path}'])
     # testing 1 option
-    self.do_runf('other/test_external_ports.c', 'value1=12&value2=0\n', emcc_args=[f'--use-port={external_port_path}:value1=12'])
+    self.do_runf('other/test_external_ports.c', 'value1=12&value2=0&value3=v3\n', emcc_args=[f'--use-port={external_port_path}:value1=12'])
     # testing 2 options
-    self.do_runf('other/test_external_ports.c', 'value1=12&value2=36\n', emcc_args=[f'--use-port={external_port_path}:value1=12:value2=36'])
+    self.do_runf('other/test_external_ports.c', 'value1=12&value2=36&value3=v3\n', emcc_args=[f'--use-port={external_port_path}:value1=12:value2=36'])
+    # testing ':' escape
+    self.do_runf('other/test_external_ports.c', 'value1=12&value2=36&value3=v:3\n', emcc_args=[f'--use-port={external_port_path}:value1=12:value3=v::3:value2=36'])
     # testing dependency
     self.do_runf('other/test_external_ports.c', 'mpg123=45\n', emcc_args=[f'--use-port={external_port_path}:dependency=mpg123'])
     # testing invalid dependency
@@ -2481,6 +2483,7 @@ def test_external_ports(self):
 Options:
 * value1: Value for define TEST_VALUE_1
 * value2: Value for define TEST_VALUE_2
+* value3: String value
 * dependency: A dependency
 More info: https://emscripten.org
 ''', stdout)

tools/ports/__init__.py

@@ -437,7 +437,8 @@ def handle_port_options(name, options, error_handler):
     error_handler(f'no options available for port `{name}`')
   else:
     options_dict = {}
-    for name_value in options.split(':'):
+    for name_value in options.replace('::', '\0').split(':'):
+      name_value = name_value.replace('\0', ':')
       nv = name_value.split('=', 1)
       if len(nv) != 2:
         error_handler(f'`{name_value}` is missing a value')

tools/ports/contrib/README.md

@@ -37,6 +37,9 @@ calls the handler function with these (valid) options. If you detect an error
 with a value, you should use the error handler provided to report the 
 failure.
 
+Since emscripten uses `:` as the option separator, `::` is the escape syntax 
+(ex: `--use-port=name:opt1=abc::def`)
+
 > ### Note
 > If the options influence the way the library produced by the port is built, 
 > you must ensure that the library name accounts for these options. Check