Looking for an out-of-source "Hello, world" LLVM/Clang pass example

Project Infrastructure LLVM Dev List Archives
1

I'm looking for a "Hello, world" pass example that ideally has all of
the following properties:

  1) Complete. That is, it should have functional CMakeLists.txt,
     etc. files.

  2) Out-of-source. That is, it should build against a binary LLVM
     installation.

  3) Modern. That is, I don't want to use any deprecated APIs or
     CMake macros.

  4) Clang-compatible. That is, I'd like the pass to be able to run
     directly from Clang instead of having to generate bitcode, run
     opt on it, and then feed it back to Clang for linking.

Does such an example exist and if so, where can I find it?

Here's what I've considered to date:

  * llvm/lib/Transforms/Hello, but this appears to be in-source only.

  * http://llvm.org/docs/WritingAnLLVMPass.html, but this example
    doesn't appear to be runnable directly from Clang.

  * Building LLVM with CMake — LLVM 16.0.0git documentation, but its proposed CMake line of
    "add_llvm_library(LLVMPassname MODULE Pass.cpp)" blows up with

      CMake Error at /usr/local/lib/cmake/llvm/AddLLVM.cmake:659 (install):
        install TARGETS given no LIBRARY DESTINATION for module target
"Hello".
      Call Stack (most recent call first):
        Hello/CMakeLists.txt:3 (add_llvm_library)

    (Perhaps this is fixable with additional CMake macro calls, but
    that's what I list "Complete" as a desideratum.)

2

Hi,

3

Florian,

Adrian Sampson: LLVM for Grad Students describes how to
create an out-of-source pass (see 'Let’s Write a Pass’). I think it
is for LLVM 3.8 though.

Thanks for pointing that out. I had actually recently stumbled across
that page (and the GitHub repository it references,
GitHub - sampsyo/llvm-pass-skeleton: example LLVM pass) while searching for an
answer to my questions but wasn't sure how up-to-date the information
is:

  * Is add_library the currently recommended CMake macro call for
    building an LLVM pass?
    Writing an LLVM Pass — LLVM 18.0.0git documentation and
    Building LLVM with CMake — LLVM 18.0.0git documentation both point to add_llvm_library,
    which I couldn't get to work.

  * Is the legacy pass manager still the right way to make a pass
    Clang-callable? There's a currently active thread on this list,
    "Status of the New Pass Manager", that makes me think I have some
    code-rewriting in my future.

-- Scott

4

Scott,

This is still very early stages, but you can be my guinea pig:

It's a tutorial that I've been preparing recently and am hoping to
present somewhere at some point :slight_smile: I believe that it already covers 1),
2) and 3). I haven't had the time to work on 4). It's based on LLVM-8
and includes a working CI set-up, so that you can be confident that it
works. If it doesn't, ping me - I'm keen on improving it.

-- Andrzej

5

Andrzej,

This is still very early stages, but you can be my guinea pig:

GitHub - banach-space/llvm-tutor: A collection of out-of-tree LLVM passes for teaching and learning

It's a tutorial that I've been preparing recently and am hoping to
present somewhere at some point :slight_smile: I believe that it already covers 1),
2) and 3). I haven't had the time to work on 4). It's based on LLVM-8
and includes a working CI set-up, so that you can be confident that it
works. If it doesn't, ping me - I'm keen on improving it.

Cool, thanks. I just started reading over that now. I have a couple
of questions already, if you don't mind:

1) I see you're building the pass with

    add_library(lt-cc-static STATIC StaticCallCounter.cpp
DynamicCallCounter.cpp)
    add_library(lt-cc-shared MODULE StaticCallCounter.cpp
DynamicCallCounter.cpp)

  What's the reason for building a STATIC version? Does any LLVM tool
  make use of that?

  Is add_library the preferred pass-building CMake macro these days,
  as opposed to add_llvm_library or add_llvm_loadable_module?

2) How is the user supposed to install the generated files? Neither
   "make install" nor "cmake --target=install" seem to work.

-- Scott

6

This review https://reviews.llvm.org/D61446 tries hard to address your needs: it makes it possible to register a pass withing clang/opt/bugpoint with a dedicated cmake function call. The pass can then behave as a loadable plugin or be linked statically to LLVM (depending on cmake options), and the code can live out-of-tree, much like polly.

7

Hi Scott,

This is useful feedback for me, thanks! As you've noticed, that project
is Work In Progress, which has been on hold for a while. I'm about to
get back to it, and you've already given me some good hints as what to
improve.

My replies inline.

Andrzej,

This is still very early stages, but you can be my guinea pig:

GitHub - banach-space/llvm-tutor: A collection of out-of-tree LLVM passes for teaching and learning

It's a tutorial that I've been preparing recently and am hoping to
present somewhere at some point :slight_smile: I believe that it already covers 1),
2) and 3). I haven't had the time to work on 4). It's based on LLVM-8
and includes a working CI set-up, so that you can be confident that it
works. If it doesn't, ping me - I'm keen on improving it.

Cool, thanks. I just started reading over that now. I have a couple
of questions already, if you don't mind:

1) I see you're building the pass with

     add_library(lt-cc-static STATIC StaticCallCounter.cpp
DynamicCallCounter.cpp)
     add_library(lt-cc-shared MODULE StaticCallCounter.cpp
DynamicCallCounter.cpp)

   What's the reason for building a STATIC version? Does any LLVM tool
   make use of that?

Good catch - I honestly don't remember. Let me check that and I'll get
back to you.

   Is add_library the preferred pass-building CMake macro these days,
   as opposed to add_llvm_library or add_llvm_loadable_module?

My motivation was to make it as standalone and basic as possible.
add_library was sufficient and that's what I used.

2) How is the user supposed to install the generated files? Neither
    "make install" nor "cmake --target=install" seem to work.

I have not considered that at all. Added to my TODO list.

-- Scott

-- Andrzej
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

8

Thanks. I had looked at Polly in the past. I guess I should take
another look now that I more clearly know what I'm looking for.

-- Scott