Allow marking of library functions as __internal. (#15294)

Functions marked in this way will generate a warning if depended
on my external (user) library JS files.

See: #15242

Author: sbc100

ChangeLog.md

@@ -20,6 +20,10 @@ See docs/process.md for more on how version tagging works.
 
 2.0.32
 ------
+- Internal-only library functions can now be marked as `__internal: true` in JS
+  system libraries.  Such symbols should not be used by external libraries and
+  are subject to change.  As of now we generate warning when external libraries
+  depend on the these symbols.
 - Stub functions from `library_syscall.js` and `library.js` were replaced with
   native code stubs (See `system/lib/libc/emscripten_syscall_stubs.c`).  This
   should be better for wasm module portability as well as code size.  As part

src/compiler.js

@@ -8,7 +8,7 @@
 // LLVM => JavaScript compiler, main entry point
 
 var nodeFS = require('fs');
-var nodePath = require('path');
+nodePath = require('path');
 
 print = (x) => {
   process['stdout'].write(x + '\n');

src/jsifier.js

@@ -205,10 +205,14 @@ function ${name}(${args}) {
         error(`JS library directive ${ident}__deps=${deps.toString()} is of type ${typeof deps}, but it should be an array!`);
         return;
       }
+      var isUserSymbol = LibraryManager.library[ident + '__user'];
       deps.forEach((dep) => {
         if (typeof snippet === 'string' && !(dep in LibraryManager.library)) {
           warn(`missing library dependency ${dep}, make sure you are compiling with the right options (see #if in src/library*.js)`);
         }
+        if (isUserSymbol && LibraryManager.library[dep + '__internal']) {
+          warn(`user library symbol '${ident}' depends on internal symbol '${dep}'`)
+        }
       });
       var isFunction = false;
 

src/library.js

@@ -3395,6 +3395,7 @@ LibraryManager.library = {
 #endif
   },
 
+  $callRuntimeCallbacks__internal: true,
   $callRuntimeCallbacks: function(callbacks) {
     while (callbacks.length > 0) {
       var callback = callbacks.shift();

src/library_dylink.js

@@ -5,6 +5,7 @@
 
 var LibraryDylink = {
 #if RELOCATABLE
+  $resolveGlobalSymbol__internal: true,
   $resolveGlobalSymbol__deps: ['$asmjsMangle'],
   $resolveGlobalSymbol: function(symName, direct) {
     var sym;
@@ -39,6 +40,7 @@ var LibraryDylink = {
 
   // Create globals to each imported symbol.  These are all initialized to zero
   // and get assigned later in `updateGOT`
+  $GOTHandler__internal: true,
   $GOTHandler__deps: ['$GOT'],
   $GOTHandler: {
     'get': function(obj, symName) {
@@ -52,6 +54,7 @@ var LibraryDylink = {
     }
   },
 
+  $isInternalSym__internal: true,
   $isInternalSym: function(symName) {
     // TODO: find a way to mark these in the binary or avoid exporting them.
     return [
@@ -72,6 +75,7 @@ var LibraryDylink = {
     ;
   },
 
+  $updateGOT__internal: true,
   $updateGOT__deps: ['$GOT', '$isInternalSym'],
   $updateGOT: function(exports, replace) {
 #if DYLINK_DEBUG
@@ -122,6 +126,7 @@ var LibraryDylink = {
   },
 
   // Applies relocations to exported things.
+  $relocateExports__internal: true,
   $relocateExports__deps: ['$updateGOT'],
   $relocateExports: function(exports, memoryBase, replace) {
     var relocated = {};
@@ -149,6 +154,7 @@ var LibraryDylink = {
     return relocated;
   },
 
+  $reportUndefinedSymbols__internal: true,
   $reportUndefinedSymbols__deps: ['$GOT', '$resolveGlobalSymbol'],
   $reportUndefinedSymbols: function() {
 #if DYLINK_DEBUG
@@ -200,6 +206,7 @@ var LibraryDylink = {
     loadedLibsByHandle: {},
   },
 
+  $dlSetError__internal: true,
   $dlSetError: ['___dl_seterr',
 #if MINIMAL_RUNTIME
    '$intArrayFromString'
@@ -215,6 +222,7 @@ var LibraryDylink = {
   // Dynamic version of shared.py:make_invoke.  This is needed for invokes
   // that originate from side modules since these are not known at JS
   // generation time.
+  $createInvokeFunction__internal: true,
   $createInvokeFunction__deps: ['$dynCall', 'setThrew'],
   $createInvokeFunction: function(sig) {
     return function() {
@@ -256,6 +264,7 @@ var LibraryDylink = {
 
   // returns the side module metadata as an object
   // { memorySize, memoryAlign, tableSize, tableAlign, neededDynlibs}
+  $getDylinkMetadata__internal: true,
   $getDylinkMetadata: function(binary) {
     var offset = 0;
     var end = 0;
@@ -734,6 +743,7 @@ var LibraryDylink = {
     return true;
   },
 
+  $preloadDylibs__internal: true,
   $preloadDylibs__deps: ['$loadDynamicLibrary', '$reportUndefinedSymbols'],
   $preloadDylibs: function() {
 #if DYLINK_DEBUG

src/modules.js

@@ -185,11 +185,30 @@ var LibraryManager = {
     this.libraries = libraries;
 
     for (var filename of libraries) {
-      var src = read(filename);
+      var isUserLibrary = nodePath.isAbsolute(filename);
       if (VERBOSE) {
-        printErr('processing: ' + filename);
+        if (isUserLibrary) {
+          printErr('processing user library: ' + filename);
+        } else {
+          printErr('processing system library: ' + filename);
+        }
       }
+      var src = read(filename);
+      var origLibrary = undefined;
       var processed = undefined;
+      // When we parse user libraries also set `__user` attribute
+      // on each element so that we can distinguish them later.
+      if (isUserLibrary) {
+        origLibrary = this.library
+        this.library = new Proxy(this.library, {
+          set: (target, prop, value) => {
+            target[prop] = value;
+            if (!isJsLibraryConfigIdentifier(prop)) {
+              target[prop + '__user'] = true;
+            }
+          }
+        });
+      }
       try {
         processed = processMacros(preprocess(src, filename));
         eval(processed);
@@ -214,6 +233,10 @@ var LibraryManager = {
           }
         }
         throw e;
+      } finally {
+        if (origLibrary) {
+          this.library = origLibrary;
+        }
       }
     }
 

src/utility.js

@@ -122,6 +122,7 @@ function isJsLibraryConfigIdentifier(ident) {
     '__import',
     '__nothrow',
     '__noleakcheck',
+    '__internal',
   ];
   return suffixes.some((suffix) => ident.endsWith(suffix));
 }

tests/test_other.py

@@ -3169,6 +3169,25 @@ def test_js_lib_using_asm_lib(self):
     self.run_process([EMXX, 'src.cpp', '--js-library', 'lib.js'])
     self.assertContained('c calling: 14\n', self.run_js('a.out.js'))
 
+  def test_js_internal_deps(self):
+    create_file('lib.js', r'''
+mergeInto(LibraryManager.library, {
+  jslibfunc__deps: ['$callRuntimeCallbacks'],
+  jslibfunc: function(x) {
+    callRuntimeCallbacks();
+  },
+});
+''')
+    create_file('src.cpp', r'''
+#include <stdio.h>
+extern "C" int jslibfunc();
+int main() {
+  printf("c calling: %d\n", jslibfunc());
+}
+''')
+    err = self.run_process([EMXX, 'src.cpp', '--js-library', 'lib.js'], stderr=PIPE).stderr
+    self.assertContained("warning: user library symbol 'jslibfunc' depends on internal symbol '$callRuntimeCallbacks'", err)
+
   def test_EMCC_BUILD_DIR(self):
     # EMCC_BUILD_DIR env var contains the dir we were building in, when running the js compiler (e.g. when
     # running a js library). We force the cwd to be src/ for technical reasons, so this lets you find out