From a0694298aad5f2f428311d6e787484a250c9de43 Mon Sep 17 00:00:00 2001
From: "Serge S. Gulin" <gulin.serge@gmail.com>
Date: Sat, 30 Mar 2024 02:28:24 +0300
Subject: [PATCH] JS: Add externs to linker (fixes #24602)
After enabling jsdoc and built-in google closure compiler types I was needed to deal with the following:
1. Define NodeJS-environment types. I've just copied minimal set of externs from semi-official repo (see https://github.com/externs/nodejs/blob/6c6882c73efcdceecf42e7ba11f1e3e5c9c041f0/v8/nodejs.js#L8).
2. Define Emscripten-environment types: `HEAP8`. Emscripten already provides some externs in our code but it supposed to be run in some module system. And its definitions do not work well in plain bundle.
3. We have some functions which purpose is to add to functions some contextual information via function properties. These functions should be marked as `modifies` to let google closure compiler remove calls if these functions are not used actually by call graph. Such functions are: `h$o`, `h$sti`, `h$init_closure`, `h$setObjInfo`.
4. STG primitives such as registries and stuff from `GHC.StgToJS`. `dXX` properties were already present at externs generator function but they are started from `7`, not from `1`. This message is related: `// fixme does closure compiler bite us here?`
---
compiler/GHC/StgToJS/Linker/Linker.hs | 58 +++++++++++++++++++++++++--
1 file changed, 55 insertions(+), 3 deletions(-)
diff --git a/compiler/GHC/StgToJS/Linker/Linker.hs b/compiler/GHC/StgToJS/Linker/Linker.hs
index 3a609b9bb340..67fa8b344b0c 100644
--- a/compiler/GHC/StgToJS/Linker/Linker.hs
+++ b/compiler/GHC/StgToJS/Linker/Linker.hs
@@ -728,12 +728,64 @@ writeRunner _settings out = do
rtsExterns :: FastString
rtsExterns =
+ -- Google Closure Compiler --externs option is deprecated.
+ -- Need pass them as a js file with @externs module-level jsdoc.
+ "/** @externs @suppress {duplicate} */\n" <>
"// GHCJS RTS externs for closure compiler ADVANCED_OPTIMIZATIONS\n\n" <>
- mconcat (map (\x -> "/** @type {*} */\nObject.d" <> mkFastString (show x) <> ";\n")
- [(7::Int)..16384])
+ mconcat
+ -- See GHC.StgToJS
+ -- We connect all payload fields "dXX" on JavaScript Object.
+ -- That's most simple way to make Google Closure Compiler prevent
+ -- property names mangling.
+ (map (\x -> "/** @type {*} */\nObject.d" <> mkFastString (show x) <> ";\n")
+ [(1::Int)..16384]) <>
+ mconcat
+ (map (\x -> "/** @type {*} */\nObject." <> x <> ";\n")
+ -- We do same for special STG properties as well.
+ ["m", "f", "cc", "t", "size", "i", "n", "a", "r", "s"]) <>
+ mconcat
+ [ -- Used at h$mkForeignCallback
+ "/** @type {*} */\nObject.mv;\n"
+ ] <>
+ mconcat
+ (map (\x -> x <> ";\n")
+ [ -- Externs needed by node environment
+ "/** @type {string} */ var __dirname"
+ -- Copied minimally from https://github.com/externs/nodejs/blob/6c6882c73efcdceecf42e7ba11f1e3e5c9c041f0/v8/nodejs.js#L8
+ , "/** @const */ var NodeJS = {}"
+ -- NodeJS Stream interface
+ , "/** @interface */ NodeJS.Stream = function () {}"
+ , "/** @template THIS @this {THIS} @return {THIS} */ NodeJS.Stream.prototype.on = function() {}"
+ , "/** @return {boolean} */ NodeJS.Stream.prototype.write = function() {}"
+ -- NodeJS versions property contains actual versions of the environment
+ , "/** @interface */ NodeJS.ProcessVersions = function() {}"
+ , "/** @type {string} */ NodeJS.ProcessVersions.prototype.node"
+ -- NodeJS Process interface
+ , "/** @interface */ NodeJS.Process = function() {}"
+ , "/** @type {!NodeJS.Stream} */ NodeJS.Process.prototype.stderr"
+ , "/** @type {!NodeJS.Stream} */ NodeJS.Process.prototype.stdin"
+ , "/** @type {!NodeJS.Stream} */ NodeJS.Process.prototype.stdout"
+ , "/** @type {!NodeJS.ProcessVersions} */ NodeJS.Process.prototype.versions"
+ , "/** @return {?} */ NodeJS.Process.prototype.exit = function() {}"
+ , "/** @type {!Array<string>} */ NodeJS.Process.prototype.argv"
+ -- NodeJS Process definition
+ , "/** @type {!NodeJS.Process} */ var process"
+ -- NodeJS Buffer class
+ , "/** @extends {Uint8Array} @constructor */ function Buffer(arg1, encoding) {}"
+ , "/** @return {!Buffer} */ Buffer.alloc = function() {}"
+ -- Emscripten Module
+ , "/** @type {*} */ var Module"
+ -- Mozilla's Narcissus (JS in JS interpreter implemented on top of SpiderMonkey) environment
+ , "/** @type {*} */ var putstr"
+ , "/** @type {*} */ var printErr"
+ -- Apples's JavaScriptCore environment
+ , "/** @type {*} */ var debug"
+ -- We use only Heap8 from Emscripten
+ , "/** @type {!Int8Array} */ Module.HEAP8"
+ ])
writeExterns :: FilePath -> IO ()
-writeExterns out = writeFile (out </> "all.js.externs")
+writeExterns out = writeFile (out </> "all.externs.js")
$ unpackFS rtsExterns
-- | Get all block dependencies for a given set of roots
--
GitLab