Rename -gside to -gseparate-dwarf, make the setting internal, and add…

… some docs (#10588)

emcc.py

@@ -2814,11 +2814,11 @@ def check_bad_eq(arg):
           newargs[i] = '-g'
           shared.Settings.FULL_DWARF = 1
           shared.warning('gforce_dwarf is a temporary option that will eventually disappear')
-        elif requested_level.startswith('side'):
+        elif requested_level.startswith('separate-dwarf'):
           # Emit full DWARF but also emit it in a file on the side
           newargs[i] = '-g'
           shared.Settings.FULL_DWARF = 1
-          shared.Settings.SIDE_DEBUG = 1
+          shared.Settings.SEPARATE_DWARF = 1
         # a non-integer level can be something like -gline-tables-only. keep
         # the flag for the clang frontend to emit the appropriate DWARF info.
         # set the emscripten debug level to 3 so that we do not remove that
@@ -3337,7 +3337,7 @@ def run_closure_compiler(final):
     with open(final, 'w') as f:
       f.write(js)
 
-  if shared.Settings.FULL_DWARF and shared.Settings.SIDE_DEBUG:
+  if shared.Settings.FULL_DWARF and shared.Settings.SEPARATE_DWARF:
     shared.Building.emit_debug_on_side(wasm_binary_target)
 
 

site/source/docs/tools_reference/emcc.rst

@@ -114,6 +114,11 @@ Options that are modified or new in *emcc* are listed below:
   - When compiling to object files, this is the same as in *Clang* and *gcc*, it adds debug information to the object files.
   - When linking, this is equivalent to :ref:`-g3 <emcc-g3>`.
 
+``-gseparate-dwarf``
+  Preserve debug information, but in a separate file on the side. This is the
+  same as ``-g``, but the main file will contain no debug info, while a file
+  with suffix ``.debug.wasm`` will contain the debug info.
+
 .. _emcc-gN:
 
 ``-g<level>``

src/settings.js

@@ -1499,14 +1499,6 @@ var ELIMINATE_DUPLICATE_FUNCTIONS_PASSES = 5;
 // the ctors.
 var EVAL_CTORS = 0;
 
-// Whether to emit DWARF in a wasm file on the side (this is not called
-// "split"/"separate" because there is already a DWARF concept by that name).
-// When DWARF is on the side, the main file has no DWARF info, while the side
-// file, ending in .debug.wasm, has the same wasm binary + all the debug
-// sections.
-// This has no effect if DWARF is not being emitted.
-var SIDE_DEBUG = 0;
-
 // see http://kripken.github.io/emscripten-site/docs/debugging/CyberDWARF.html
 // [fastcomp-only]
 var CYBERDWARF = 0;

src/settings_internal.js

@@ -173,3 +173,11 @@ var WASM_FUNCTIONS_THAT_ARE_NOT_NAME_MANGLED = ['setTempRet0', 'getTempRet0', 's
 
 // Internal: value of -flto argument (either full or thin)
 var LTO = 0;
+
+// Whether to emit DWARF in a separate wasm file on the side (this is not called
+// "split" because there is already a DWARF concept by that name).
+// When DWARF is on the side, the main file has no DWARF info, while the side
+// file, ending in .debug.wasm, has the same wasm binary + all the debug
+// sections.
+// This has no effect if DWARF is not being emitted.
+var SEPARATE_DWARF = 0;

tests/test_other.py

@@ -9039,11 +9039,11 @@ def test(infile, source_map_added_dir=''):
     test('inner/a.cpp', 'inner')
 
   @no_fastcomp('dwarf')
-  def test_side_debug(self):
+  def test_separate_dwarf(self):
     run_process([PYTHON, EMCC, path_from_root('tests', 'hello_world.c'), '-gforce_dwarf'])
     self.assertExists('a.out.wasm')
     self.assertNotExists('a.out.wasm.debug.wasm')
-    run_process([PYTHON, EMCC, path_from_root('tests', 'hello_world.c'), '-gside'])
+    run_process([PYTHON, EMCC, path_from_root('tests', 'hello_world.c'), '-gseparate-dwarf'])
     self.assertExists('a.out.wasm')
     self.assertExists('a.out.wasm.debug.wasm')
     self.assertLess(os.path.getsize('a.out.wasm'), os.path.getsize('a.out.wasm.debug.wasm'))