Writing LLVM Pass in 2018 — Preface

TL;DR: Official tutorial still works, but it have been outdated for a long long time

You have written a HelloWorld pass by following the official tutorial …

And now, you want to learn more, see more…

So you dive in the wonderful LLVM source tree, to see how those famous and powerful optimizations are written in passes…

But turns out being confused by the exotic pass construction syntax that is neither similar to the tutorial you just followed, nor documented in any place in the official website — That’s exactly what I was bumping into few years ago, when I was still a LLVM newbie and LLVM pass is the only thing I heard before then.

As one of the most important core components in LLVM, Pass and PassManager system started their makeover dated back to 2014, motivated by many missing optimization opportunities cases and compilation speed regressions. The entire codebase also started to reflect these changes by placing old pass and new pass implementations side-by-side. Users could switch to the new pass manager by providing specific command line options while the old pass manager is still the default.

However, just as the preface section point out, there is currently no official documents telling about this innovation. Though as the new pass manager ,and its document page, are getting really closed to their shipping date, I still want to write a simple tutorial for those enthusiasts who’s eager to know what’s happening now in the source tree. I divide this series into four parts:

1. Part I (Link): Write a new HelloWorld Pass in new pass manager fashion.
2. Part II (Link): How to use the new AnalysisManager to replace the old getAnalysis<...>() syntax.
3. Part III (Link): How passes are integrated inside LLVM source tree. Spoiler: (Old) Passes inside LLVM source tree requires some extra syntax, this would tell you how. I know it’s a little bit strange to talk about legacy pass manager in an article titled new pass manager. But considering the huge project size of LLVM and its wide adoptions in industries, it would definitely take some time on the migration. So just thinking about this part as a delayed(for nearly a decade, actually) tutorial for those interested in in-tree development.
4. Part IV (Link): “How do I add a clang option to use my cool feature built inside LLVM?”. Well, this part would tell you how. Though it seems to be orthogonal to the new pass manager topic in previous episodes, it’s always one of my “Tutorials/Hints that should be officially-documented”. So here you go.

I will not talk about the design details, like how do the new pass manager improve compilation speed and optimization quality in comparison to the old one. The new pass manager revolution is leaded by some of the best developers in the LLVM community, you should definitely heard their explanation(instead of mine) in related materials(e.g. Talks in LLVM developers meeting). I would go through the story from the perspective of a pass manager user who is focusing on middle-end optimization and analyses development. So there would be no covering on the back-end side.

In addition, you should always checkout LLVM mailing list and the comment in the source code. Information in these places might be scattered, but they’re always up-to-date.