This is an archive of the discontinued LLVM Phabricator instance.

Differential D109871

[flang][docs] Document plugin limitations
ClosedPublic

Authored by awarzynski on Sep 16 2021, 1:00 AM.

Details

Reviewers
kiranchandramohan
klausler
stuartellis
Commits
rG7e7484a816a5: [flang][docs] Document plugin limitations
Summary

This was extracted from the discussion on
https://reviews.llvm.org/D108283.

Co-authored-by: Kiran Chandramohan <kiran.chandramohan@arm.com>

Diff Detail

Event Timeline

awarzynski created this revision.Sep 16 2021, 1:00 AM
Herald added a subscriber: kristof.beyls. · View Herald TranscriptSep 16 2021, 1:00 AM
awarzynski requested review of this revision.Sep 16 2021, 1:00 AM
Herald added a project: Restricted Project. · View Herald TranscriptSep 16 2021, 1:00 AM
Herald added a subscriber: llvm-commits. · View Herald Transcript
awarzynski added reviewers: kiranchandramohan, klausler, stuartellis.Sep 16 2021, 1:04 AM
awarzynski added a project: Restricted Project.
Herald added a subscriber: jdoerfert. · View Herald TranscriptSep 16 2021, 1:04 AM
awarzynski added a comment.Sep 16 2021, 1:05 AM

@kiranchandramohan I took the liberty of expanding your bullet points from https://reviews.llvm.org/D108283 into a paragraph. I hope that that's fine. Feel free to edit!

Harbormaster completed remote builds in B124148: Diff 372875.Sep 16 2021, 1:43 AM
kiranchandramohan accepted this revision.Sep 16 2021, 2:14 AM

LGTM.
I have a suggestion.

flang/docs/FlangDriver.md
407

Nit: Use the following as a suggestion

Note that we intend to replace the traversal API with an API based on function object style. Hence the current API will be deprecated in future.

The parse-tree classes and enums will change as Flang development progresses and new language features are added. Plugin writers should therefore not expect these classes to be stable and keep in mind the need for maintenance.

This revision is now accepted and ready to land.Sep 16 2021, 2:14 AM
awarzynski added a comment.Sep 20 2021, 11:26 AM

@kiranchandramohan, thank you the suggestion!

In D109871#3003369, @kiranchandramohan wrote:

I have a suggestion.

Note that we intend to replace the traversal API with an API based on function object style.

I wouldn't add this here. It's something that we would like to happen, but AFAIK it's not being worked on actively. Also, I would prefer for this document to focus on the currently available interface. We know that it works fine as there are tests to defend that.

Plugin writers should therefore not expect these classes to be stable and keep in mind the need for maintenance.

I don't think that we need this. AFAIK, there are no guarantees about the stability of any of the C++ APIs within llvm-project. LLVM only mentions the stability of the C API. Sadly, we are unable to make any guarantees to to our downstream users, regardless of whether it's for plugins or other libraries within LLVM Flang.

Closed by commit rG7e7484a816a5: [flang][docs] Document plugin limitations (authored by awarzynski). · Explain WhySep 21 2021, 1:51 AM
This revision was automatically updated to reflect the committed changes.
awarzynski added a commit: rG7e7484a816a5: [flang][docs] Document plugin limitations.

Revision Contents

PathSize
flang/
docs/
17 lines

Diff 372875

flang/docs/FlangDriver.md

Show First 20 Lines • Show All 392 Lines • ▼ Show 20 Lines
For in-tree plugins, there is the CMake flag `FLANG_PLUGIN_SUPPORT`, enabled by For in-tree plugins, there is the CMake flag `FLANG_PLUGIN_SUPPORT`, enabled by
default, that controls the exporting of executable symbols from `flang-new`, default, that controls the exporting of executable symbols from `flang-new`,
which plugins need access to. Additionally, there is the CMake flag which plugins need access to. Additionally, there is the CMake flag
`FLANG_BUILD_EXAMPLES`, turned off by default, that is used to control if the `FLANG_BUILD_EXAMPLES`, turned off by default, that is used to control if the
example programs are built. This includes plugins that are in the example programs are built. This includes plugins that are in the
`flang/example` directory and added as a `sub_directory` to the `flang/example` directory and added as a `sub_directory` to the
`flang/examples/CMakeLists.txt`, for example, the `PrintFlangFunctionNames` `flang/examples/CMakeLists.txt`, for example, the `PrintFlangFunctionNames`
plugin. It is also possible to develop plugins out-of-tree. plugin. It is also possible to develop plugins out-of-tree.
## Limitations
Note that the traversal API presented here is under active development and
might change in the future. We expect it to evolve as support for new
language features are added. This document and the examples will be updated
accordingly.
kiranchandramohanUnsubmitted
Not Done
ReplyInline Actions

Nit: Use the following as a suggestion

Note that we intend to replace the traversal API with an API based on function object style. Hence the current API will be deprecated in future.

The parse-tree classes and enums will change as Flang development progresses and new language features are added. Plugin writers should therefore not expect these classes to be stable and keep in mind the need for maintenance.

kiranchandramohan: Nit: Use the following as a suggestion Note that we intend to replace the traversal API with…
The current `ParseTree` structure is not suitable for modifications. The
copy constructors are not available and hence duplicating code might not be
trivial. Please take this into consideration when designing your plugin. In
particular, creating a transformation plugin will be noticeably harder than
analysis plugins that just consume (rather than edit) `ParseTree`.
Lastly, if `ParseTree` modifications are performed, then it might be necessary
to re-analyze expressions and modify scope or symbols. You can check
[Semantics.md](Semantics.md) for more details on how `ParseTree` is edited
e.g. during the semantic checks.