Description: API notes are a YAML-based “sidecar” file mechanism in Clang that allows users to add attributes to existing headers without modifying the header files themselves. This is particularly useful for Swift developers who want to annotate third-party C/C++ libraries and frameworks for better interoperability. However, API notes have limited support for C++ syntax (e.g., type conversion operators), and cannot annotate specific function overloads or template instantiations.
Expected result: Extend API notes to better support C++ language features.
Desirable skills: Intermediate C++, familiarity or experience with compiler development
Project size: Small or Medium, depending on scope of the proposal
Not necessarily. At the moment, Swift interop seems to be the most common use case of API notes, but this mechanism can be used for attaching attributes for any purpose.
I think API notes are also used to attach nullability attributes like _Nonnull and friends for use by the Clang static analyzer, though I don’t have personal experience with this; @Xazax-hun might have more context on that use case.
Yup, we have some clang static analyzer checks that take advantage of these attributes. It looks like we have not documented this yet but some lifetime annotations can also be applied via APINotes, so there are also some clang (on by default) warnings that can benefit from these notes.
This is a clang tools, right? then how is swift involved? considering clang does not compile swift code.
The thing I want to know is: if I am developing a swift app, does this tool allow me to link to a clang library? or is it the other way around? (clang app link to swift library)
A good fundamentals resource about language interoperability would be nice
This is part of the Clang compiler. (We often refer to clang-format or other utilities as clang tools, but APINotes is part of the main clang binary.)
then how is swift involved?
Clang is not just a compiler but designed to be a collection of libraries. Swift is heavily using Clang as a library for interoperability between C family languages and Swift. The Swift compiler can parse C/C++/Obj-C header files to make those declarations available for Swift code.
if I am developing a swift app, does this tool allow me to link to a clang library? or is it the other way around? (clang app link to swift library)
The Swift compiler already links with Clang. App developers do not need to do anything extra. These features supported and on by default in the released Swift toolchain.
A good fundamentals resource about language interoperability would be nice
One could complete this project without ever touching the Swift compiler or the language interoperability. APINotes are a core part of Clang and can be used/tested without using Swift.
That being said, if you want to learn more about interop, there are a couple of talks on them at some LLVM Dev conferences, like https://www.youtube.com/watch?v=2g-fQd_OYUU
I’m interested in helping expand the Clang API Notes as part of GSoC 2026.
I’ve been exploring the use of API Notes with Swift, following Doug Gregor’s blog post, and experimenting with the test demo from the documentation.
After learning about the use cases of API Notes and experimenting with them, I wanted to learn more about the project.
I have a few questions:
Recommended clang command to show and verify the output? (I’ve been using xcrun swift-synthesize-interface but I’m not sure if that’s the best approach.
What are the recommended features that have the highest priority for the project so we can start discussing how to implement them?
Is there anything you would recommend to help me become more familiar with the API Notes code (for example, good first issues)?
Your preferred communication channel (here, discord, personal/work email)?
I would appreciate your guidance on the next steps.
Recommended clang command to show and verify the output? (I’ve been using xcrun swift-synthesize-interface but I’m not sure if that’s the best approach.
You do not need Swift to test APINotes. I recommend looking at the APINotes regression tests. Note that you need clang modules for APINotes to work and we use the AST dumps to check if the attributes from the APINotes are properly applied.
What are the recommended features that have the highest priority for the project so we can start discussing how to implement them?
I’d say supporting overloads. But others might have different opinions.
You could look at previous patches to that area to get a feel what it is like to work with APINotes. I don’t think we have a list of good first issues just yet, but you could look around in the codebase if there are any FIXME comments. On potential idea I can think of, not too long ago we added lifetimebound annotation support to APInotes. But we lack documentation. Documenting it is a realtively easy task. One step up would be adding lifetime_capture_by support.
I think here would work the best for now. If/when the project is accepted, it is very likely we would need to set up some weekly calls.
I’m also very interested in this project and have been exploring the current API Notes implementation, building Clang locally and running the regression tests to better understand how everything fits together.
Since overload support was mentioned as a high-priority area, I’ve been looking at how C++ methods are currently matched. From reading the implementation and tests, it appears that C++ method lookup is keyed by (record context, name), without parameter-type disambiguation. For overload-specific annotations, is the intended direction to extend the lookup key with signature information (for example parameter types including cv/ref qualifiers and possibly template arguments), or is there another mechanism envisioned for uniquely identifying overloads?
Additionally, since the description also mentions type conversion operators and template instantiations, would overload support be the first milestone to focus on before tackling those, or are they expected to be addressed together?
I would imagine overload resolution has to specify the type signature when there are multiple decls with the same name, yeah. API notes are usually used when modifying the header is not an option, so it has to be able to be completely standalone.
Overload support should be entirely doable before addressing other issues. In general the LLVM project prefers small, iterative patches over large ones, even when the desired end goal is known ahead of time.
My name is Mafe, and I`m a Master`s student researching compiler optimization.
I found the “Expanding API Notes for C++” project very interesting, especially the challenge of working with the Clang AST to support complex features like overloads. I`m already familiar with the LLVM ecosystem and contribution workflow, as I currently work with MLIR and have contributed optimization passes (such as vectorization) upstream to the CIRCT project.
I have already built Clang locally, and I`m running the regression tests to understand how the API Notes are currently implemented.
@Xazax-hun Thank you for the tips on how to get started. I will follow your advice, look at previous patches in this area, and search for FIXMEs in the codebase to get a better feel for it.
Following up on your tip, I started looking for FIXMEs in the APINotes codebase. I found 54 FIXMEs in APINotesReader.cpp stating: // FIXME this drops the error on the floor.
Looking at the code, it seems this happens because the internal read*Block methods return a bool, and the APINotesReader constructor reports failures via a bool &Failed out-parameter. This forces the actual llvm::Errors from the bitstream cursor to be silently consumed with consumeError().
Would refactoring this be a good first patch?
I was thinking that a way to fix this would be:
Change the read*Block methods to return llvm::Error instead of bool.
Make the APINotesReader constructor private.
Create a static factory method (e.g., APINotesReader::Create(…)) that returns an llvm::Expectedstd::unique_ptr, allowing us to propagate the error up the stack instead of dropping it.
Hi everyone, I’m Aditya, a pre-final year CSE undergrad with a strong interest in compilers and systems.
I also work as an iOS developer. Last year I won the Swift Student Challenge for building an educational app around lambda calculus, where I implemented a small lambda-calculus interpreter in Swift. That project pushed me to think deeply about language design and semantics.
API Notes caught my attention because I’ve come across them in practice as an iOS developer. Seeing how they improve C/C++ interop in Swift without requiring upstream changes made me curious about how that mechanism is implemented internally. I’ve been studying the workflow and implementation over the past week to better understand how notes are parsed, validated, and applied during import.
I’ve opened PR #183811 (NFC changes) to get familiar with the contribution flow, and I’m currently working on issue #183340 while reading through the relevant upstream logic before proposing a fix.
Looking forward to discussing more with everyone here!
I am Pramodh s, currently a 6th semester CS student . I’ve been into systems programming and linux for a while now and C++ is my primary language.
I came across this project through the gsoc 2026 idea list . I spent some time exploring the apinotes codebase clang/lib/APINotes and clang/include/clang/APINotes/Types.h to understand the current data structures and where C++ overload and template support is missing.
I also have some background in compiler concepts — I built a small language from scratch during college which gave me hands-on exposure to lexing, parsing and AST construction.
A couple of questions that could help me with my proposal-
-Which C++ features would you prioritize for a Small vs Medium proposal?
-Is there a specific area in Types.h or the YAML compiler you’d recommend starting with?
looking forward to learn some new things from everyone in here.
