llvm dev - Oct 2019 - 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.

On Thu, Oct 24, 2019 at 4:47 PM Florian Hahn via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> 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
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20191024/5634b515/attachment.html>

What Dave said :)

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

On Thu, Oct 24, 2019 at 6:25 PM David Blaikie via llvm-dev
<llvm-dev at lists.llvm.org> wrote:
>
> 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.
>
> On Thu, Oct 24, 2019 at 4:47 PM Florian Hahn via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
>>
>> 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
>> _______________________________________________
>> LLVM Developers mailing list
>> llvm-dev at lists.llvm.org
>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

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

On Fri, Oct 25, 2019 at 2:43 PM Michael Kruse via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> 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)

>
> 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
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20191025/12e6e0e2/attachment.html>

On Fri, Oct 25, 2019 at 2:43 PM Michael Kruse via llvm-dev
<llvm-dev at lists.llvm.org> wrote:
>
> 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

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

On 24/10/2019 18:24, David Blaikie via llvm-dev wrote:
> 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: https://reviews.llvm.org/D61446?id=221321#change-uAgt0khUmRhe
2. RFC: http://lists.llvm.org/pipermail/llvm-dev/2019-May/132128.html

Just my 2c.

-Andrzej

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
> On Oct 25, 2019, at 01:46, Florian Hahn via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
> 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
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev