Speed up emcc -v by not running sanity checks.

Since some build tools run `emcc -v` regularly we want to be fast.  This
change avoid running sanity checks which means fewer subprocesses.

On my machine this takes `emcc -v ` from ~300 ro ~200 ms.

Add a new options `--check` which will force the running of sanity
checks.

See: #13004

Author: sbc100

ChangeLog.md

@@ -23,6 +23,9 @@ Current Trunk
 
 2.0.11: 12/17/2020
 ------------------
+- `emcc -v` no longer forces the running the sanity checks.  Sanity checks
+  are always run on first use or can be forced with `--check` or by setting
+  `EMCC_DEBUG` is set in the environment.
 - An upstream LLVM regression with global initializer linking has been fixed
   (#13038).
 - Remove a racy unneeded assertion about async dynamic linking (#13060).

docs/emcc.txt

@@ -401,10 +401,8 @@ Options that are modified or new in *emcc* are listed below:
 "-v"
    Turns on verbose output.
 
-   This will pass "-v" to *Clang*, and also enable "EMCC_DEBUG" to
-   generate intermediate files for the compiler's various stages. It
-   will also run Emscripten's internal sanity checks on the toolchain,
-   etc.
+   This will print the internal sub-commands run by emscripten as well
+   as "-v" to *Clang*.
 
    Tip:
 

emcc.py

@@ -781,11 +781,11 @@ def run(args):
       revision = open(shared.path_from_root('emscripten-revision.txt')).read().strip()
     if revision:
       revision = ' (%s)' % revision
-    print('''emcc (Emscripten gcc/clang-like replacement) %s%s
+    print('''%s%s
 Copyright (C) 2014 the Emscripten authors (see AUTHORS.txt)
 This is free and open source software under the MIT license.
 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-  ''' % (shared.EMSCRIPTEN_VERSION, revision))
+  ''' % (version_string(), revision))
     return 0
 
   if run_via_emxx:
@@ -795,10 +795,8 @@ def run(args):
 
   if len(args) == 1 and args[0] == '-v': # -v with no inputs
     # autoconf likes to see 'GNU' in the output to enable shared object support
-    print('emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) %s' % shared.EMSCRIPTEN_VERSION, file=sys.stderr)
-    code = shared.check_call([clang, '-v'] + shared.get_clang_flags(), check=False).returncode
-    shared.check_sanity(force=True)
-    return code
+    print(version_string(), file=sys.stderr)
+    return shared.check_call([clang, '-v'] + shared.get_clang_flags(), check=False).returncode
 
   if '-dumpmachine' in args:
     print(shared.get_llvm_target())
@@ -2347,6 +2345,10 @@ def post_link(options, in_wasm, wasm_target, target):
   return 0
 
 
+def version_string():
+  return 'emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) %s' % shared.EMSCRIPTEN_VERSION
+
+
 def parse_args(newargs):
   options = EmccOptions()
   settings_changes = []
@@ -2528,7 +2530,6 @@ def consume_arg_file():
       options.ignore_dynamic_linking = True
     elif arg == '-v':
       shared.PRINT_STAGES = True
-      shared.check_sanity(force=True)
     elif check_arg('--shell-file'):
       options.shell_path = consume_arg_file()
     elif check_arg('--source-map-base'):
@@ -2546,6 +2547,10 @@ def consume_arg_file():
       shared.Cache.erase()
       shared.check_sanity(force=True) # this is a good time for a sanity check
       should_exit = True
+    elif check_flag('--check'):
+      print(version_string(), file=sys.stderr)
+      shared.check_sanity(force=True) # this is a good time for a sanity check
+      should_exit = True
     elif check_flag('--clear-ports'):
       logger.info('clearing ports and cache as requested by --clear-ports')
       system_libs.Ports.erase()

site/source/docs/building_from_source/verify_emscripten_environment.rst

@@ -13,11 +13,11 @@ Testing the environment
 Sanity tests
 ------------
 
-The first step in verifying the environment is to run Emscripten with the version command (``-v``). The command prints out information about the toolchain and runs some basic sanity tests to check that the required tools are available.
+The first step in verifying the environment is to run Emscripten with ``--check``. The option prints out information about the toolchain and runs some basic sanity tests to check that the required tools are available.
 
 Open a terminal in the directory in which you installed Emscripten (on Windows open the :ref:`Emscripten Command Prompt <emcmdprompt>`). Then call the :ref:`Emscripten Compiler Frontend (emcc) <emccdoc>` as shown::
 
-  ./emcc -v
+  ./emcc --check
 
 .. note:: On Windows, invoke the tool with **emcc** instead of **./emcc**.
 
@@ -27,13 +27,10 @@ For example, the following output reports an installation where Java is missing:
   :emphasize-lines: 6
 
   emcc (Emscripten GCC-like replacement + linker emulating GNU ld ) 1.21.0
-  clang version 3.3
-  Target: x86_64-pc-win32
-  Thread model: posix
-  INFO     root: (Emscripten: Running sanity checks)
-  WARNING  root: java does not seem to exist, required for closure compiler. -O2 and above will fail. You need to define JAVA in .emscripten
+  shared:INFO: (Emscripten: Running sanity checks)
+  shared:WARNING: java does not seem to exist, required for closure compiler. -O2 and above will fail. You need to define JAVA in .emscripten
 
-At this point you need to :ref:`Install and activate <fixing-missing-components-emcc>` any missing components. When everything is set up properly, ``emcc -v`` should give no warnings, and if you just enter ``emcc`` (without any input files), it will give an error ::
+At this point you need to :ref:`Install and activate <fixing-missing-components-emcc>` any missing components. When everything is set up properly, ``emcc ---check`` should give no warnings, and if you just enter ``emcc`` (without any input files), it will give an error ::
 
   emcc: error: no input files
 
@@ -64,7 +61,7 @@ Emscripten has a comprehensive test suite which may be used to further validate
 Troubleshooting
 ===============
 
-First run ``./emcc -v`` and examine the output to find missing components. You can also try ``./emcc --clear-cache`` to empty the :ref:`compiler's internal cache <emcc-clear-cache>` and reset it to a known good state.
+First run ``./emcc --check`` and examine the output to find missing components. You can also try ``./emcc --clear-cache`` to empty the :ref:`compiler's internal cache <emcc-clear-cache>` and reset it to a known good state.
 
 
 .. _fixing-missing-components-emcc:

site/source/docs/getting_started/FAQ.rst

@@ -17,7 +17,7 @@ Why do I get multiple errors building basic code and the tests?
 
 All the tests in the :ref:`Emscripten test suite <emscripten-test-suite>` are known to build and pass on our test infrastructure, so if you see failures locally it is likely that there is some problem with your environment. (Rarely, there may be temporary breakage, but never on a tagged release version.)
 
-First call ``emcc -v``, which runs basic sanity checks and prints out useful environment information. If that doesn't help, follow the instructions in :ref:`verifying-the-emscripten-environment`.
+First call ``emcc --check``, which runs basic sanity checks and prints out useful environment information. If that doesn't help, follow the instructions in :ref:`verifying-the-emscripten-environment`.
 
 You might also want to go through the :ref:`Tutorial` again, as it is updated as Emscripten changes.
 

site/source/docs/porting/Debugging.rst

@@ -57,7 +57,7 @@ directory (e.g. **/tmp** on UNIX).
 
 The debug logs can be analysed to profile and review the changes that were made in each step.
 
-.. note:: The debug mode can also be enabled by specifying the :ref:`verbose output <debugging-emcc-v>` compiler flag (``emcc -v``).
+.. note:: The more limited amount of debug information can also be enabled by specifying the :ref:`verbose output <debugging-emcc-v>` compiler flag (``emcc -v``).
 
 
 .. _debugging-compilation-settings:
@@ -121,10 +121,8 @@ Emscripten also supports some of Clang's sanitizers, such as :ref:`sanitizer_ubs
 emcc verbose output
 ===================
 
-Compiling with the :ref:`emcc -v <emcc-verbose>` option passes ``-v`` to LLVM and runs Emscripten's internal sanity checks on the toolchain.
-
-The verbose mode also enables Emscripten's :ref:`debugging-EMCC_DEBUG` to generate intermediate files for the compiler’s various stages.
-
+Compiling with the :ref:`emcc -v <emcc-verbose>` will cause Emscripten to output
+the sub-command that it runs as well as passes ``-v`` to Clang.
 
 .. _debugging-manual-debugging:
 

site/source/docs/tools_reference/emcc.rst

@@ -323,7 +323,8 @@ Options that are modified or new in *emcc* are listed below:
 ``-v``
   Turns on verbose output.
 
-  This will pass ``-v`` to *Clang*, and also enable ``EMCC_DEBUG`` to generate intermediate files for the compiler's various stages. It will also run Emscripten's internal sanity checks on the toolchain, etc.
+  This will print the internal sub-commands run by emscripten as well as ``-v``
+  to *Clang*.
 
   .. tip:: ``emcc -v`` is a useful tool for diagnosing errors. It works with or without other arguments.
 

tests/test_other.py

@@ -170,6 +170,14 @@ def test_emcc_v(self):
       self.assertContained('Target: wasm32-unknown-emscripten', proc.stderr)
       self.assertNotContained('this is dangerous', proc.stderr)
 
+  def test_emcc_check(self):
+    proc = self.run_process([EMCC, '--check'], stdout=PIPE, stderr=PIPE)
+    self.assertEqual(proc.stdout, '')
+    self.assertContained('emcc (Emscripten gcc/clang-like replacement', proc.stderr)
+    self.assertContained('Running sanity checks', proc.stderr)
+    proc = self.run_process([EMCC, '--check'], stdout=PIPE, stderr=PIPE)
+    self.assertContained('Running sanity checks', proc.stderr)
+
   def test_emcc_generate_config(self):
     for compiler in [EMCC, EMXX]:
       config_path = './emscripten_config'