Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -687,7 +687,7 @@ Structs, enums and `extern "C"` functions are emitted, and polymorphic classes (

#### C++ classes

A polymorphic class (one with virtual methods), in any namespace, becomes a [`@cpp` class](docs/cpp-classes.md): tslang calls its virtual methods through the object's vtable and its non-virtual methods by their mangled symbols, with no wrapper. clang computes the slots and the symbols for the target's ABI (`--target`), so generate the bindings once per ABI: MSVC and the Itanium ABI (Linux, Android) number the slots differently.
A polymorphic class (one with virtual methods), in any namespace, becomes a [`@cpp` class](docs/cpp-classes.md): tslang calls its virtual methods through the object's vtable and its non-virtual methods by their C++ declarations (`@cppname`, which tslang mangles for the target it compiles for), with no wrapper. clang computes the slots for the target's ABI (`--target`), so generate the bindings once per ABI: MSVC and the Itanium ABI (Linux, Android) number the slots differently. A non-virtual method `@cppname` can't spell (a function pointer or a template in its signature) is bound by the target's mangled symbol, `@linkname`, instead.

```cpp
namespace geo {
Expand Down Expand Up @@ -717,7 +717,7 @@ class Shape { // geo::Shape
@slot(2) scale(by: f64): void;
@cppnontrivial
@slot(4) handle(): [p: Opaque | null];
@linkname("?id@Shape@geo@@QEAAHH@Z") id(x: s32): s32;
@cppname("int geo::Shape::id(int)") id(x: s32): s32;
}
@cpp
class Square extends Shape { // geo::Square
Expand Down
5 changes: 3 additions & 2 deletions docs/cpp-classes.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,9 @@ counts it:

## Writing a binding

`tsbindgen` writes the binding from the C++ header, with the slots, the mangled symbols and the
`@cppnontrivial` marks clang computes for the target (README, "C++ classes"):
`tsbindgen` writes the binding from the C++ header, with the slots and the `@cppnontrivial` marks
clang computes for the target, and each non-virtual method's `@cppname` declaration (its
`@linkname` symbol when `@cppname` can't spell it or mangles it otherwise) (README, "C++ classes"):
`tsbindgen nvrhi.hpp --target x86_64-pc-windows-msvc --filter 'nvrhi::I*' -- -std=c++17`.
Writing one by hand:

Expand Down
6 changes: 5 additions & 1 deletion tslang/include/TsClangImporter/BindingModel.h
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ enum class DeclKind
Enum, // enum E { A = 0 }
FixedEnum, // type E = u8; const A = 1;
Typedef, // type T = ...;
CppClass, // @cpp class C extends B { @slot(N) f(...): R; @linkname("...") g(...): R; }
CppClass, // @cpp class C extends B { @slot(N) f(...): R; @cppname("R C::g(...)") g(...): R; }
Function // declare function f(...): R;
};

Expand All @@ -92,6 +92,10 @@ struct Method
std::string cppName; // the C++ name, for messages
int slot = -1; // a virtual method's vtable slot; -1 for a non-virtual one
std::string symbol; // a non-virtual method's mangled symbol
// a non-virtual method's C++ declaration, `int32_t ns::C::id(int32_t) const`, for @cppname to
// mangle for any target; empty when @cppname can't spell it or mangles it to another symbol than
// `symbol`, which @linkname binds instead
std::string cppDeclaration;
std::vector<Field> parameters;
TsType result;
bool nonTrivialReturn = false; // returns a record with a destructor or a copy constructor
Expand Down
6 changes: 5 additions & 1 deletion tslang/lib/TsClangImporter/BindingPrinter.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -305,8 +305,12 @@ llvm::Expected<PrintResult> printBindings(const HeaderModel &model, const PrintO
member("@cppnontrivial");
}

// a non-virtual method by its C++ declaration, which @cppname mangles for the
// target compiled for; by this target's symbol when it can't be spelled so
auto decorator = method.slot >= 0 ? "@slot(" + std::to_string(method.slot) + ") "
: "@linkname(\"" + method.symbol + "\") ";
: method.cppDeclaration.empty()
? "@linkname(\"" + method.symbol + "\") "
: "@cppname(\"" + method.cppDeclaration + "\") ";
member(decorator + method.name + "(" + parameters + "): " + renderType(method.result, nameOf) + ";");
}

Expand Down
4 changes: 4 additions & 0 deletions tslang/lib/TsClangImporter/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,17 @@
# wrapper generation is meant to reuse it. It links clang's frontend; tslang itself does not.
set(LLVM_LINK_COMPONENTS
Support
TargetParser
)

add_llvm_library(TsClangImporter
BindingModel.cpp
TypeMapper.cpp
HeaderParser.cpp
BindingPrinter.cpp
# tslang's @cppname mangler (LLVM-only, no MLIR), to check that the declaration a binding carries
# mangles to clang's symbol; tslang and TsClangImporter are never linked together
../TypeScript/CppMangler.cpp

LINK_LIBS
clangTooling
Expand Down
247 changes: 247 additions & 0 deletions tslang/lib/TsClangImporter/HeaderParser.cpp
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
#include "TsClangImporter/HeaderParser.h"
#include "TsClangImporter/TypeMapper.h"
#include "TypeScript/CppMangler.h"

#include "clang/AST/ASTConsumer.h"
#include "clang/AST/DeclCXX.h"
#include "clang/AST/DeclTemplate.h"
#include "clang/AST/GlobalDecl.h"
#include "clang/AST/Mangle.h"
#include "clang/AST/RecordLayout.h"
Expand All @@ -28,6 +30,8 @@
#include "llvm/Support/MemoryBuffer.h"
#include "llvm/Support/VirtualFileSystem.h"

#include <optional>

namespace tsbindgen
{

Expand Down Expand Up @@ -74,6 +78,230 @@ std::string escapeString(llvm::StringRef text)
return escaped + "\"";
}

// The name of a record or enum with its namespaces and enclosing classes (`ns::Outer::Inner`), as
// @cppname reads it. An inline namespace is spelled too: both schemes mangle it. Nothing for what
// @cppname can't name: an anonymous namespace or record, a template's specialization or a member of
// one, a function's local type.
std::optional<std::string> cppQualifiedName(const clang::NamedDecl *decl)
{
std::vector<std::string> parts;
for (const clang::DeclContext *context = llvm::cast<clang::DeclContext>(decl); !context->isTranslationUnit();
context = context->getParent())
{
if (llvm::isa<clang::LinkageSpecDecl>(context))
{
continue; // extern "C++" { ... }
}

auto *named = llvm::dyn_cast<clang::NamedDecl>(context);
if (!named || !named->getIdentifier() || llvm::isa<clang::ClassTemplateSpecializationDecl>(context) ||
!(llvm::isa<clang::NamespaceDecl, clang::RecordDecl, clang::EnumDecl>(context)))
{
return std::nullopt;
}

parts.insert(parts.begin(), named->getName().str());
}

return llvm::join(parts, "::");
}

std::optional<std::string> cppBuiltinName(const clang::BuiltinType *builtin)
{
switch (builtin->getKind())
{
case clang::BuiltinType::Void:
return "void";
case clang::BuiltinType::Bool:
return "bool";
case clang::BuiltinType::Char_S:
case clang::BuiltinType::Char_U:
return "char";
case clang::BuiltinType::SChar:
return "signed char";
case clang::BuiltinType::UChar:
return "unsigned char";
case clang::BuiltinType::WChar_S:
case clang::BuiltinType::WChar_U:
return "wchar_t";
case clang::BuiltinType::Char8:
return "char8_t";
case clang::BuiltinType::Char16:
return "char16_t";
case clang::BuiltinType::Char32:
return "char32_t";
case clang::BuiltinType::Short:
return "short";
case clang::BuiltinType::UShort:
return "unsigned short";
case clang::BuiltinType::Int:
return "int";
case clang::BuiltinType::UInt:
return "unsigned int";
case clang::BuiltinType::Long:
return "long";
case clang::BuiltinType::ULong:
return "unsigned long";
case clang::BuiltinType::LongLong:
return "long long";
case clang::BuiltinType::ULongLong:
return "unsigned long long";
case clang::BuiltinType::Float:
return "float";
case clang::BuiltinType::Double:
return "double";
case clang::BuiltinType::LongDouble:
return "long double";
default:
return std::nullopt; // __int128, _Float16, nullptr_t, ...
}
}

// `type` as @cppname reads it (CppMangler.h): a builtin, a <stdint.h>/<stddef.h> typedef as written
// - it mangles as whatever the target @cppname is compiled for defines it as - or a record or enum by
// its qualified name and tag (`class X`, `union U`, `enum E`; a bare name is a struct), with
// `const`/`volatile`, `*`, `&` and `&&`. Nothing for anything else: an array, a function pointer, a
// template's specialization, ...
std::optional<std::string> cppTypeSpelling(clang::QualType type)
{
clang::Qualifiers qualifiers;
std::string base;
for (;;)
{
qualifiers.addQualifiers(type.getLocalQualifiers());
auto *bare = type.getTypePtr();
if (auto *typedefType = llvm::dyn_cast<clang::TypedefType>(bare))
{
auto name = typedefType->getDecl()->getName();
if (llvm::is_contained({"int8_t", "uint8_t", "int16_t", "uint16_t", "int32_t", "uint32_t", "int64_t",
"uint64_t", "size_t", "ptrdiff_t", "intptr_t", "uintptr_t"},
name))
{
base = name.str();
break;
}
}

auto desugared = bare->getLocallyUnqualifiedSingleStepDesugaredType();
if (desugared.getTypePtr() == bare && !desugared.hasLocalQualifiers())
{
break;
}

type = desugared;
}

if (qualifiers.hasRestrict() || qualifiers.hasAddressSpace() || qualifiers.hasObjCLifetime() ||
qualifiers.hasUnaligned())
{
return std::nullopt;
}

auto cv = std::string(qualifiers.hasConst() ? "const" : "") +
(qualifiers.hasConst() && qualifiers.hasVolatile() ? " " : "") +
(qualifiers.hasVolatile() ? "volatile" : "");
auto *bare = type.getTypePtr();
if (base.empty())
{
auto pointer = [&](clang::QualType pointee, const char *declarator) -> std::optional<std::string> {
auto inner = cppTypeSpelling(pointee);
if (!inner)
{
return std::nullopt;
}

return *inner + declarator + (cv.empty() ? "" : " " + cv);
};

if (auto *pointerType = llvm::dyn_cast<clang::PointerType>(bare))
{
return pointer(pointerType->getPointeeType(), "*");
}

if (auto *reference = llvm::dyn_cast<clang::LValueReferenceType>(bare))
{
return pointer(reference->getPointeeType(), "&");
}

if (auto *reference = llvm::dyn_cast<clang::RValueReferenceType>(bare))
{
return pointer(reference->getPointeeType(), "&&");
}

if (auto *builtin = llvm::dyn_cast<clang::BuiltinType>(bare))
{
auto name = cppBuiltinName(builtin);
if (!name)
{
return std::nullopt;
}

base = *name;
}
else if (auto *tag = llvm::dyn_cast<clang::TagType>(bare))
{
auto *decl = tag->getDecl();
auto name = cppQualifiedName(decl);
if (!name)
{
return std::nullopt;
}

switch (decl->getTagKind())
{
case clang::TagTypeKind::Struct:
base = *name;
break;
case clang::TagTypeKind::Class:
base = "class " + *name;
break;
case clang::TagTypeKind::Union:
base = "union " + *name;
break;
case clang::TagTypeKind::Enum:
base = "enum " + *name;
break;
default:
return std::nullopt; // __interface
}
}
else
{
return std::nullopt;
}
}

return cv.empty() ? base : cv + " " + base;
}

// A method's declaration as @cppname takes it, its name qualified with its class's (the TS class
// can be named otherwise: --strip-prefix, a namespace, ...), or nothing when a type can't be spelled
std::optional<std::string> cppMethodDeclaration(const clang::CXXMethodDecl *method)
{
auto *prototype = method->getType()->getAs<clang::FunctionProtoType>();
auto className = cppQualifiedName(method->getParent());
auto result = cppTypeSpelling(method->getReturnType());
if (!prototype || !className || !result || method->getRefQualifier() != clang::RQ_None)
{
return std::nullopt;
}

std::string parameters;
for (auto parameter : prototype->getParamTypes())
{
auto spelled = cppTypeSpelling(parameter);
if (!spelled)
{
return std::nullopt;
}

parameters += (parameters.empty() ? "" : ", ") + *spelled;
}

return *result + " " + *className + "::" + method->getName().str() + "(" + parameters + ")" +
(method->isConst() ? " const" : "") + (method->isVolatile() ? " volatile" : "");
}

// An object-like macro's value as a TS literal: an integer, a float or a string, optionally
// negated and parenthesized. "" for anything else.
std::string literalValue(clang::Preprocessor &preprocessor, llvm::ArrayRef<clang::Token> tokens)
Expand Down Expand Up @@ -712,6 +940,25 @@ class Collector : public clang::RecursiveASTVisitor<Collector>
if (bound.result.skipped())
{
bound.skipReason = "result: " + bound.result.skipReason;
return;
}

// bound by its declaration when @cppname, mangling it for this target, gives clang's symbol:
// the same binding then links on every other target too
if (!method->isVirtual())
{
if (auto declaration = cppMethodDeclaration(method))
{
CppMangleContext mangleContext;
mangleContext.isInstanceMethod = true;
std::string symbol;
std::string error;
if (mangleCppName(*declaration, context.getTargetInfo().getTriple(), mangleContext, symbol, error) &&
symbol == bound.symbol)
{
bound.cppDeclaration = std::move(*declaration);
}
}
}
}

Expand Down
2 changes: 1 addition & 1 deletion tslang/test/bindgen/bindgen_cpp_test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ function main() {
print(pair.a, pair.b);
const handle = shape.handle(); // a non-trivial one (@cppnontrivial)
print(handle.p == <Opaque>shape);
print(shape.id(5)); // a non-virtual method, by its mangled symbol
print(shape.id(5)); // a non-virtual method, by its C++ declaration (@cppname)
let extent: Extent = [3, 4]; // fx::Extent, a struct in a namespace: a tuple
print(shape.fits(Ref(extent), null), shape.fits(Ref(extent), Ref(extent))); // a reference, a pointer or null

Expand Down
4 changes: 2 additions & 2 deletions tslang/test/bindgen/fixture_cpp.hpp
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// A C++ library for tsbindgen's @cpp classes (run-bindgen-test.cmake, MODE=cpp): its polymorphic
// classes become @cpp classes, called through their vtables and by their mangled symbols.
// classes become @cpp classes, called through their vtables and by their C++ declarations.
//
// No C++ runtime is needed to link it: no destructors, pure virtual methods, RTTI or exceptions, and
// its objects are constant-initialized (constexpr constructors), so a tslang program links its object
Expand Down Expand Up @@ -100,7 +100,7 @@ class FX_API Shape
virtual int32_t fits(const Extent &extent, const Extent *limit);
virtual int32_t sum(const Batch &batch);

// non-virtual: called by its mangled symbol
// non-virtual: called by its declaration, @cppname("int32_t fx::Shape::id(int32_t)")
int32_t id(int32_t x);

int64_t sides; // 8 bytes: no tail padding, which the Itanium ABI would put `side` in
Expand Down
2 changes: 1 addition & 1 deletion tslang/test/bindgen/run-bindgen-test.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
# print expected.txt. MODE=namespace does the same through `--namespace Fx --strip-prefix fx_`,
# which only links because @linkname binds each renamed function to its C symbol. MODE=cpp does it
# for fixture_cpp.hpp's C++ classes, which become @cpp classes: their virtual methods called through
# the vtable the host's clang made, their non-virtual ones by their mangled symbols.
# the vtable the host's clang made, their non-virtual ones by their declarations (@cppname).

cmake_minimum_required(VERSION 3.17.3)

Expand Down
Loading
Loading