Merge branch 'incoming' into minnum-maxnum-intrinsics

Author: varkor

ChangeLog.markdown

@@ -9,9 +9,14 @@ Not all changes are documented here. In particular, new features, user-oriented
 
 Current Trunk
 -------------
+ - Breaking change: Don't export the `ALLOC_*` numeric constants by default. As with previous changes, a warning will be shown in `-O0` and when `ASSERTIONS` are on if they are used.
+ - Breaking change: Don't export FS methods by default. As with previous changes, a warning will be shown in `-O0` and when `ASSERTIONS` are on, which will suggest either exporting the specific methods you need, or using `FORCE_FILESYSTEM` which will auto export all the main filesystem methods. Aside from using FS methods yourself, you may notice this change when using a file package created standalone, that is, by running the file packager directly and then loading it at run time (as opposed to telling `emcc` to package the files for you, in which case it would be aware of them at compile time); you should build with `FORCE_FILESYSTEM` to ensure filesystem support for that case.
+
+v1.37.27: 12/24/2017
+--------------------
  - Breaking change: Remove the `Runtime` object, and move all the useful methods from it to simple top-level functions. Any usage of `Runtime.func` should be changed to `func`.
 
-v1.37.26: 12/20/1027
+v1.37.26: 12/20/2017
 --------------------
  - Breaking change: Change `NO_EXIT_RUNTIME` to 1 by default. This means that by default we don't include code to shut down the runtime, flush stdio streams, run atexits, etc., which is better for code size. When `ASSERTIONS` is on, we warn at runtime if there is text buffered in the streams that should be flushed, or atexits are used.
  - Meta-DCE for JS+wasm: remove unused code between JS+wasm more aggressively. This should not break valid code, but may break code that depended on unused code being kept around (like using a function from outside the emitted JS without exporting it - only exported things are guaranteed to be kept alive through optimization).

emcc.py

@@ -909,7 +909,11 @@ def check(input_file):
             value = '"' + value + '"'
         else:
           value = value.replace('\\', '\\\\')
-        setattr(shared.Settings, key, eval(value))
+        try:
+          setattr(shared.Settings, key, eval(value))
+        except Exception as e:
+          logging.error('a problem occurred in evaluating content after a "-s", specifically  %s . one possible cause of this is missing quotation marks (this depends on the shell you are running in; you may need quotation marks around the entire  %s , or on an individual element)' % (change, change))
+          raise e
         if key == 'EXPORTED_FUNCTIONS':
           # used for warnings in emscripten.py
           shared.Settings.ORIGINAL_EXPORTED_FUNCTIONS = original_exported_response or shared.Settings.EXPORTED_FUNCTIONS[:]
@@ -979,6 +983,10 @@ def check(input_file):
         shared.Settings.RELOCATABLE = 1
         shared.Settings.PRECISE_I64_MATH = 1 # other might use precise math, we need to be able to print it
         assert not options.use_closure_compiler, 'cannot use closure compiler on shared modules'
+        # getMemory is used during startup of shared modules (to allocate their static memory)
+        shared.Settings.EXPORTED_RUNTIME_METHODS += [
+          'getMemory',
+        ]
 
       if shared.Settings.EMULATE_FUNCTION_POINTER_CASTS:
         shared.Settings.ALIASING_FUNCTION_POINTERS = 0
@@ -1092,6 +1100,25 @@ def check(input_file):
       else:
         options.js_libraries.append(shared.path_from_root('src', 'library_pthread_stub.js'))
 
+      if shared.Settings.FORCE_FILESYSTEM:
+        # when the filesystem is forced, we export by default methods that filesystem usage
+        # may need, including filesystem usage from standalone file packager output (i.e.
+        # file packages not built together with emcc, but that are loaded at runtime
+        # separately, and they need emcc's output to contain the support they need)
+        shared.Settings.EXPORTED_RUNTIME_METHODS += [
+          'FS_createFolder',
+          'FS_createPath',
+          'FS_createDataFile',
+          'FS_createPreloadedFile',
+          'FS_createLazyFile',
+          'FS_createLink',
+          'FS_createDevice',
+          'FS_unlink',
+          'getMemory',
+          'addRunDependency',
+          'removeRunDependency',
+        ]
+
       if shared.Settings.USE_PTHREADS:
         if shared.Settings.LINKABLE:
           exit_with_error('-s LINKABLE=1 is not supported with -s USE_PTHREADS>0!')

emscripten-version.txt

@@ -1 +1 @@
-"1.37.26"
+"1.37.27"

emscripten.py

@@ -644,6 +644,13 @@ def get_exported_implemented_functions(all_exported_functions, all_implemented,
       funcs += ['setTempRet0', 'getTempRet0']
     if not (settings['BINARYEN'] and settings['SIDE_MODULE']):
       funcs += ['setThrew']
+    if settings['EMTERPRETIFY']:
+      funcs += ['emterpret']
+      if settings['EMTERPRETIFY_ASYNC']:
+        funcs += ['setAsyncState', 'emtStackSave', 'emtStackRestore']
+    if settings['ASYNCIFY']:
+      funcs += ['setAsync']
+
   return sorted(set(funcs))
 
 
@@ -1253,8 +1260,6 @@ def create_basic_vars(exported_implemented_functions, forwarded_json, metadata,
 def create_exports(exported_implemented_functions, in_table, function_table_data, metadata, settings):
   quote = quoter(settings)
   asm_runtime_funcs = create_asm_runtime_funcs(settings)
-  if need_asyncify(exported_implemented_functions):
-    asm_runtime_funcs.append('setAsync')
   all_exported = exported_implemented_functions + asm_runtime_funcs + function_tables(function_table_data, settings)
   if settings['EMULATED_FUNCTION_POINTERS']:
     all_exported += in_table
@@ -1281,10 +1286,6 @@ def create_asm_runtime_funcs(settings):
     funcs += ['setDynamicTop']
   if settings['ONLY_MY_CODE']:
     funcs = []
-  if settings.get('EMTERPRETIFY'):
-    funcs += ['emterpret']
-    if settings.get('EMTERPRETIFY_ASYNC'):
-      funcs += ['setAsyncState', 'emtStackSave', 'emtStackRestore']
   return funcs
 
 

site/source/docs/api_reference/module.rst

@@ -8,7 +8,7 @@ Module object
 
 Developers can provide an implementation of ``Module`` to control the execution of code. For example, to define how notification messages from Emscripten are displayed, developers implement the :js:attr:`Module.print` attribute.
 
-.. note:: ``Module`` is also used to provide access to Emscripten API functions (for example :js:func:`ccall`) in a safe way. Any function or runtime method exported (using ``EXPORTED_FUNCTIONS`` for compiled functions, or ``EXTRA_EXPORTED_RUNTIME_METHODS`` for runtime methods like ``ccall``) will be accessible on the ``Module`` object, without minification changing the name, and the optimizer will make sure to keep the function present (and not remove it as unused).
+.. note:: ``Module`` is also used to provide access to Emscripten API functions (for example :js:func:`ccall`) in a safe way. Any function or runtime method exported (using ``EXPORTED_FUNCTIONS`` for compiled functions, or ``EXTRA_EXPORTED_RUNTIME_METHODS`` for runtime methods like ``ccall``) will be accessible on the ``Module`` object, without minification changing the name, and the optimizer will make sure to keep the function present (and not remove it as unused). See the :ref:`relevant FAQ entry<faq-export-stuff>`.
 
 .. contents:: Table of Contents
 	:local:

site/source/docs/getting_started/FAQ.rst

@@ -345,15 +345,51 @@ Emscripten by default does *not* give fatal errors on undefined symbols, so you
 
 Aside from just forgetting to link in a necessary object file, one possible cause for this error is inline functions in headers. If you have a header with ``inline int my_func() { .. }`` then *Clang* may not actually inline the function (since inline is just a hint), and also not generate code for it (since it's in a header). The result is that the generated bitcode and JavaScript will not have that function implemented. One solution is to add ``static`` to the function declaration, which forces code to be generated in the object file: ``static inline int my_func() { .. }``.
 
+.. _faq-export-stuff:
+
 Why do I get ``TypeError: Module.someThing is not a function``?
 ===============================================================
 
-The ``Module`` object will contain exported methods. For something to appear there, you should add it to ``EXPORTED_FUNCTIONS`` for compiled code, or ``EXTRA_EXPORTED_RUNTIME_METHODS`` for a runtime method (like ``getValue``).
+The ``Module`` object will contain exported methods. For something to appear there, you should add it to ``EXPORTED_FUNCTIONS`` for compiled code, or ``EXTRA_EXPORTED_RUNTIME_METHODS`` for a runtime method (like ``getValue``). For example,
+
+ ::
+
+	./emcc -s EXPORTED_FUNCTIONS="['_main', '_my_func']" ...
+
+would export a C method ``my_func`` (in addition to ``main``, in this example). And
+
+ ::
+
+	./emcc -s EXTRA_EXPORTED_RUNTIME_METHODS="['ccall']" ...
+
+will export ``ccall``. In both cases you can then access the exported function on the ``Module`` object.
 
 .. note:: You can use runtime methods directly, without exporting them, if the compiler can see them used. For example, you can use ``getValue`` in ``EM_ASM`` code, or a ``--pre-js``, by calling it directly. The optimizer will not remove that JS runtime method because it sees it is used. You only need to use ``Module.getValue`` if you want to call that method from outside the JS code the compiler can see, and then you need to export it.
 
 .. note:: Emscripten used to export many runtime methods by default. This increased code size, and for that reason we've changed that default. If you depend on something that used to be exported, you should see a warning pointing you to the solution, in an unoptimized build, or a build with ``ASSERTIONS`` enabled, which we hope will minimize any annoyance. See ``Changelog.markdown`` for details.
 
+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
+
+::
+
+	# this fails on most Linuxes
+	./emcc a.c -s EXTRA_EXPORTED_RUNTIME_METHODS=['addOnPostRun']
+
+You may need quotation marks, such as
+
+::
+
+	# this works on most Linuxes
+	./emcc a.c -s "EXTRA_EXPORTED_RUNTIME_METHODS=['addOnPostRun']"
+
+	# also this should work
+	./emcc a.c -s EXTRA_EXPORTED_RUNTIME_METHODS="['addOnPostRun']"
+
+The proper syntax depends on the OS and shell you are in.
+
 Why do I get an odd python error complaining about libcxx.bc or libcxxabi.bc?
 =============================================================================
 

src/emscripten-source-map.min.js

@@ -284,11 +284,13 @@ var screen = { // XXX these values may need to be adjusted
   availWidth: 2100,
   availHeight: 1283,
 };
-var console = {
-  log: function(x) {
-    print(x);
-  },
-};
+if (typeof console === "undefined") {
+  console = {
+    log: function(x) {
+      print(x);
+    }
+  };
+}
 var MozBlobBuilder = function() {
   this.data = new Uint8Array(0);
   this.append = function(buffer) {

src/headless.js

@@ -54,7 +54,7 @@ mergeInto(LibraryManager.library, {
 
   emscripten_sleep__deps: ['emscripten_async_resume', '$Browser'],
   emscripten_sleep: function(ms) {
-    Module['asm'].setAsync(); // tell the scheduler that we have a callback on hold
+    Module['setAsync'](); // tell the scheduler that we have a callback on hold
     Browser.safeSetTimeout(_emscripten_async_resume, ms);
   },
 
@@ -196,7 +196,7 @@ mergeInto(LibraryManager.library, {
     var _url = Pointer_stringify(url);
     var _file = Pointer_stringify(file);
     _file = PATH.resolve(FS.cwd(), _file);
-    Module['asm'].setAsync();
+    Module['setAsync']();
     Module['noExitRuntime'] = true;
     var destinationDirectory = PATH.dirname(_file);
     FS.createPreloadedFile(
@@ -255,7 +255,7 @@ mergeInto(LibraryManager.library, {
     setState: function(s) {
       this.ensureInit();
       this.state = s;
-      Module['asm'].setAsyncState(s);
+      Module['setAsyncState'](s);
     },
     handle: function(doAsyncOp, yieldDuring) {
       Module['noExitRuntime'] = true;

src/library_async.js

@@ -14,7 +14,7 @@ mergeInto(LibraryManager.library, {
                 '__ATINIT__.unshift(function() { if (!Module["noFSInit"] && !FS.init.initialized) FS.init() });' +
                 '__ATMAIN__.push(function() { FS.ignorePermissions = false });' +
                 '__ATEXIT__.push(function() { FS.quit() });' +
-                //Get module methods from settings
+                // Get module methods from settings
                 '{{{ EXPORTED_RUNTIME_METHODS.filter(function(func) { return func.substr(0, 3) === 'FS_' }).map(function(func){return 'Module["' + func + '"] = FS.' + func.substr(3) + ";"}).reduce(function(str, func){return str + func;}, '') }}}',
   $FS: {
     root: null,

src/library_fs.js

@@ -271,10 +271,38 @@ var EXPORTED_RUNTIME_METHODS_SET = set(EXPORTED_RUNTIME_METHODS.concat(EXTRA_EXP
 EXPORTED_RUNTIME_METHODS = unset(EXPORTED_RUNTIME_METHODS_SET);
 EXTRA_EXPORTED_RUNTIME_METHODS = [];
 
-function maybeExport(name) {
+function isFSPrefixed(name) {
+  return name.length > 3 && name[0] === 'F' && name[1] === 'S' && name[2] === '_';
+}
+
+// forcing the filesystem exports a few things by default
+function isExportedByForceFilesystem(name) {
+  return name === 'FS_createFolder' ||
+         name === 'FS_createPath' ||
+         name === 'FS_createDataFile' ||
+         name === 'FS_createPreloadedFile' ||
+         name === 'FS_createLazyFile' ||
+         name === 'FS_createLink' ||
+         name === 'FS_createDevice' ||
+         name === 'FS_unlink' ||
+         name === 'getMemory' ||
+         name === 'addRunDependency' ||
+         name === 'removeRunDependency';
+}
+
+// optionally export something.
+// in ASSERTIONS mode we show a useful error if it is used without
+// being exported. how we show the message depends on whether it's
+// a function (almost all of them) or a number.
+function maybeExport(name, isNumber) {
   // if requested to be exported, export it
   if (name in EXPORTED_RUNTIME_METHODS_SET) {
-    return 'Module["' + name + '"] = ' + name + ';';
+    var exported = name;
+    if (isFSPrefixed(exported)) {
+      // this is a filesystem value, FS.x exported as FS_x
+      exported = 'FS.' + exported.substr(3);
+    }
+    return 'Module["' + name + '"] = ' + exported + ';';
   }
   // do not export it. but if ASSERTIONS, emit a
   // stub with an error, so the user gets a message
@@ -283,11 +311,23 @@ function maybeExport(name) {
     // check if it already exists, to support EXPORT_ALL and other cases
     // (we could optimize this, but in ASSERTIONS mode code size doesn't
     // matter anyhow)
-    return 'if (!Module["' + name + '"]) Module["' + name + '"] = function() { abort("\'' + name + '\' was not exported. add it to EXTRA_EXPORTED_RUNTIME_METHODS (see the FAQ)") };';
+    var extra = '';
+    if (isExportedByForceFilesystem(name)) {
+      extra = '. Alternatively, forcing filesystem support (-s FORCE_FILESYSTEM=1) can export this for you';
+    }
+    if (!isNumber) {
+      return 'if (!Module["' + name + '"]) Module["' + name + '"] = function() { abort("\'' + name + '\' was not exported. add it to EXTRA_EXPORTED_RUNTIME_METHODS (see the FAQ)' + extra + '") };';
+    } else {
+      return 'if (!Module["' + name + '"]) Object.defineProperty(Module, "' + name + '", { get: function() { abort("\'' + name + '\' was not exported. add it to EXTRA_EXPORTED_RUNTIME_METHODS (see the FAQ)' + extra + '") } });';
+    }
   }
   return '';
 }
 
+function maybeExportNumber(name) {
+  return maybeExport(name, true);
+}
+
 var PassManager = {
   serialize: function() {
     print('\n//FORWARDED_DATA:' + JSON.stringify({

src/modules.js

@@ -4,6 +4,15 @@
 Module['asm'] = asm;
 
 {{{ maybeExport('FS') }}}
+{{{ maybeExport('FS_createFolder') }}}
+{{{ maybeExport('FS_createPath') }}}
+{{{ maybeExport('FS_createDataFile') }}}
+{{{ maybeExport('FS_createPreloadedFile') }}}
+{{{ maybeExport('FS_createLazyFile') }}}
+{{{ maybeExport('FS_createLink') }}}
+{{{ maybeExport('FS_createDevice') }}}
+{{{ maybeExport('FS_unlink') }}}
+
 {{{ maybeExport('GL') }}}
 
 #if MEM_INIT_IN_WASM == 0

src/postamble.js

@@ -276,11 +276,11 @@ var ALLOC_STACK = 1; // Lives for the duration of the current function call
 var ALLOC_STATIC = 2; // Cannot be freed
 var ALLOC_DYNAMIC = 3; // Cannot be freed except through sbrk
 var ALLOC_NONE = 4; // Do not allocate
-{{{ maybeExport('ALLOC_NORMAL') }}}
-{{{ maybeExport('ALLOC_STACK') }}}
-{{{ maybeExport('ALLOC_STATIC') }}}
-{{{ maybeExport('ALLOC_DYNAMIC') }}}
-{{{ maybeExport('ALLOC_NONE') }}}
+{{{ maybeExportNumber('ALLOC_NORMAL') }}}
+{{{ maybeExportNumber('ALLOC_STACK') }}}
+{{{ maybeExportNumber('ALLOC_STATIC') }}}
+{{{ maybeExportNumber('ALLOC_DYNAMIC') }}}
+{{{ maybeExportNumber('ALLOC_NONE') }}}
 
 // allocate(): This is for internal use. You can use it yourself as well, but the interface
 //             is a little tricky (see docs right below). The reason is that it is optimized
@@ -933,7 +933,7 @@ function checkStackCookie() {
 }
 
 function abortStackOverflow(allocSize) {
-  abort('Stack overflow! Attempted to allocate ' + allocSize + ' bytes on the stack, but stack has only ' + (STACK_MAX - Module['asm'].stackSave() + allocSize) + ' bytes available!');
+  abort('Stack overflow! Attempted to allocate ' + allocSize + ' bytes on the stack, but stack has only ' + (STACK_MAX - stackSave() + allocSize) + ' bytes available!');
 }
 #endif
 

src/preamble.js

@@ -342,31 +342,16 @@ var ASYNCIFY_WHITELIST = ['qsort',   // Functions in this list are never conside
                           '__fwritex',
                           'MUSL_vfprintf'];
 
-var EXPORTED_RUNTIME_METHODS = [ // Runtime elements that are exported on Module. By default we export quite a bit, you can reduce this list to lower your code size,
-                                 // especially when closure is run (exporting prevents closure from eliminating code)
+var EXPORTED_RUNTIME_METHODS = [ // Runtime elements that are exported on Module by default. We used to export quite a lot here,
+                                 // but have removed them all, so this option is redundant given that EXTRA_EXPORTED_RUNTIME_METHODS
+                                 // exists, and so this option exists only for backwards compatibility. You should use
+                                 // EXTRA_EXPORTED_RUNTIME_METHODS for things you want to export from the runtime.
                                  // Note that methods on this list are only exported if they are included (either automatically from linking, or due to being
                                  // in DEFAULT_LIBRARY_FUNCS_TO_INCLUDE)
                                  // Note that the name may be slightly misleading, as this
                                  // is for any JS library element, and not just
                                  // methods. For example, we export the Runtime object
                                  // by having "Runtime" in this list.
-  'FS_createFolder',
-  'FS_createPath',
-  'FS_createDataFile',
-  'FS_createPreloadedFile',
-  'FS_createLazyFile',
-  'FS_createLink',
-  'FS_createDevice',
-  'FS_unlink',
-  'Runtime',
-  'ALLOC_NORMAL',
-  'ALLOC_STACK',
-  'ALLOC_STATIC',
-  'ALLOC_DYNAMIC',
-  'ALLOC_NONE',
-  'getMemory',
-  'addRunDependency',
-  'removeRunDependency',
 ];
 
 var EXTRA_EXPORTED_RUNTIME_METHODS = []; // Additional methods to those in EXPORTED_RUNTIME_METHODS. Adjusting that list