RFC: Adding IR Transformation examples/tutorial code to llvm-project

Hi,

I’d like to propose adding a new example directory (llvm/examples/IRTransforms) as a new home for example code used by various tutorials. After talking to a few people at the Developers meeting, it became clear to me that it would be valuable to have the code examples for various tutorials in-tree to keep them from bit-rotting and make it very easy to build them.

I’d suggest adding new IR pass examples to llvm/examples/IRTransforms. The passes in that directory will be built as an ExamplesIRTransforms library, which exposes initializeExampleIRTransforms to initialise the passes. Additionally, if LLVM_BUILD_EXAMPLES=On, we add a -DBUILD_EXAMPLES define, which is then used in opt to make the example passes available if LLVM_BUILD_EXAMPLES=On. I think that allows for relatively friction-less integration of the example passes into `opt`.

I’ve put up a patch doing exactly that: https://reviews.llvm.org/D69416 and added a few reviewers, but please join in if you have any thoughts!

Please let me know if you have any concerns or suggestions to improve the CMake setup & co.

As initial example, it contains the code we used for the IR transformations in the 'Getting Started With LLVM: Basics’ tutorial.

I think there were other tutorials with examples that would be great to have there, like 'Writing Loop Optimizations in LLVM’.

As a second step, to make those examples even more valuable, it would be great to provide an accompanying text version of the tutorials. But I would suggest we start with adding the code, which we already have.

Cheers,
Florian

Sounds good - bonus points if these examples were motivated with a continuation to the Kaleidoscope tutorial - Eric Christopher and I did a tutorial on debug info back in 2014 and included new chapters for Kaleidoscope for future usage.

What Dave said :slight_smile:

Even if the tutorial code and descriptions are in a different
directory because reasons it'd be good to get it checked in where we
can have things updated automatically.

-eric

I like the idea and already discussed it with Kit Barton.

Two concerns that I had:

1. Keeping them in-tree requires them to be up-to-date, a potential
additional maintenance burden. This might be what we want, but I get
less enthusiastic when thinking about maintaining all tutorials ever
given at any conference during the last xx years without having gone
through a review process.

2.Chris Bieneman seeks to simplify the cmake build system, including
significantly reducing the number of configuration parameters and
making "make all" really make everything, including examples. This
would make the overall configure process slower even when not
interested in the tutorials.

Michael

I like the idea and already discussed it with Kit Barton.

Two concerns that I had:

  1. Keeping them in-tree requires them to be up-to-date, a potential
    additional maintenance burden. This might be what we want, but I get
    less enthusiastic when thinking about maintaining all tutorials ever
    given at any conference during the last xx years without having gone
    through a review process.

As with any code in the codebase, yeah, pre or post commit review seems good & if they end up bitrotting/becoming less relevant/diverge significantly from the tutorial content (written, video, whatever there is) I think it’s fine to delete them. Same as we’d do with tests. (I think they’re sort of like tests, really)

I like the idea and already discussed it with Kit Barton.

Two concerns that I had:

1. Keeping them in-tree requires them to be up-to-date, a potential
additional maintenance burden. This might be what we want, but I get
less enthusiastic when thinking about maintaining all tutorials ever
given at any conference during the last xx years without having gone
through a review process.

Given the concerns and requests for additional documentation I think
that the maintenance burden of tutorials are well within bounds of
"necessary maintenance" for the project as a whole. Hopefully API and
other updates won't feel too onerous and the additional benefits will
prove out.

... and as Dave followed up as I was writing this - I see these as
tests as well.

2.Chris Bieneman seeks to simplify the cmake build system, including
significantly reducing the number of configuration parameters and
making "make all" really make everything, including examples. This
would make the overall configure process slower even when not
interested in the tutorials.

I would be entirely up for having them built all the time (along with
the all of the other tutorials).

-eric

Thanks for taking a look!

I am not entirely sure at the moment how the transformations would fit into the Kaleidoscope tutorial directly; but on the tutorials page, there is a `Writing an Optimization for LLVM` one and the examples would fit well alongside there I think.

Cheers,
Florian

Thanks for taking a look! Eric and David beat me to responding. Below are a few additional thoughts in a similar direction.

I like the idea and already discussed it with Kit Barton.

Two concerns that I had:

  1. Keeping them in-tree requires them to be up-to-date, a potential
    additional maintenance burden. This might be what we want, but I get
    less enthusiastic when thinking about maintaining all tutorials ever
    given at any conference during the last xx years without having gone
    through a review process.

As with any code in the codebase, yeah, pre or post commit review seems good & if they end up bitrotting/becoming less relevant/diverge significantly from the tutorial content (written, video, whatever there is) I think it’s fine to delete them. Same as we’d do with tests. (I think they’re sort of like tests, really)

I think that would be great policy.

IMO, the examples should go through reviews as well and for any changes that break the examples, I think it is reasonable to expect the author to fix them, similar to breaking other parts of LLVM.

But it might be unreasonable to expect people to also update accompanying material (e.g. a write up), except for trivial API changes. As David suggested, if they diverge too much, we can remove them (or try to find someone who is interested in updating them).

2.Chris Bieneman seeks to simplify the cmake build system, including
significantly reducing the number of configuration parameters and
making “make all” really make everything, including examples. This
would make the overall configure process slower even when not
interested in the tutorials.

The suggested approach does not introduce any new options/variables, it just adds an additional definition, if the existing LLVM_BUILD_EXAMPLES=On. So this should not interfere with reducing the overall options. Whatever solution will be applied to all examples should also work for the IR pass examples.

Cheers,
Florian

I think he would like to remove LLVM_BUILD_EXAMPLES altogether. That
is, any "cmake" will execute any CMakeLists.txt, "make all" will
always build TutorialSimplyCFG and any execution of `opt` will call
initializeExampleIRTransforms.

I am in favor of adding (more) tutorials to the repository, joint
trying to point out items to consider.

Michael

+1 I think that this will be super helpful, thank you Florian!

Sounds good - bonus points if these examples were motivated with a
continuation to the Kaleidoscope tutorial - Eric Christopher and I did a
tutorial on debug info back in 2014 and included new chapters for
Kaleidoscope for future usage.

From the conversations that I had during LLVM Dev, Kaleidoscope isn't
as helpful beginner tutorial as we tend to think. IMHO, self-contained
examples like Florian is proposing are more useful. Meike Baumgärtner
presented a great talk on the matter.

If we want to keep the number of extra CMake flags to minimum, maybe it
would be worth considering such examples as _opt_ plugins? This could
then leverage the mechanism proposed here:
1. Phab patch: ⚙ D61446 Generalize the pass registration mechanism used by Polly to any third-party tool
2. RFC: http://lists.llvm.org/pipermail/llvm-dev/2019-May/132128.html

Just my 2c.

-Andrzej

Sorry, I meant this RFC:
http://lists.llvm.org/pipermail/llvm-dev/2019-September/135326.html

(the previous one is also relevant)

-Andrzej

Michael Kruse via llvm-dev <llvm-dev@lists.llvm.org> writes:

Yes I think we should move to that mechanism, once it is available (Michael pointed that out during the review as well), but not necessarily block submitting the first examples until the new mechanism is available.

Cheers,
Florian

Yes that would be great!

As mentioned earlier, I think the decision on unconditionally building the (existing) examples does not really depend on whether we add more examples. Until then, I think there are bots that build with examples enabled (and if not I’ll try to get one doing that).

Cheers,
Florian

Thanks for the great comments so far.

My understanding from the comments is that people generally think that adding IR transformation examples to llvm/examples is valuable.

Unless there are remaining high-level concerns, I’d suggest to discuss the details as part of https://reviews.llvm.org/D69416 and iterate on the examples once they are in-tree.

Cheers,
Florian