Use modern -s command line lists in more places. NFC (emscripten-core#15516)

sbc100 · web-flow · commit bb615a9a0e45 · 2021-11-15T15:17:03.000-08:00
We want to avoid pointing folks to the older, more error prone and
complex format.
diff --git a/docs/emcc.txt b/docs/emcc.txt
@@ -104,11 +104,17 @@ Options that are modified or new in *emcc* are listed below:
 
    Note:
 
-     Lists can be specified without or without quotes around each
-     element and with or without brackets around the list.  For
-     example all the following are equivelent:
+     Lists can be specified as comma separated strings:
 
         -s EXPORTED_FUNCTIONS=foo,bar
+
+   Note:
+
+     We also support older list formats that involve more quoting.
+     Lists can be specified with or without quotes around each element
+     and with or without brackets around the list.  For example, all
+     the following are equivalent:
+
         -s EXPORTED_FUNCTIONS="foo","bar"
         -s EXPORTED_FUNCTIONS=["foo","bar"]
         -s EXPORTED_FUNCTIONS=[foo,bar]
diff --git a/site/source/docs/api_reference/advanced-apis.rst b/site/source/docs/api_reference/advanced-apis.rst
@@ -30,7 +30,7 @@ While it is possible to edit **settings.js** manually, this is *highly discourag
 
 The small number of options that developers may have cause to change should be modified when the *emcc* tool is invoked. For example, ``EXPORTED_FUNCTIONS``: ::
 
-  ./emcc tests/hello_function.cpp -o function.html -s EXPORTED_FUNCTIONS="['_int_sqrt']"
+  ./emcc tests/hello_function.cpp -o function.html -s EXPORTED_FUNCTIONS=_int_sqrt
 
 
 preamble.js
diff --git a/site/source/docs/api_reference/preamble.js.rst b/site/source/docs/api_reference/preamble.js.rst
@@ -10,7 +10,7 @@ We call this "``preamble.js``" because Emscripten's output JS, at a high level,
 
 The preamble code is included in the output JS, which is then optimized all together by the compiler, together with any ``--pre-js`` and ``--post-js`` files you added and code from any JavaScript libraries (``--js-library``). That means that you can call methods from the preamble directly, and the compiler will see that you need them, and not remove them as being unused.
 
-If you want to call preamble methods from somewhere the compiler can't see, like another script tag on the HTML, you need to **export** them. To do so, add them to ``EXPORTED_RUNTIME_METHODS`` (for example, ``-s 'EXPORTED_RUNTIME_METHODS=["ccall", "cwrap"]'`` will export ``ccall`` and ``cwrap``). Once exported, you can access them on the ``Module`` object (as ``Module.ccall``, for example).
+If you want to call preamble methods from somewhere the compiler can't see, like another script tag on the HTML, you need to **export** them. To do so, add them to ``EXPORTED_RUNTIME_METHODS`` (for example, ``-s EXPORTED_RUNTIME_METHODS=ccall,cwrap`` will export ``ccall`` and ``cwrap``). Once exported, you can access them on the ``Module`` object (as ``Module.ccall``, for example).
 
 .. note:: If you try to use ``Module.ccall`` or another runtime method without exporting it, you will get an error. In a build with ``-s ASSERTIONS=1``, the compiler emits code to show you a useful error message, which will explain that you need to export it. In general, if you see something odd, it's useful to build with assertions.
 
@@ -51,7 +51,7 @@ Calling compiled C functions from JavaScript
 
       .. code-block:: none
 
-        -s EXPORTED_FUNCTIONS="['_main', '_myfunc']"
+        -s EXPORTED_FUNCTIONS=_main,_myfunc"
 
       (Note that we also export ``main`` - if we didn't, the compiler would assume we don't need it.) Exported functions can then be called as normal:
 
@@ -104,7 +104,7 @@ Calling compiled C functions from JavaScript
 
       .. code-block:: none
 
-        -s EXPORTED_FUNCTIONS="['_main', '_myfunc']"
+        -s EXPORTED_FUNCTIONS=_main,_myfunc
 
       Exported functions can be called as normal:
 
diff --git a/site/source/docs/getting_started/FAQ.rst b/site/source/docs/getting_started/FAQ.rst
@@ -415,46 +415,31 @@ with
 Why do I get a ``NameError`` or ``a problem occurred in evaluating content after a "-s"`` when I use a ``-s`` option?
 =====================================================================================================================
 
-That may occur when running something like
+That may occur when using the old list syntax for ``-s`` settings:
 
 ::
 
   # this fails on most Linuxes
-  emcc a.c -s EXPORTED_RUNTIME_METHODS=['addOnPostRun']
+  emcc a.c -s EXPORTED_RUNTIME_METHODS=['foo']
 
   # this fails on macOS
-  emcc a.c -s EXPORTED_RUNTIME_METHODS="['addOnPostRun']"
+  emcc a.c -s EXPORTED_RUNTIME_METHODS="['foo']"
 
-You may need to quote things like this:
+A new, simpler way to specify these lists is to simply use
+comma separated lists:
 
 ::
 
-  # this works in the shell on most Linuxes and on macOS
-  emcc a.c -s "EXPORTED_RUNTIME_METHODS=['addOnPostRun']"
+  emcc a.c -s EXPORTED_RUNTIME_METHODS=foo,bar
 
-  # or you may need something like this in a Makefile
-  emcc a.c -s EXPORTED_RUNTIME_METHODS=\"['addOnPostRun']\"
-
-The proper syntax depends on the OS and shell you are in, and if you are writing
-in a Makefile, etc. Things like spaces may also matter in some shells, for
-example you may need to avoid empty spaces between list items:
-
-::
-
-  # this works in the shell on most Linuxes and on macOS
-  emcc a.c -s "EXPORTED_RUNTIME_METHODS=['foo','bar']"
-
-(note there is no space after the ``,``).
-
-For simplicity, you may want to use a **response file**, that is,
+It is also possible to use a **response file**, that is,
 
 ::
 
-  # this works in the shell on most Linuxes and on macOS
-  emcc a.c -s "EXPORTED_RUNTIME_METHODS=@extra.txt"
+  emcc a.c -s EXPORTED_RUNTIME_METHODS=@extra.txt
 
-and then ``extra.txt`` can be a plain file that contains ``['foo','bar']``. This
-avoids any issues with the shell environment parsing the string.
+with ``extra.txt`` being a plain text file that contains ``foo`` and ``bar`` on
+seperate lines.
 
 How do I specify ``-s`` options in a CMake project?
 ===================================================
@@ -475,7 +460,7 @@ notation, that is, without a space:
   # same as before but no space after -s
   set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -sUSE_SDL=2")
   # example of target_link_options with a list of names
-  target_link_options(example PRIVATE "-sEXPORTED_FUNCTIONS=[_main]")
+  target_link_options(example PRIVATE "-sEXPORTED_FUNCTIONS=_main")
 
 Note also that ``_main`` does not need to be quoted, even though it's a string
 name (``emcc`` knows that the argument to ``EXPORTED_FUNCTIONS`` is a list of
diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst
@@ -96,11 +96,16 @@ Options that are modified or new in *emcc* are listed below:
 
   .. note:: If no value is specifed it will default to ``1``.
 
-  .. note:: Lists can be specified without or without quotes around each element and with or without brackets around the list.  For example all the following are equivelent:
+  .. note:: Lists can be specified as comma separated strings:
 
     ::
 
       -s EXPORTED_FUNCTIONS=foo,bar
+
+  .. note:: We also support older list formats that involve more quoting.  Lists can be specified with or without quotes around each element and with or without brackets around the list.  For example, all the following are equivalent:
+
+    ::
+
       -s EXPORTED_FUNCTIONS="foo","bar"
       -s EXPORTED_FUNCTIONS=["foo","bar"]
       -s EXPORTED_FUNCTIONS=[foo,bar]
diff --git a/tests/test_interactive.py b/tests/test_interactive.py
@@ -26,7 +26,7 @@ def setUpClass(cls):
     print()
 
   def test_html5_fullscreen(self):
-    self.btest(test_file('test_html5_fullscreen.c'), expected='0', args=['-s', 'DISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR', '-s', 'EXPORTED_FUNCTIONS=["_requestFullscreen","_enterSoftFullscreen","_main"]', '--shell-file', test_file('test_html5_fullscreen.html')])
+    self.btest(test_file('test_html5_fullscreen.c'), expected='0', args=['-s', 'DISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR', '-s', 'EXPORTED_FUNCTIONS=_requestFullscreen,_enterSoftFullscreen,_main', '--shell-file', test_file('test_html5_fullscreen.html')])
 
   def test_html5_emscripten_exit_with_escape(self):
     self.btest('test_html5_emscripten_exit_fullscreen.c', expected='1', args=['-DEXIT_WITH_F'])
@@ -63,7 +63,7 @@ def test_sdl_audio(self):
     open(os.path.join(self.get_dir(), 'bad.ogg'), 'w').write('I claim to be audio, but am lying')
 
     # use closure to check for a possible bug with closure minifying away newer Audio() attributes
-    self.compile_btest(['-O2', '--closure=1', '--minify=0', test_file('sdl_audio.c'), '--preload-file', 'sound.ogg', '--preload-file', 'sound2.wav', '--embed-file', 'the_entertainer.ogg', '--preload-file', 'noise.ogg', '--preload-file', 'bad.ogg', '-o', 'page.html', '-s', 'EXPORTED_FUNCTIONS=["_main", "_play", "_play2"]'])
+    self.compile_btest(['-O2', '--closure=1', '--minify=0', test_file('sdl_audio.c'), '--preload-file', 'sound.ogg', '--preload-file', 'sound2.wav', '--embed-file', 'the_entertainer.ogg', '--preload-file', 'noise.ogg', '--preload-file', 'bad.ogg', '-o', 'page.html', '-s', 'EXPORTED_FUNCTIONS=_main,_play,_play2'])
     self.run_browser('page.html', '', '/report_result?1')
 
     # print('SDL2')
@@ -72,7 +72,7 @@ def test_sdl_audio(self):
     #        depended on fragile SDL1/SDL2 mixing, which stopped working with
     #        7a5744d754e00bec4422405a1a94f60b8e53c8fc (which just uncovered
     #        the existing problem)
-    # self.run_process([EMCC, '-O1', '--closure', '0', '--minify=0', os.path.join(self.get_dir(), 'sdl_audio.c'), '--preload-file', 'sound.ogg', '--preload-file', 'sound2.wav', '--embed-file', 'the_entertainer.ogg', '--preload-file', 'noise.ogg', '--preload-file', 'bad.ogg', '-o', 'page.html', '-s', 'EXPORTED_FUNCTIONS=["_main", "_play", "_play2"]', '-s', 'USE_SDL=2', '-DUSE_SDL2']).communicate()
+    # self.run_process([EMCC, '-O1', '--closure', '0', '--minify=0', os.path.join(self.get_dir(), 'sdl_audio.c'), '--preload-file', 'sound.ogg', '--preload-file', 'sound2.wav', '--embed-file', 'the_entertainer.ogg', '--preload-file', 'noise.ogg', '--preload-file', 'bad.ogg', '-o', 'page.html', '-s', 'EXPORTED_FUNCTIONS=[_main,_play,_play2', '-s', 'USE_SDL=2', '-DUSE_SDL2']).communicate()
     # self.run_browser('page.html', '', '/report_result?1')
 
   @parameterized({
@@ -101,7 +101,7 @@ def test_sdl_audio_panning(self):
     shutil.copyfile(test_file('sounds', 'the_entertainer.wav'), os.path.join(self.get_dir(), 'the_entertainer.wav'))
 
     # use closure to check for a possible bug with closure minifying away newer Audio() attributes
-    self.compile_btest(['-O2', '--closure=1', '--minify=0', test_file('sdl_audio_panning.c'), '--preload-file', 'the_entertainer.wav', '-o', 'page.html', '-s', 'EXPORTED_FUNCTIONS=["_main", "_play"]'])
+    self.compile_btest(['-O2', '--closure=1', '--minify=0', test_file('sdl_audio_panning.c'), '--preload-file', 'the_entertainer.wav', '-o', 'page.html', '-s', 'EXPORTED_FUNCTIONS=_main,_play'])
     self.run_browser('page.html', '', '/report_result?1')
 
   def test_sdl_audio_beeps(self):
