[llvm] 0489222 - [llvm] get cl::opt instantiations working with MSVC DLL build (#147810)

[via llvm-commits]

Author: Andrew Rogers
Date: 2025-07-24T11:03:58-07:00
New Revision: 04892228b1125723666c0df874797c51e4620e50

URL: https://github.com/llvm/llvm-project/commit/04892228b1125723666c0df874797c51e4620e50
DIFF: https://github.com/llvm/llvm-project/commit/04892228b1125723666c0df874797c51e4620e50.diff

LOG: [llvm] get cl::opt instantiations working with MSVC DLL build (#147810)

## Purpose

This patch is one in a series of code-mods that annotate LLVM’s public
interface for export. This patch annotates the `llvm::cl::opt` explicit
template instantiations for export with `LLVM_TEMPLATE_ABI` and
`LLVM_EXPORT_TEMPLATE`. This annotation currently has no meaningful
impact on the LLVM build; however, it is a prerequisite to support an
LLVM Windows DLL (shared library) build.

## Background

This effort is tracked in #109483. Additional context is provided in
[this
discourse](https://discourse.llvm.org/t/psa-annotating-llvm-public-interface/85307),
and documentation for `LLVM_ABI` and related annotations is found in the
LLVM repo
[here](https://github.com/llvm/llvm-project/blob/main/llvm/docs/InterfaceExportAnnotations.rst).

Annotating the `llvm::cl::opt` template instances for DLL export was not
straight-forward like other explicit template instances that have
already been annotated. Annotating them as documented
[here](https://github.com/llvm/llvm-project/blob/main/llvm/docs/InterfaceExportAnnotations.rst#templates)
results in link errors when building a Windows DLL using MSVC.

## Overview 
There are two specific issues that appear when exporting the
`llvm::cl::opt` templates and compiling a Windows DLL with MSVC:
1. We cannot export `opt<std::string>`. This is because MSVC exports all
ancestor classes when exporting an instantiated template class. Since
one of `opt`'s ancestor classes is its type argument (via
`opt_storage`), it is an ancestor of `std::string`. Therefore, if we
export `opt<std::string>` from the LLVM DLL, MSVC forces
`std::basic_string` to also be exported. This leads to duplicate symbol
errors and generally seems like a bad idea. Compiling with `clang-cl`
does not exhibit this behavior.
2. The `opt` template instances other than `opt<bool>` get optimized out
because they are not referenced in the TU (`opt<bool>` actually is). It
is unclear exactly why MSVC optimizes these template instances away, but
`clang-cl` does not. Adding explicit references to the instantiated
`opt` template classes' vtables via implicit virtual destructor forces
MSVC to export them.

## Validation
Windows with MSVC
Windows with Clang

Added: 
    

Modified: 
    llvm/include/llvm/Support/CommandLine.h
    llvm/lib/Support/CommandLine.cpp

Removed: 
    


################################################################################
diff  --git a/llvm/include/llvm/Support/CommandLine.h b/llvm/include/llvm/Support/CommandLine.h
index adaa75cc6c348..ca725b8ac8712 100644
--- a/llvm/include/llvm/Support/CommandLine.h
+++ b/llvm/include/llvm/Support/CommandLine.h
@@ -1518,11 +1518,18 @@ class opt
       [](const typename ParserClass::parser_data_type &) {};
 };
 
-extern template class opt<unsigned>;
-extern template class opt<int>;
-extern template class opt<std::string>;
-extern template class opt<char>;
-extern template class opt<bool>;
+#if !(defined(LLVM_ENABLE_LLVM_EXPORT_ANNOTATIONS) && defined(_MSC_VER))
+// Only instantiate opt<std::string> when not building a Windows DLL. When
+// exporting opt<std::string>, MSVC implicitly exports symbols for
+// std::basic_string through transitive inheritance via std::string. These
+// symbols may appear in clients, leading to duplicate symbol conflicts.
+extern template class LLVM_TEMPLATE_ABI opt<std::string>;
+#endif
+
+extern template class LLVM_TEMPLATE_ABI opt<unsigned>;
+extern template class LLVM_TEMPLATE_ABI opt<int>;
+extern template class LLVM_TEMPLATE_ABI opt<char>;
+extern template class LLVM_TEMPLATE_ABI opt<bool>;
 
 //===----------------------------------------------------------------------===//
 // Default storage class definition: external storage.  This implementation

diff  --git a/llvm/lib/Support/CommandLine.cpp b/llvm/lib/Support/CommandLine.cpp
index d5c3cba13e030..8491633df97e8 100644
--- a/llvm/lib/Support/CommandLine.cpp
+++ b/llvm/lib/Support/CommandLine.cpp
@@ -68,11 +68,19 @@ template class LLVM_EXPORT_TEMPLATE basic_parser<float>;
 template class LLVM_EXPORT_TEMPLATE basic_parser<std::string>;
 template class LLVM_EXPORT_TEMPLATE basic_parser<char>;
 
-template class opt<unsigned>;
-template class opt<int>;
-template class opt<std::string>;
-template class opt<char>;
-template class opt<bool>;
+#if !(defined(LLVM_ENABLE_LLVM_EXPORT_ANNOTATIONS) && defined(_MSC_VER))
+// Only instantiate opt<std::string> when not building a Windows DLL. When
+// exporting opt<std::string>, MSVC implicitly exports symbols for
+// std::basic_string through transitive inheritance via std::string. These
+// symbols may appear in clients, leading to duplicate symbol conflicts.
+template class LLVM_EXPORT_TEMPLATE opt<std::string>;
+#endif
+
+template class LLVM_EXPORT_TEMPLATE opt<bool>;
+template class LLVM_EXPORT_TEMPLATE opt<char>;
+template class LLVM_EXPORT_TEMPLATE opt<int>;
+template class LLVM_EXPORT_TEMPLATE opt<unsigned>;
+
 } // namespace cl
 } // namespace llvm
 
@@ -95,6 +103,15 @@ void parser<float>::anchor() {}
 void parser<std::string>::anchor() {}
 void parser<char>::anchor() {}
 
+// These anchor functions instantiate opt<T> and reference its virtual
+// destructor to ensure MSVC exports the corresponding vtable and typeinfo when
+// building a Windows DLL. Without an explicit reference, MSVC may omit the
+// instantiation at link time even if it is marked DLL-export.
+void opt_bool_anchor() { opt<bool> anchor{""}; }
+void opt_char_anchor() { opt<char> anchor{""}; }
+void opt_int_anchor() { opt<int> anchor{""}; }
+void opt_unsigned_anchor() { opt<unsigned> anchor{""}; }
+
 //===----------------------------------------------------------------------===//
 
 const static size_t DefaultPad = 2;