Add option to emit TypeScript definitions for Wasm module exports. (#21279)

brendandahl · web-flow · commit 57ba7930d65e · 2024-02-12T13:44:42.000-06:00
The new flag `--emit-tsd &lt;filename&gt;` will generate a TypeScript defintion
file for any Wasm module exports. If embind is also used the definitions
for those types will also be included in the same file.

This still doesn't give the full picture of Wasm module e.g. missing
HEAP&lt;N&gt; and the various helper functions defined in JS.
diff --git a/emcc.py b/emcc.py
@@ -140,6 +140,7 @@ def __init__(self):
     self.ignore_dynamic_linking = False
     self.shell_path = None
     self.source_map_base = ''
+    self.emit_tsd = ''
     self.embind_emit_tsd = ''
     self.emrun = False
     self.cpu_profiler = False
@@ -1276,6 +1277,9 @@ def consume_arg_file():
       options.source_map_base = consume_arg()
     elif check_arg('--embind-emit-tsd'):
       options.embind_emit_tsd = consume_arg()
+    elif check_arg('--emit-tsd'):
+      diagnostics.warning('experimental', '--emit-tsd is still experimental. Not all definitions are generated.')
+      options.emit_tsd = consume_arg()
     elif check_flag('--no-entry'):
       options.no_entry = True
     elif check_arg('--js-library'):
diff --git a/src/embind/embind_gen.js b/src/embind/embind_gen.js
@@ -365,7 +365,7 @@ var LibraryEmbind = {
         def.print(this.typeToJsName.bind(this), out);
       }
       // Print module definitions
-      out.push('export interface MainModule {\n');
+      out.push('interface EmbindModule {\n');
       for (const def of this.definitions) {
         if (!def.printModuleEntry) {
           continue;
diff --git a/test/other/embind_tsgen.d.ts b/test/other/embind_tsgen.d.ts
@@ -1,3 +1,8 @@
+// TypeScript bindings for emscripten-generated code.  Automatically generated at compile time.
+interface WasmModule {
+  _main(_0: number, _1: number): number;
+}
+
 export interface Test {
   x: number;
   readonly y: number;
@@ -77,7 +82,7 @@ export interface DerivedClass extends BaseClass {
 
 export type ValArr = [ number, number, number ];
 
-export interface MainModule {
+interface EmbindModule {
   Test: {staticFunction(_0: number): number; staticFunctionWithParam(x: number): number; staticProperty: number};
   class_returning_fn(): Test;
   class_unique_ptr_returning_fn(): Test;
@@ -104,3 +109,4 @@ export interface MainModule {
   string_test(_0: ArrayBuffer|Uint8Array|Uint8ClampedArray|Int8Array|string): string;
   wstring_test(_0: string): string;
 }
+export type MainModule = WasmModule & EmbindModule;
diff --git a/test/other/embind_tsgen_bigint.d.ts b/test/other/embind_tsgen_bigint.d.ts
@@ -1,3 +1,8 @@
-export interface MainModule {
+// TypeScript bindings for emscripten-generated code.  Automatically generated at compile time.
+interface WasmModule {
+}
+
+interface EmbindModule {
   bigintFn(_0: bigint): bigint;
 }
+export type MainModule = WasmModule & EmbindModule;
diff --git a/test/other/embind_tsgen_ignore_1.d.ts b/test/other/embind_tsgen_ignore_1.d.ts
@@ -0,0 +1,110 @@
+// TypeScript bindings for emscripten-generated code.  Automatically generated at compile time.
+interface WasmModule {
+  _pthread_self(): number;
+  _main(_0: number, _1: number): number;
+  __emscripten_tls_init(): number;
+  __emscripten_proxy_main(_0: number, _1: number): number;
+  __embind_initialize_bindings(): void;
+  __emscripten_thread_init(_0: number, _1: number, _2: number, _3: number, _4: number, _5: number): void;
+  __emscripten_thread_crashed(): void;
+  __emscripten_thread_exit(_0: number): void;
+}
+
+export interface Test {
+  x: number;
+  readonly y: number;
+  functionOne(_0: number, _1: number): number;
+  functionTwo(_0: number, _1: number): number;
+  functionFour(_0: boolean): number;
+  functionFive(x: number, y: number): number;
+  constFn(): number;
+  longFn(_0: number): number;
+  functionThree(_0: ArrayBuffer|Uint8Array|Uint8ClampedArray|Int8Array|string): number;
+  functionSix(str: ArrayBuffer|Uint8Array|Uint8ClampedArray|Int8Array|string): number;
+  delete(): void;
+}
+
+export interface BarValue<T extends number> {
+  value: T;
+}
+export type Bar = BarValue<0>|BarValue<1>|BarValue<2>;
+
+export interface EmptyEnumValue<T extends number> {
+  value: T;
+}
+export type EmptyEnum = never/* Empty Enumerator */;
+
+export type ValArrIx = [ Bar, Bar, Bar, Bar ];
+
+export interface IntVec {
+  push_back(_0: number): void;
+  resize(_0: number, _1: number): void;
+  size(): number;
+  set(_0: number, _1: number): boolean;
+  get(_0: number): any;
+  delete(): void;
+}
+
+export interface Foo {
+  process(_0: Test): void;
+  delete(): void;
+}
+
+export type ValObj = {
+  foo: Foo,
+  bar: Bar
+};
+
+export interface ClassWithConstructor {
+  fn(_0: number): number;
+  delete(): void;
+}
+
+export interface ClassWithTwoConstructors {
+  delete(): void;
+}
+
+export interface ClassWithSmartPtrConstructor {
+  fn(_0: number): number;
+  delete(): void;
+}
+
+export interface BaseClass {
+  fn(_0: number): number;
+  delete(): void;
+}
+
+export interface DerivedClass extends BaseClass {
+  fn2(_0: number): number;
+  delete(): void;
+}
+
+export type ValArr = [ number, number, number ];
+
+interface EmbindModule {
+  Test: {staticFunction(_0: number): number; staticFunctionWithParam(x: number): number; staticProperty: number};
+  class_returning_fn(): Test;
+  class_unique_ptr_returning_fn(): Test;
+  a_class_instance: Test;
+  an_enum: Bar;
+  Bar: {valueOne: BarValue<0>, valueTwo: BarValue<1>, valueThree: BarValue<2>};
+  EmptyEnum: {};
+  enum_returning_fn(): Bar;
+  IntVec: {new(): IntVec};
+  Foo: {};
+  ClassWithConstructor: {new(_0: number, _1: ValArr): ClassWithConstructor};
+  ClassWithTwoConstructors: {new(): ClassWithTwoConstructors; new(_0: number): ClassWithTwoConstructors};
+  ClassWithSmartPtrConstructor: {new(_0: number, _1: ValArr): ClassWithSmartPtrConstructor};
+  BaseClass: {};
+  DerivedClass: {};
+  a_bool: boolean;
+  an_int: number;
+  global_fn(_0: number, _1: number): number;
+  optional_test(_0: Foo | undefined): number | undefined;
+  smart_ptr_function(_0: ClassWithSmartPtrConstructor): number;
+  smart_ptr_function_with_params(foo: ClassWithSmartPtrConstructor): number;
+  function_with_callback_param(_0: (message: string) => void): number;
+  string_test(_0: ArrayBuffer|Uint8Array|Uint8ClampedArray|Int8Array|string): string;
+  wstring_test(_0: string): string;
+}
+export type MainModule = WasmModule & EmbindModule;
diff --git a/test/other/embind_tsgen_ignore_2.d.ts b/test/other/embind_tsgen_ignore_2.d.ts
@@ -0,0 +1,102 @@
+// TypeScript bindings for emscripten-generated code.  Automatically generated at compile time.
+interface WasmModule {
+}
+
+export interface Test {
+  x: number;
+  readonly y: number;
+  functionOne(_0: number, _1: number): number;
+  functionTwo(_0: number, _1: number): number;
+  functionFour(_0: boolean): number;
+  functionFive(x: number, y: number): number;
+  constFn(): number;
+  longFn(_0: number): number;
+  functionThree(_0: ArrayBuffer|Uint8Array|Uint8ClampedArray|Int8Array|string): number;
+  functionSix(str: ArrayBuffer|Uint8Array|Uint8ClampedArray|Int8Array|string): number;
+  delete(): void;
+}
+
+export interface BarValue<T extends number> {
+  value: T;
+}
+export type Bar = BarValue<0>|BarValue<1>|BarValue<2>;
+
+export interface EmptyEnumValue<T extends number> {
+  value: T;
+}
+export type EmptyEnum = never/* Empty Enumerator */;
+
+export type ValArrIx = [ Bar, Bar, Bar, Bar ];
+
+export interface IntVec {
+  push_back(_0: number): void;
+  resize(_0: number, _1: number): void;
+  size(): number;
+  set(_0: number, _1: number): boolean;
+  get(_0: number): any;
+  delete(): void;
+}
+
+export interface Foo {
+  process(_0: Test): void;
+  delete(): void;
+}
+
+export type ValObj = {
+  foo: Foo,
+  bar: Bar
+};
+
+export interface ClassWithConstructor {
+  fn(_0: number): number;
+  delete(): void;
+}
+
+export interface ClassWithTwoConstructors {
+  delete(): void;
+}
+
+export interface ClassWithSmartPtrConstructor {
+  fn(_0: number): number;
+  delete(): void;
+}
+
+export interface BaseClass {
+  fn(_0: number): number;
+  delete(): void;
+}
+
+export interface DerivedClass extends BaseClass {
+  fn2(_0: number): number;
+  delete(): void;
+}
+
+export type ValArr = [ number, number, number ];
+
+interface EmbindModule {
+  Test: {staticFunction(_0: number): number; staticFunctionWithParam(x: number): number; staticProperty: number};
+  class_returning_fn(): Test;
+  class_unique_ptr_returning_fn(): Test;
+  a_class_instance: Test;
+  an_enum: Bar;
+  Bar: {valueOne: BarValue<0>, valueTwo: BarValue<1>, valueThree: BarValue<2>};
+  EmptyEnum: {};
+  enum_returning_fn(): Bar;
+  IntVec: {new(): IntVec};
+  Foo: {};
+  ClassWithConstructor: {new(_0: number, _1: ValArr): ClassWithConstructor};
+  ClassWithTwoConstructors: {new(): ClassWithTwoConstructors; new(_0: number): ClassWithTwoConstructors};
+  ClassWithSmartPtrConstructor: {new(_0: number, _1: ValArr): ClassWithSmartPtrConstructor};
+  BaseClass: {};
+  DerivedClass: {};
+  a_bool: boolean;
+  an_int: number;
+  global_fn(_0: number, _1: number): number;
+  optional_test(_0: Foo | undefined): number | undefined;
+  smart_ptr_function(_0: ClassWithSmartPtrConstructor): number;
+  smart_ptr_function_with_params(foo: ClassWithSmartPtrConstructor): number;
+  function_with_callback_param(_0: (message: string) => void): number;
+  string_test(_0: ArrayBuffer|Uint8Array|Uint8ClampedArray|Int8Array|string): string;
+  wstring_test(_0: string): string;
+}
+export type MainModule = WasmModule & EmbindModule;
diff --git a/test/other/embind_tsgen_memory64.d.ts b/test/other/embind_tsgen_memory64.d.ts
@@ -1,3 +1,8 @@
-export interface MainModule {
+// TypeScript bindings for emscripten-generated code.  Automatically generated at compile time.
+interface WasmModule {
+}
+
+interface EmbindModule {
   longFn(_0: bigint): bigint;
 }
+export type MainModule = WasmModule & EmbindModule;
diff --git a/test/other/test_emit_tsd.c b/test/other/test_emit_tsd.c
@@ -0,0 +1,10 @@
+#include <emscripten.h>
+
+EMSCRIPTEN_KEEPALIVE void fooVoid() {}
+EMSCRIPTEN_KEEPALIVE int fooInt(int a, int b) {
+  return 42;
+}
+
+int main() {
+
+}
diff --git a/test/other/test_emit_tsd.d.ts b/test/other/test_emit_tsd.d.ts
@@ -0,0 +1,8 @@
+// TypeScript bindings for emscripten-generated code.  Automatically generated at compile time.
+interface WasmModule {
+  _fooVoid(): void;
+  _fooInt(_0: number, _1: number): number;
+  _main(_0: number, _1: number): number;
+}
+
+export type MainModule = WasmModule;
diff --git a/test/test_other.py b/test/test_other.py
@@ -3136,14 +3136,14 @@ def test_embind_tsgen_ignore(self):
                   '-lembind', # Test duplicated link option.
                   ]
     self.emcc(test_file('other/embind_tsgen.cpp'), extra_args)
-    self.assertFileContents(test_file('other/embind_tsgen.d.ts'), read_file('embind_tsgen.d.ts'))
+    self.assertFileContents(test_file('other/embind_tsgen_ignore_1.d.ts'), read_file('embind_tsgen.d.ts'))
     # Test these args separately since they conflict with arguments in the first test.
     extra_args = ['-sMODULARIZE',
                   '--embed-file', 'fail.js',
                   '-sMINIMAL_RUNTIME=2',
                   '-sEXPORT_ES6=1']
     self.emcc(test_file('other/embind_tsgen.cpp'), extra_args)
-    self.assertFileContents(test_file('other/embind_tsgen.d.ts'), read_file('embind_tsgen.d.ts'))
+    self.assertFileContents(test_file('other/embind_tsgen_ignore_2.d.ts'), read_file('embind_tsgen.d.ts'))
 
   def test_embind_tsgen_test_embind(self):
     self.run_process([EMXX, test_file('embind/embind_test.cpp'),
@@ -3189,6 +3189,12 @@ def test_embind_jsgen_method_pointer_stability(self):
     # AOT JS generation still works correctly.
     self.do_runf('other/embind_jsgen_method_pointer_stability.cpp', 'done')
 
+  def test_emit_tsd(self):
+    self.run_process([EMCC, test_file('other/test_emit_tsd.c'),
+                      '--emit-tsd', 'test_emit_tsd.d.ts', '-Wno-experimental'] +
+                     self.get_emcc_args())
+    self.assertFileContents(test_file('other/test_emit_tsd.d.ts'), read_file('test_emit_tsd.d.ts'))
+
   def test_emconfig(self):
     output = self.run_process([emconfig, 'LLVM_ROOT'], stdout=PIPE).stdout.strip()
     self.assertEqual(output, config.LLVM_ROOT)
diff --git a/tools/emscripten.py b/tools/emscripten.py
diff --git a/tools/extract_metadata.py b/tools/extract_metadata.py
diff --git a/tools/link.py b/tools/link.py

Original file line number	Diff line number	Diff line change
`@@ -365,7 +365,7 @@ var LibraryEmbind = {`
`365`	`365`	`def.print(this.typeToJsName.bind(this), out);`
`366`	`366`	`}`
`367`	`367`	`// Print module definitions`
`368`		`- out.push('export interface MainModule {\n');`
	`368`	`+ out.push('interface EmbindModule {\n');`
`369`	`369`	`for (const def of this.definitions) {`
`370`	`370`	`if (!def.printModuleEntry) {`
`371`	`371`	`continue;`