[llvm] [docs] Try to make it easier to find info about new PM vs legacy PM (PR #80834)

Tue Feb 6 05:58:30 PST 2024

https://github.com/bjope created https://github.com/llvm/llvm-project/pull/80834

Seen several beginner questions popping up in discourse about how to implement and run custom passes. And then it turns out that they are following the old "Writing an LLVM Pass" guide that describe legacy passes, and then things are mixed up when they try to run that pass using opt that nowadays default to the new pass manager.

This is an attempt to make it slightly clearer in the User Guides that there are two different "Writing an LLVM Pass" pages depending on which pass manager that should be used. This is done by renaming the legacy version of "Writing an LLVM Pass" as "Writing an LLVM Pass (legacy PM version)".
Also reordered the links to put the link to the new pass manager documentation first.

This patch also moves the warning text that cross references the description on how to write a pass for legacy/new PM to make sure it ends up already in the beginning of the descriptions.

Also adding a new warning in the "Running a pass with opt" section of the legacy PM version of the guide, to inform that those examples are outdated.

>From f3081fde1a3d55317e22efc5d4364c8412af22fd Mon Sep 17 00:00:00 2001
From: Bjorn Pettersson <bjorn.a.pettersson at ericsson.com>
Date: Wed, 31 Jan 2024 17:19:39 +0100
Subject: [PATCH] [docs] Try to make it easier to find info about new PM vs
 legacy PM

Seen several beginner questions popping up in discourse about
how to implement and run custom passes. And then it turns out
that they are following the old "Writing an LLVM Pass" guide that
describe legacy passes, and then things are mixed up when they
try to run that pass using opt that nowadays default to the
new pass manager.

This is an attempt to make it slightly clearer in the User Guides
that there are two different "Writing an LLVM Pass" pages depending
on which pass manager that should be used. This is done by renaming
the legacy version of "Writing an LLVM Pass" as "Writing an LLVM Pass
(legacy PM version)".
Also reordered the links to put the link to the new pass manager
documentation first.

This patch also moves the warning text that cross references
the description on how to write a pass for legacy/new PM to make
sure it ends up already in the beginning of the descriptions.

Also adding a new warning in the "Running a pass with opt" section of
the legacy PM version of the guide, to inform that those examples
are outdated.
---
 llvm/docs/UserGuides.rst             |  7 ++++---
 llvm/docs/WritingAnLLVMNewPMPass.rst | 10 +++++-----
 llvm/docs/WritingAnLLVMPass.rst      | 27 +++++++++++++++++----------
 3 files changed, 26 insertions(+), 18 deletions(-)

diff --git a/llvm/docs/UserGuides.rst b/llvm/docs/UserGuides.rst
index 9ae0d360111542..6fb61f2d3a2526 100644
--- a/llvm/docs/UserGuides.rst
+++ b/llvm/docs/UserGuides.rst
@@ -123,13 +123,14 @@ LLVM Builds and Distributions
 Optimizations
 -------------
 
-:doc:`WritingAnLLVMPass`
-   Information on how to write LLVM transformations and analyses.
-
 :doc:`WritingAnLLVMNewPMPass`
    Information on how to write LLVM transformations under the new pass
    manager.
 
+:doc:`WritingAnLLVMPass`
+   Information on how to write LLVM transformations and analyses under the
+   legacy pass manager.
+
 :doc:`Passes`
    A list of optimizations and analyses implemented in LLVM.
 
diff --git a/llvm/docs/WritingAnLLVMNewPMPass.rst b/llvm/docs/WritingAnLLVMNewPMPass.rst
index 799863c7864ecc..ea30d637347f16 100644
--- a/llvm/docs/WritingAnLLVMNewPMPass.rst
+++ b/llvm/docs/WritingAnLLVMNewPMPass.rst
@@ -10,6 +10,11 @@ Writing an LLVM Pass
 Introduction --- What is a pass?
 ================================
 
+.. warning::
+  This document deals with the new pass manager. LLVM uses the legacy pass
+  manager for the codegen pipeline. For more details, see
+  :doc:`WritingAnLLVMPass` and :doc:`NewPassManager`.
+
 The LLVM pass framework is an important part of the LLVM system, because LLVM
 passes are where most of the interesting parts of the compiler exist. Passes
 perform the transformations and optimizations that make up the compiler, they
@@ -29,11 +34,6 @@ We start by showing you how to construct a pass, from setting up the build,
 creating the pass, to executing and testing it. Looking at existing passes is
 always a great way to learn details.
 
-.. warning::
-  This document deals with the new pass manager. LLVM uses the legacy pass
-  manager for the codegen pipeline. For more details, see
-  :doc:`WritingAnLLVMPass` and :doc:`NewPassManager`.
-
 Quick Start --- Writing hello world
 ===================================
 
diff --git a/llvm/docs/WritingAnLLVMPass.rst b/llvm/docs/WritingAnLLVMPass.rst
index b94669917c9071..a3602e7fbc31fd 100644
--- a/llvm/docs/WritingAnLLVMPass.rst
+++ b/llvm/docs/WritingAnLLVMPass.rst
@@ -1,6 +1,6 @@
-====================
-Writing an LLVM Pass
-====================
+========================================
+Writing an LLVM Pass (legacy PM version)
+========================================
 
 .. program:: opt
 
@@ -10,6 +10,13 @@ Writing an LLVM Pass
 Introduction --- What is a pass?
 ================================
 
+.. warning::
+  This document deals with the legacy pass manager. LLVM uses the new pass
+  manager for the optimization pipeline (the codegen pipeline
+  still uses the legacy pass manager), which has its own way of defining
+  passes. For more details, see :doc:`WritingAnLLVMNewPMPass` and
+  :doc:`NewPassManager`.
+
 The LLVM Pass Framework is an important part of the LLVM system, because LLVM
 passes are where most of the interesting parts of the compiler exist.  Passes
 perform the transformations and optimizations that make up the compiler, they
@@ -34,13 +41,6 @@ We start by showing you how to construct a pass, everything from setting up the
 code, to compiling, loading, and executing it.  After the basics are down, more
 advanced features are discussed.
 
-.. warning::
-  This document deals with the legacy pass manager. LLVM uses the new pass
-  manager for the optimization pipeline (the codegen pipeline
-  still uses the legacy pass manager), which has its own way of defining
-  passes. For more details, see :doc:`WritingAnLLVMNewPMPass` and
-  :doc:`NewPassManager`.
-
 Quick Start --- Writing hello world
 ===================================
 
@@ -224,6 +224,13 @@ can have them) to be useful.
 Running a pass with ``opt``
 ---------------------------
 
+.. warning::
+  This document deals with the legacy pass manager. The :program:`opt` tool no
+  longer supports running legacy passes (except for certain hardcoded backend
+  passes and when using bugpoint). So the examples below for loading and
+  running legacy passes using :program:`opt` are deprecated and no longer
+  guaranteed to work.
+
 Now that you have a brand new shiny shared object file, we can use the
 :program:`opt` command to run an LLVM program through your pass.  Because you
 registered your pass with ``RegisterPass``, you will be able to use the

