[lld][WebAssembly] Add `--export-if-defined`

[sbc100]

Summary

Unlike the existing --export option this will not causes errors
or warnings if the specified symbol is not defined.

See: https://github.com/emscripten-core/emscripten/issues/13736

[sbc100]

rebase

[sbc100]

I dont love the name of this option.. but I failed to come up with any thing nicer.

I did consider weaking the existing --export to mean "export if defined" and then requiring --require-defined (which is an existing GNU ld option) to get the stronger meaning back.. but that has two disadvantages:

1. Potentially breaking existing users exceptions
2. Makes the common use case of --export foo --require-defined foo for each export a lot more verbose.

[dschuff]

Pre-existing, but what does --export plus --allow-undefined do?

lld/wasm/Driver.cpp

890

should this comment no longer say "if its found"? If it's not found, the whole process should error, right?

[dschuff]

Oh also, I think --export-if-defined is an OK name.

[MaskRay]

I don't know wasm enough... In ELF, --export-dynamic-symbol only affects defined symbols. --export-dynamic affects all defined symbols. They don't have effect on other symbols.

[sbc100]

In D99887#2669570, @dschuff wrote:

Pre-existing, but what does --export plus --allow-undefined do?

--allow-undefined will not report errors on undefined symbols at all (even those passed via --export). This is true both before and after this change.

One of the reasons for this change is that we would like one day to remove --allow-undefined from emscripten by default which exposes the current limitations of --export.

[sbc100]

In D99887#2669582, @MaskRay wrote:

I don't know wasm enough... In ELF, --export-dynamic-symbol only affects defined symbols. --export-dynamic affects all defined symbols. They don't have effect on other symbols.

Interesting.. aside from not really conveying its meaning clearly --export-dynamic-symbol sounds like it might be what we want here.

[MaskRay]

In D99887#2669855, @sbc100 wrote:

In D99887#2669582, @MaskRay wrote:

I don't know wasm enough... In ELF, --export-dynamic-symbol only affects defined symbols. --export-dynamic affects all defined symbols. They don't have effect on other symbols.

Interesting.. aside from not really conveying its meaning clearly --export-dynamic-symbol sounds like it might be what we want here.

I think the reason is because for non-defined symbols, there is no point specifically mentioning "exported".

An undefined symbol not defined anywhere or defined in a shared object is naturally exported, because otherwise it cannot be resolved to a different module at runtime.
For a defined symbol, there is a distinction whether it should be exported.

[sbc100]

Closing in favor of https://reviews.llvm.org/D101271

[sbc100]

rebase

[sbc100]

Going with this option over re-using --export-dynamic-symbol since the meaning doesn't quite match.

lld/docs/WebAssembly.rst

 be exported.
 
 When building an executable, only the entry point (``_start``) and symbols with
 the ``WASM_SYMBOL_EXPORTED`` flag are exported by default.  In LLVM the
 ``WASM_SYMBOL_EXPORTED`` flag is set by the ``wasm-export-name`` attribute which
 in turn can be set using ``__attribute__((export_name))`` clang attribute.
 
 In addition, symbols can be exported via the linker command line using
-``--export``.
+``--export`` (which will error if the symbol is not found) or
+``--export-if-defined`` (which will not).
 
 Finally, just like with native ELF linker the ``--export-dynamic`` flag can be
 used to export symbols in the executable which are marked as
 ``visibility=default``.
 
 Imports
 ~~~~~~~
 

lld/test/wasm/export-if-defined.s

+# RUN: llvm-mc -filetype=obj -triple=wasm32-unknown-unknown -o %t.o %s
+# RUN: wasm-ld --export-if-defined=foo -o %t1.wasm %t.o
+# RUN: obj2yaml %t1.wasm | FileCheck %s
+
+# RUN: wasm-ld --export-if-defined=bar -o %t2.wasm %t.o
+# RUN: obj2yaml %t2.wasm | FileCheck %s --check-prefixes=MISSING
+
+.globl foo
+foo:
+  .functype foo () -> ()
+  end_function
+
+.globl _start
+_start:
+  .functype _start () -> ()
+  end_function
+
+#      CHECK:   - Type:            EXPORT
+# CHECK-NEXT:     Exports:
+# CHECK-NEXT:       - Name:            memory
+# CHECK-NEXT:         Kind:            MEMORY
+# CHECK-NEXT:         Index:           0
+# CHECK-NEXT:       - Name:            foo
+# CHECK-NEXT:         Kind:            FUNCTION
+# CHECK-NEXT:         Index:           0
+# CHECK-NEXT:       - Name:            _start
+# CHECK-NEXT:         Kind:            FUNCTION
+# CHECK-NEXT:         Index:           1
+
+#      MISSING:   - Type:            EXPORT
+# MISSING-NEXT:     Exports:
+# MISSING-NEXT:       - Name:            memory
+# MISSING-NEXT:         Kind:            MEMORY
+# MISSING-NEXT:         Index:           0
+# MISSING-NEXT:       - Name:            _start
+# MISSING-NEXT:         Kind:            FUNCTION
+# MISSING-NEXT:         Index:           0

lld/wasm/Config.h

struct Configuration {
 
   llvm::StringRef entry;
   llvm::StringRef mapFile;
   llvm::StringRef outputFile;
   llvm::StringRef thinLTOCacheDir;
 
   llvm::StringSet<> allowUndefinedSymbols;
   llvm::StringSet<> exportedSymbols;
+  std::vector<llvm::StringRef> requiredExports;
   std::vector<llvm::StringRef> searchPaths;
   llvm::CachePruningPolicy thinLTOCachePolicy;
   llvm::Optional<std::vector<std::string>> features;
 
   // The following config options do not directly correspond to any
   // particualr command line options.
 
   // True if we are creating position-independent code.

lld/wasm/Driver.cpp

if (auto e = tryCreateFile(config->mapFile))
     error("cannot open map file " + config->mapFile + ": " + e.message());
   if (errorCount())
     return;
 
   // Handle --trace-symbol.
   for (auto *arg : args.filtered(OPT_trace_symbol))
     symtab->trace(arg->getValue());
 
-  for (auto *arg : args.filtered(OPT_export))
+  for (auto *arg : args.filtered(OPT_export_if_defined))
     config->exportedSymbols.insert(arg->getValue());
 
+  for (auto *arg : args.filtered(OPT_export)) {
+    config->exportedSymbols.insert(arg->getValue());
+    config->requiredExports.push_back(arg->getValue());
+  }
+
   createSyntheticSymbols();
 
   // Add all files to the symbol table. This will add almost all
   // symbols that we need to the symbol table.
   for (InputFile *f : files)
     symtab->addFile(f);
   if (errorCount())
     return;
 
   // Handle the `--undefined <sym>` options.
   for (auto *arg : args.filtered(OPT_undefined))
     handleUndefined(arg->getValue());
 
   // Handle the `--export <sym>` options
   // This works like --undefined but also exports the symbol if its found
-  for (auto *arg : args.filtered(OPT_export))
-    handleUndefined(arg->getValue());
+  for (auto &iter : config->exportedSymbols)
+    handleUndefined(iter.first());
 
   Symbol *entrySym = nullptr;
   if (!config->relocatable && !config->entry.empty()) {
     entrySym = handleUndefined(config->entry);
     if (entrySym && entrySym->isDefined())
       entrySym->forceExport = true;
     else
       error("entry symbol not defined (pass --no-entry to suppress): " +
void LinkerDriver::linkerMain(ArrayRef<const char *> argsArr) {
   symtab->handleSymbolVariants();
   if (errorCount())
     return;
 
   // Apply symbol renames for -wrap.
   if (!wrapped.empty())
     wrapSymbols(wrapped);
 
-  for (auto *arg : args.filtered(OPT_export)) {
-    Symbol *sym = symtab->find(arg->getValue());
+  for (auto &iter : config->exportedSymbols) {
+    Symbol *sym = symtab->find(iter.first());
     if (sym && sym->isDefined())
       sym->forceExport = true;
   }
 
   if (!config->relocatable && !config->isPic) {
     // Add synthetic dummies for weak undefined functions.  Must happen
     // after LTO otherwise functions may not yet have signatures.
     symtab->handleWeakUndefines();

lld/wasm/Options.td

 def allow_undefined_file: J<"allow-undefined-file=">,
   HelpText<"Allow symbols listed in <file> to be undefined in linked binary">;
 
 def allow_undefined_file_s: Separate<["-"], "allow-undefined-file">,
   Alias<allow_undefined_file>;
 
 defm export: Eq<"export", "Force a symbol to be exported">;
 
+defm export_if_defined: Eq<"export-if-defined",
+     "Force a symbol to be exported, if it is defined in the input">;
+
 def export_all: F<"export-all">,
   HelpText<"Export all symbols (normally combined with --no-gc-sections)">;
 
 def export_table: F<"export-table">,
   HelpText<"Export function table to the environment">;
 
 def growable_table: F<"growable-table">,
   HelpText<"Remove maximum size from function table, allowing table to grow">;

lld/wasm/Writer.cpp

if (!config->relocatable) {
     // This has to be done after memory layout is performed.
     for (const OutputSegment *seg : segments) {
       addStartStopSymbols(seg);
     }
   }
 
   // Delay reporting error about explict exports until after addStartStopSymbols
   // which can create optional symbols.
-  for (auto &entry : config->exportedSymbols) {
-    StringRef name = entry.first();
+  for (auto &name : config->requiredExports) {
     Symbol *sym = symtab->find(name);
     if (sym && sym->isDefined())
       sym->forceExport = true;
     else if (config->unresolvedSymbols == UnresolvedPolicy::ReportError)
       error(Twine("symbol exported via --export not found: ") + name);
     else if (config->unresolvedSymbols == UnresolvedPolicy::Warn)
       warn(Twine("symbol exported via --export not found: ") + name);
   }