Cold-Air-Networks/mirror-llvm-project
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 7

[docs] Migrate 22 popular LLVM docs to MyST (#201244)

Browse source 
This was done with LLM assistance.

I rebuilt the LLVM docs, opened all 22 docs in a browser and scrolled
through them, and caught and fixed a few errors.

Tracking issue: #201242 
Migration guide docs:
https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
RFC:
https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/90840
This commit is contained in:
Reid Kleckner 2026-06-22 16:02:50 -07:00 committed by GitHub
parent 64d386e642
commit 3e414a36cd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
23 changed files with 11232 additions and 12165 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1661
llvm/docs/CMake.md
View file

File diff suppressed because it is too large Load diff

1930
llvm/docs/CodeGenerator.md
View file

File diff suppressed because it is too large Load diff

1757
llvm/docs/CodingStandards.md
View file

File diff suppressed because it is too large Load diff

169
llvm/docs/CommandGuide/index.md
View file

@ -1,105 +1,104 @@
LLVM Command Guide
------------------
# LLVM Command Guide
The following documents are command descriptions for all of the LLVM tools.
These pages describe how to use the LLVM commands and what their options are.
Note that these pages do not describe all of the options available for all
tools. To get a complete listing, pass the ``--help`` (general options) or
``--help-hidden`` (general and debugging options) arguments to the tool you are
tools. To get a complete listing, pass the `--help` (general options) or
`--help-hidden` (general and debugging options) arguments to the tool you are
interested in.
Basic Commands
~~~~~~~~~~~~~~
## Basic Commands
.. toctree::
:maxdepth: 1
```{toctree}
:maxdepth: 1
dsymutil
llc
lli
llubi
llvm-as
llvm-cgdata
llvm-config
llvm-cov
llvm-cxxmap
llvm-debuginfo-analyzer
llvm-diff
llvm-dis
llvm-dwarfdump
llvm-dwarfutil
llvm-extract-bundle-entry
llvm-ir2vec
llvm-lib
llvm-libtool-darwin
llvm-link
llvm-lipo
llvm-mc
llvm-mca
llvm-opt-report
llvm-otool
llvm-profdata
llvm-readobj
llvm-reduce
llvm-stress
llvm-symbolizer
opt
dsymutil
llc
lli
llubi
llvm-as
llvm-cgdata
llvm-config
llvm-cov
llvm-cxxmap
llvm-debuginfo-analyzer
llvm-diff
llvm-dis
llvm-dwarfdump
llvm-dwarfutil
llvm-extract-bundle-entry
llvm-ir2vec
llvm-lib
llvm-libtool-darwin
llvm-link
llvm-lipo
llvm-mc
llvm-mca
llvm-opt-report
llvm-otool
llvm-profdata
llvm-readobj
llvm-reduce
llvm-stress
llvm-symbolizer
opt
```
GNU binutils replacements
~~~~~~~~~~~~~~~~~~~~~~~~~
## GNU binutils replacements
.. toctree::
:maxdepth: 1
```{toctree}
:maxdepth: 1
llvm-addr2line
llvm-ar
llvm-cxxfilt
llvm-install-name-tool
llvm-nm
llvm-objcopy
llvm-objdump
llvm-ranlib
llvm-readelf
llvm-size
llvm-strings
llvm-strip
llvm-addr2line
llvm-ar
llvm-cxxfilt
llvm-install-name-tool
llvm-nm
llvm-objcopy
llvm-objdump
llvm-ranlib
llvm-readelf
llvm-size
llvm-strings
llvm-strip
```
Debugging Tools
~~~~~~~~~~~~~~~
## Debugging Tools
.. toctree::
:maxdepth: 1
```{toctree}
:maxdepth: 1
llvm-extract
llvm-bcanalyzer
llvm-reduce
llvm-extract
llvm-bcanalyzer
llvm-reduce
```
Developer Tools
~~~~~~~~~~~~~~~
## Developer Tools
.. toctree::
:maxdepth: 1
```{toctree}
:maxdepth: 1
FileCheck
tblgen
clang-tblgen
lldb-tblgen
llvm-tblgen
mlir-tblgen
lit
llvm-exegesis
llvm-ifs
llvm-locstats
llvm-test-mustache-spec
llvm-pdbutil
llvm-profgen
llvm-tli-checker
llvm-offload-binary
FileCheck
tblgen
clang-tblgen
lldb-tblgen
llvm-tblgen
mlir-tblgen
lit
llvm-exegesis
llvm-ifs
llvm-locstats
llvm-test-mustache-spec
llvm-pdbutil
llvm-profgen
llvm-tli-checker
llvm-offload-binary
```
Remarks Tools
~~~~~~~~~~~~~~
## Remarks Tools
.. toctree::
:maxdepth: 1
```{toctree}
:maxdepth: 1
llvm-remarkutil
llvm-remarkutil
```

219
llvm/docs/Contributing.md
View file

@ -1,124 +1,119 @@
==================================
Contributing to LLVM
==================================
# Contributing to LLVM
Thank you for your interest in contributing to LLVM! There are multiple ways to
contribute, and we appreciate all contributions. If you have questions,
you can either use the `Forum`_ or, for a more interactive chat, go to our
`Discord server`_.
you can either use the [Forum] or, for a more interactive chat, go to our
[Discord server].
If you want to contribute code, please familiarize yourself with the :doc:`DeveloperPolicy`.
If you want to contribute code, please familiarize yourself with the {doc}`DeveloperPolicy`.
.. contents::
:local:
```{contents}
:local:
```
Ways to Contribute
==================
## Ways to Contribute
Bug Reports
-----------
### Bug Reports
If you are working with LLVM and run into a bug, we definitely want to know
about it. Please follow the instructions in
:doc:`HowToSubmitABug` to create a bug report.
{doc}`HowToSubmitABug` to create a bug report.
Bug Fixes
---------
### Bug Fixes
If you are interested in contributing code to LLVM, bugs labeled with the
`good first issue`_ keyword in the `bug tracker`_ are a good way to get familiar with
[good first issue] keyword in the [bug tracker] are a good way to get familiar with
the code base. If you are interested in fixing a bug, please comment on it to
let people know you are working on it.
Then try to reproduce and fix the bug with upstream LLVM. Start by building
LLVM from source as described in :doc:`GettingStarted` and
LLVM from source as described in {doc}`GettingStarted` and
use the built binaries to reproduce the failure described in the bug. Use
a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions
(`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds).
Reporting a Security Issue
--------------------------
### Reporting a Security Issue
There is a separate process to submit security-related bugs, see :ref:`report-security-issue`.
There is a separate process to submit security-related bugs, see {ref}`report-security-issue`.
Bigger Pieces of Work
---------------------
### Bigger Pieces of Work
If you are interested in taking on a bigger piece of work, a list of
interesting projects is maintained at the `LLVM's Open Projects page`_. If
interesting projects is maintained at the [LLVM's Open Projects page]. If
you are interested in working on any of these projects, please post on the
`Forum`_, so that we know the project is being worked on.
[Forum], so that we know the project is being worked on.
.. _submit_patch:
(submit_patch)=
How to Submit a Patch
=====================
## How to Submit a Patch
Once you have a patch ready, it is time to submit it. The patch should:
* include a small unit test
* conform to the :doc:`CodingStandards`. You can use the `clang-format-diff.py`_ or `git-clang-format`_ tools to automatically format your patch properly.
* conform to the {doc}`CodingStandards`. You can use the [clang-format-diff.py] or [git-clang-format] tools to automatically format your patch properly.
* not contain any unrelated changes
* be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.
* have a single commit, up-to-date with the upstream ``origin/main`` branch, and don't have merges.
* have a single commit, up-to-date with the upstream `origin/main` branch, and don't have merges.
.. _format patches:
(format patches)=
Before sending a patch for review, please also ensure it is
formatted properly. We use ``clang-format`` for this, which has git integration
through the ``git-clang-format`` script. On some systems, it may already be
formatted properly. We use `clang-format` for this, which has git integration
through the `git-clang-format` script. On some systems, it may already be
installed (or be installable via your package manager). If so, you can simply
run it -- the following command will format only the code changed in the most
recent commit:
.. code-block:: console
```console
% git clang-format HEAD~1
```
% git clang-format HEAD~1
```{note}
For some patches, formatting them may add changes that obscure the intent of
the patch. For example, adding to an enum that was not previously formatted
may result in the entire enum being reformatted. This happens because not all
of the LLVM Project conforms to LLVM's clang-format style at this time.
.. note::
For some patches, formatting them may add changes that obscure the intent of
the patch. For example, adding to an enum that was not previously formatted
may result in the entire enum being reformatted. This happens because not all
of the LLVM Project conforms to LLVM's clang-format style at this time.
If you think that this might be the case for your changes, or are unsure, we
recommend that you add the formatting changes as a **separate commit** within
the Pull Request.
If you think that this might be the case for your changes, or are unsure, we
recommend that you add the formatting changes as a **separate commit** within
the Pull Request.
Reviewers may request that this formatting commit be made into a separate Pull
Request that will be merged before your actual changes.
Reviewers may request that this formatting commit be made into a separate Pull
Request that will be merged before your actual changes.
This means that if the formatting changes are the first commit, you will have
an easier time doing this. If they are not, that is ok too, but you will have
to do a bit more work to separate it out.
```
This means that if the formatting changes are the first commit, you will have
an easier time doing this. If they are not, that is ok too, but you will have
to do a bit more work to separate it out.
Note that ``git clang-format`` modifies the files, but does not commit them --
Note that `git clang-format` modifies the files, but does not commit them --
you will likely want to run one of the following to add the changes to a commit:
.. code-block:: console
```console
# To create a new commit.
% git commit -a
# To add to the most recent commit.
% git commit --amend -a
```
# To create a new commit.
% git commit -a
# To add to the most recent commit.
% git commit --amend -a
.. note::
If you don't already have ``clang-format`` or ``git clang-format`` installed
on your system, the ``clang-format`` binary will be built alongside clang, and
the git integration can be run from
``clang/tools/clang-format/git-clang-format``.
```{note}
If you don't already have `clang-format` or `git clang-format` installed
on your system, the `clang-format` binary will be built alongside clang, and
the git integration can be run from
`clang/tools/clang-format/git-clang-format`.
```
The LLVM project has migrated to GitHub Pull Requests as its review process.
For more information about the workflow of using GitHub Pull Requests see our
:ref:`GitHub <github-reviews>` documentation. We still have a read-only
`LLVM's Phabricator <https://reviews.llvm.org>`_ instance.
{ref}`GitHub <github-reviews>` documentation. We still have a read-only
[LLVM's Phabricator](https://reviews.llvm.org) instance.
To make sure the right people see your patch, please select suitable reviewers
and add them to your patch when requesting a review.
Suitable reviewers are the maintainers of the project you are modifying, and
anyone else working in the area your patch touches. To find maintainers, look for
the ``Maintainers.md`` file in the root of the project's
sub-directory. For example, LLVM's is ``llvm/Maintainers.md`` and
clang-tools-extra's is ``clang-tools-extra/Maintainers.md``.
the `Maintainers.md` file in the root of the project's
sub-directory. For example, LLVM's is `llvm/Maintainers.md` and
clang-tools-extra's is `clang-tools-extra/Maintainers.md`.
If you are a new contributor, you will not be able to select reviewers in such a
way, in which case you can still get the attention of potential reviewers by CC'ing
@ -135,32 +130,32 @@ explicitly, as reviewers' default assumption is that you are able to merge your
own PR.
For more information on LLVM's code-review process, please see
:doc:`CodeReview`.
{doc}`CodeReview`.
.. _commit_from_git:
(commit_from_git)=
For developers to commit changes from Git
-----------------------------------------
### For developers to commit changes from Git
.. note::
See also :ref:`GitHub <github-reviews>` for more details on merging your changes
into LLVM project monorepo.
```{note}
See also {ref}`GitHub <github-reviews>` for more details on merging your changes
into LLVM project monorepo.
```
Once a pull request is approved, you can select the "Squash and merge" button in the
GitHub web interface.
When pushing directly from the command-line to the ``main`` branch, you will need
When pushing directly from the command-line to the `main` branch, you will need
to rebase your change. LLVM has a linear-history policy, which means
that merge commits are not allowed, and the ``main`` branch is configured to reject
that merge commits are not allowed, and the `main` branch is configured to reject
pushes that include merges.
GitHub will display a message that looks like this:
.. code-block:: console
remote: Bypassed rule violations for refs/heads/main:
remote:
remote: - Required status check “buildkite/github-pull-requests” is expected.
```console
remote: Bypassed rule violations for refs/heads/main:
remote:
remote: - Required status check “buildkite/github-pull-requests” is expected.
```
This can seem scary, but this is just an artifact of the GitHub setup: it is
intended as a warning for people merging pull-requests with failing CI. We can't
@ -168,56 +163,52 @@ disable it for people pushing on the command-line.
Please ask for help if you're having trouble with your particular git workflow.
.. _git_pre_push_hook:
(git_pre_push_hook)=
Git pre-push hook
^^^^^^^^^^^^^^^^^
#### Git pre-push hook
We include an optional pre-push hook that runs some sanity checks on the revisions
you are about to push and asks for confirmation if you push multiple commits at once.
You can set it up (on Unix systems) by running from the repository root:
.. code-block:: console
```console
% ln -sf ../../llvm/utils/git/pre-push.py .git/hooks/pre-push
```
% ln -sf ../../llvm/utils/git/pre-push.py .git/hooks/pre-push
Helpful Information About LLVM
==============================
:doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as
## Helpful Information About LLVM
{doc}`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as
well as various user guides. The pages listed below should provide a good overview
of LLVM's high-level design, as well as its internals:
:doc:`GettingStarted`
Discusses how to get up and running quickly with the LLVM infrastructure.
Everything from unpacking and compilation of the distribution to execution
of some tools.
{doc}`GettingStarted`
: Discusses how to get up and running quickly with the LLVM infrastructure.
Everything from unpacking and compilation of the distribution to execution
of some tools.
:doc:`LangRef`
Defines the LLVM intermediate representation.
{doc}`LangRef`
: Defines the LLVM intermediate representation.
:doc:`ProgrammersManual`
Introduction to the general layout of the LLVM sourcebase, important classes
{doc}`ProgrammersManual`
: Introduction to the general layout of the LLVM sourcebase, important classes
and APIs, and some tips & tricks.
`LLVM for Grad Students`__
This is an introduction to the LLVM infrastructure by Adrian Sampson. While it
[LLVM for Grad Students]
: This is an introduction to the LLVM infrastructure by Adrian Sampson. While it
has been written for grad students, it provides a good, compact overview of
LLVM's architecture, LLVM's IR and how to write a new pass.
.. __: http://www.cs.cornell.edu/~asampson/blog/llvm.html
[Intro to LLVM]
: Book chapter providing a compiler hacker's introduction to LLVM.
`Intro to LLVM`__
Book chapter providing a compiler hacker's introduction to LLVM.
.. __: http://www.aosabook.org/en/llvm.html
.. _Forum: https://discourse.llvm.org
.. _Discord server: https://discord.gg/xS7Z362
.. _irc.oftc.net: irc://irc.oftc.net/llvm
.. _good first issue: https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
.. _bug tracker: https://github.com/llvm/llvm-project/issues
.. _clang-format-diff.py: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/clang-format-diff.py
.. _git-clang-format: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/git-clang-format
.. _LLVM's GitHub: https://github.com/llvm/llvm-project
.. _LLVM's Phabricator (read-only): https://reviews.llvm.org/
.. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what
[Forum]: https://discourse.llvm.org
[Discord server]: https://discord.gg/xS7Z362
[irc.oftc.net]: irc://irc.oftc.net/llvm
[good first issue]: https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
[bug tracker]: https://github.com/llvm/llvm-project/issues
[clang-format-diff.py]: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/clang-format-diff.py
[git-clang-format]: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/git-clang-format
[LLVM's GitHub]: https://github.com/llvm/llvm-project
[LLVM's Phabricator (read-only)]: https://reviews.llvm.org/
[LLVM's Open Projects page]: https://llvm.org/OpenProjects.html#what
[LLVM for Grad Students]: http://www.cs.cornell.edu/~asampson/blog/llvm.html
[Intro to LLVM]: http://www.aosabook.org/en/llvm.html

1301
llvm/docs/DeveloperPolicy.md
View file

File diff suppressed because it is too large Load diff

534
llvm/docs/GettingInvolved.md
View file

@ -1,149 +1,160 @@
Getting Involved
================
# Getting Involved
LLVM welcomes contributions of all kinds. To get started, please review the following topics:
.. contents::
:local:
```{contents}
:local:
```
.. toctree::
:hidden:
```{toctree}
:hidden:
Contributing
DeveloperPolicy
CodeReview
SupportPolicy
SphinxQuickstartTemplate
HowToSubmitABug
BugLifeCycle
CodingStandards
GitHub
GitBisecting
GitRepositoryPolicy
Contributing
DeveloperPolicy
CodeReview
SupportPolicy
SphinxQuickstartTemplate
HowToSubmitABug
BugLifeCycle
CodingStandards
GitHub
GitBisecting
GitRepositoryPolicy
```
:doc:`Contributing`
An overview on how to contribute to LLVM.
* {doc}`Contributing`
:doc:`DeveloperPolicy`
The LLVM project's policy towards developers and their contributions.
An overview on how to contribute to LLVM.
:doc:`CodeReview`
The LLVM project's code-review process.
* {doc}`DeveloperPolicy`
:doc:`SupportPolicy`
The LLVM support policy for core and non-core components.
The LLVM project's policy towards developers and their contributions.
* {doc}`CodeReview`
The LLVM project's code-review process.
* {doc}`SupportPolicy`
The LLVM support policy for core and non-core components.
* {doc}`SphinxQuickstartTemplate`
:doc:`SphinxQuickstartTemplate`
A template + tutorial for writing new Sphinx documentation. It is meant
to be read in source form.
:doc:`HowToSubmitABug`
Instructions for properly submitting information about any bugs you run into
in the LLVM system.
* {doc}`HowToSubmitABug`
:doc:`BugLifeCycle`
Describes how bugs are reported, triaged, and closed.
Instructions for properly submitting information about any bugs you run into
in the LLVM system.
* {doc}`BugLifeCycle`
Describes how bugs are reported, triaged, and closed.
* {doc}`CodingStandards`
:doc:`CodingStandards`
Details the LLVM coding standards and provides useful information on writing
efficient C++ code.
:doc:`GitHub`
* {doc}`GitHub`
Describes how to use the llvm-project repository and code reviews on GitHub.
:doc:`GitBisecting`
Describes how to use ``git bisect`` on LLVM's repository.
* {doc}`GitBisecting`
:doc:`GitRepositoryPolicy`
Collection of policies around the git repositories.
Describes how to use `git bisect` on LLVM's repository.
.. _development-process:
* {doc}`GitRepositoryPolicy`
Development Process
-------------------
Collection of policies around the git repositories.
(development-process)=
## Development Process
Information about LLVM's development process.
.. toctree::
:hidden:
```{toctree}
:hidden:
Projects
HowToReleaseLLVM
ReleaseProcess
HowToAddABuilder
ReleaseNotes
Projects
HowToReleaseLLVM
ReleaseProcess
HowToAddABuilder
ReleaseNotes
```
* {doc}`Projects`
:doc:`Projects`
How-to guide and templates for new projects that *use* the LLVM
infrastructure. The templates (directory organization, Makefiles, and test
tree) allow the project code to be located outside (or inside) the ``llvm/``
tree) allow the project code to be located outside (or inside) the `llvm/`
tree, while using LLVM header files and libraries.
:doc:`HowToReleaseLLVM`
* {doc}`HowToReleaseLLVM`
This is a guide to preparing LLVM releases. Most developers can ignore it.
:doc:`ReleaseProcess`
* {doc}`ReleaseProcess`
This is a guide to validate a new release, during the release process. Most developers can ignore it.
:doc:`HowToAddABuilder`
Instructions for adding new builder to LLVM buildbot master.
* {doc}`HowToAddABuilder`
:doc:`Release notes for the current release <ReleaseNotes>`
This describes new features, known bugs, and other limitations.
Instructions for adding new builder to LLVM buildbot master.
.. _lists-forums:
* {doc}`Release notes for the current release <ReleaseNotes>`
Forums & Mailing Lists
----------------------
This describes new features, known bugs, and other limitations.
(lists-forums)=
## Forums & Mailing Lists
If you can't find what you need in these docs, try consulting the
Discourse forums. There are also commit mailing lists for all commits to the LLVM Project.
The :doc:`CodeOfConduct` applies to all these forums and mailing lists.
The {doc}`CodeOfConduct` applies to all these forums and mailing lists.
* [LLVM Discourse](https://discourse.llvm.org/)
`LLVM Discourse`__
The forums for all things LLVM and related sub-projects. There are categories and subcategories for a wide variety of areas within LLVM. You can also view tags or search for a specific topic.
.. __: https://discourse.llvm.org/
* [Commits Archive (llvm-commits)](http://lists.llvm.org/pipermail/llvm-commits/)
`Commits Archive (llvm-commits)`__
This list contains all commit messages that are made when LLVM developers
commit code changes to the repository. It also serves as a forum for
patch review (i.e., send patches here). It is useful for those who want to
stay on the bleeding edge of LLVM development. This list is very high
volume.
.. __: http://lists.llvm.org/pipermail/llvm-commits/
* [Bugs & Patches Archive (llvm-bugs)](http://lists.llvm.org/pipermail/llvm-bugs/)
`Bugs & Patches Archive (llvm-bugs)`__
This list gets emailed every time a bug is opened and closed. It is
higher volume than the LLVM-dev list.
.. __: http://lists.llvm.org/pipermail/llvm-bugs/
* [LLVM Announcements](https://discourse.llvm.org/c/announce/46)
`LLVM Announcements`__
If you just want project-wide announcements such as releases, developers meetings, or blog posts, then you should check out the Announcement category on LLVM Discourse.
.. __: https://discourse.llvm.org/c/announce/46
(online-sync-ups)=
.. _online-sync-ups:
Online Sync-Ups
---------------
## Online Sync-Ups
A number of regular calls are organized on specific topics. It should be
expected that the range of topics will change over time. At the time of
writing, the following sync-ups are organized.
The :doc:`CodeOfConduct` applies to all online sync-ups.
The {doc}`CodeOfConduct` applies to all online sync-ups.
If you'd like to organize a new sync-up, please add the info in the table
below. Please also create a calendar event for it and invite calendar@llvm.org
to the event, so that it'll show up on the :ref:`llvm-community-calendar`.
Please see :ref:`llvm-community-calendar-host-guidance` for more guidance on
to the event, so that it'll show up on the {ref}`llvm-community-calendar`.
Please see {ref}`llvm-community-calendar-host-guidance` for more guidance on
what to add to your calendar invite.
.. list-table:: LLVM regular sync-up calls
:widths: 25 25 25 25
:header-rows: 1
```{list-table} LLVM regular sync-up calls
:widths: 25 25 25 25
:header-rows: 1
* - Topic
- Frequency
@ -151,116 +162,116 @@ what to add to your calendar invite.
- Minutes/docs link
* - Loop Optimization Working Group
- Every first Wednesday of the month
- `ics <./_static/LoopOptWG_invite.ics>`__
- `Minutes/docs <https://docs.google.com/document/d/1sdzoyB11s0ccTZ3fobqctDpgJmRoFcz0sviKxqczs4g/edit>`__
- [ics](./_static/LoopOptWG_invite.ics)
- [Minutes/docs](https://docs.google.com/document/d/1sdzoyB11s0ccTZ3fobqctDpgJmRoFcz0sviKxqczs4g/edit)
* - RISC-V
- Every 2 weeks on Thursday
- `ics <https://calendar.google.com/calendar/ical/lowrisc.org_0n5pkesfjcnp0bh5hps1p0bd80%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/b/1?cid=bG93cmlzYy5vcmdfMG41cGtlc2ZqY25wMGJoNWhwczFwMGJkODBAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ>`__
- `Minutes/docs <https://docs.google.com/document/d/1G3ocHm2zE6AYTS2N3_3w2UxFnSEyKkcF57siLWe-NVs>`__
- [ics](https://calendar.google.com/calendar/ical/lowrisc.org_0n5pkesfjcnp0bh5hps1p0bd80%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/b/1?cid=bG93cmlzYy5vcmdfMG41cGtlc2ZqY25wMGJoNWhwczFwMGJkODBAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ)
- [Minutes/docs](https://docs.google.com/document/d/1G3ocHm2zE6AYTS2N3_3w2UxFnSEyKkcF57siLWe-NVs)
* - ML Guided Compiler Optimizations
- Monthly
-
- `Minutes/docs <https://docs.google.com/document/d/1JecbplF09l3swTjze-UVeLh4L48svJxGVy4mz_e9Rhs/edit?usp=gmail#heading=h.ts9cmcjbir1j>`__
* - `LLVM security group <https://llvm.org/docs/Security.html>`__
- [Minutes/docs](https://docs.google.com/document/d/1JecbplF09l3swTjze-UVeLh4L48svJxGVy4mz_e9Rhs/edit?usp=gmail#heading=h.ts9cmcjbir1j)
* - [LLVM security group](https://llvm.org/docs/Security.html)
- Monthly, every 3rd Tuesday
- `ics <https://calendar.google.com/calendar/ical/eoh3m9k1l6vqbd1fkp94fv5q74%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/embed?src=eoh3m9k1l6vqbd1fkp94fv5q74%40group.calendar.google.com>`__
- `Minutes/docs <https://discourse.llvm.org/t/llvm-security-group-public-sync-ups/62735>`__
* - `CIRCT <https://github.com/llvm/circt>`__
- [ics](https://calendar.google.com/calendar/ical/eoh3m9k1l6vqbd1fkp94fv5q74%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/embed?src=eoh3m9k1l6vqbd1fkp94fv5q74%40group.calendar.google.com)
- [Minutes/docs](https://discourse.llvm.org/t/llvm-security-group-public-sync-ups/62735)
* - [CIRCT](https://github.com/llvm/circt)
- Weekly, on Wednesday
-
- `Minutes/docs <https://docs.google.com/document/d/1fOSRdyZR2w75D87yU2Ma9h2-_lEPL4NxvhJGJd-s5pk/edit#heading=h.mulvhjtr8dk9>`__
- [Minutes/docs](https://docs.google.com/document/d/1fOSRdyZR2w75D87yU2Ma9h2-_lEPL4NxvhJGJd-s5pk/edit#heading=h.mulvhjtr8dk9)
* - flang
- Multiple meeting series, `documented here <https://github.com/llvm/llvm-project/blob/main/flang/docs/GettingInvolved.md#calls>`__
- Multiple meeting series, [documented here](https://github.com/llvm/llvm-project/blob/main/flang/docs/GettingInvolved.md#calls)
-
-
* - OpenMP
- Multiple meeting series, `documented here <https://openmp.llvm.org/docs/SupportAndFAQ.html>`__
- Multiple meeting series, [documented here](https://openmp.llvm.org/docs/SupportAndFAQ.html)
-
-
* - LLVM Alias Analysis
- Every 4 weeks on Tuesdays
- `ics <http://lists.llvm.org/pipermail/llvm-dev/attachments/20201103/a3499a67/attachment-0001.ics>`__
- `Minutes/docs <https://docs.google.com/document/d/17U-WvX8qyKc3S36YUKr3xfF-GHunWyYowXbxEdpHscw>`__
- [ics](http://lists.llvm.org/pipermail/llvm-dev/attachments/20201103/a3499a67/attachment-0001.ics)
- [Minutes/docs](https://docs.google.com/document/d/17U-WvX8qyKc3S36YUKr3xfF-GHunWyYowXbxEdpHscw)
* - LLVM Pointer Authentication
- Every month on Mondays
- `ics <https://calendar.google.com/calendar/ical/fr1qtmrmt2s9odufjvurkb6j70%40group.calendar.google.com/public/basic.ics>`__
- `Minutes/docs <https://discourse.llvm.org/t/llvm-pointer-authentication-sync-ups/62661>`__
- [ics](https://calendar.google.com/calendar/ical/fr1qtmrmt2s9odufjvurkb6j70%40group.calendar.google.com/public/basic.ics)
- [Minutes/docs](https://discourse.llvm.org/t/llvm-pointer-authentication-sync-ups/62661)
* - LLVM Embedded Toolchains
- Every 4 weeks on Thursdays
- `ics <https://drive.google.com/file/d/1uNa-PFYkhAfT83kR2Nc4Fi706TAQFBEL/view?usp=sharing>`__
`gcal <https://calendar.google.com/calendar/u/0?cid=ZDQyc3ZlajJmbjIzNG1jaTUybjFsdjA2dWNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ>`__
- `Minutes/docs <https://docs.google.com/document/d/1GahxppHJ7o1O_fn1Mbidu1DHEg7V2aOr92LXCtNV1_o/edit?usp=sharing>`__
- [ics](https://drive.google.com/file/d/1uNa-PFYkhAfT83kR2Nc4Fi706TAQFBEL/view?usp=sharing)
[gcal](https://calendar.google.com/calendar/u/0?cid=ZDQyc3ZlajJmbjIzNG1jaTUybjFsdjA2dWNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ)
- [Minutes/docs](https://docs.google.com/document/d/1GahxppHJ7o1O_fn1Mbidu1DHEg7V2aOr92LXCtNV1_o/edit?usp=sharing)
* - Clang C and C++ Language Working Group
- 1st and 3rd Wednesday of the month
-
- `Minutes/docs <https://docs.google.com/document/d/1x5-RbOC6-jnI_NcJ9Dp4pSmGhhNe7lUevuWUIB46TeM/edit?usp=sharing>`__
- [Minutes/docs](https://docs.google.com/document/d/1x5-RbOC6-jnI_NcJ9Dp4pSmGhhNe7lUevuWUIB46TeM/edit?usp=sharing)
* - LLVM SPIR-V Backend Working Group
- Every week on Monday
-
- `Meeting details/agenda <https://docs.google.com/document/d/1UjX-LAwPjJ75Nmb8a5jz-Qrm-pPtKtQw0k1S1Lop9jU/edit?usp=sharing>`__
- [Meeting details/agenda](https://docs.google.com/document/d/1UjX-LAwPjJ75Nmb8a5jz-Qrm-pPtKtQw0k1S1Lop9jU/edit?usp=sharing)
* - SYCL Upstream Working Group
- Every 2 weeks on Mondays
- `gcal <https://calendar.google.com/calendar/u/0?cid=c3ljbC5sbHZtLndnQGdtYWlsLmNvbQ>`__
- `Meeting details/agenda <https://docs.google.com/document/d/1ivYDSn_5ChTeiZ7TiO64WC_jYJnGwAUiT9Ngi9cAdFU/edit?usp=sharing>`__
- [gcal](https://calendar.google.com/calendar/u/0?cid=c3ljbC5sbHZtLndnQGdtYWlsLmNvbQ)
- [Meeting details/agenda](https://docs.google.com/document/d/1ivYDSn_5ChTeiZ7TiO64WC_jYJnGwAUiT9Ngi9cAdFU/edit?usp=sharing)
* - Formal Semantics Working Group
- Every 2 weeks on Mondays
- `gcal <https://calendar.google.com/calendar/event?eid=aHJpNnNzb3Zia3FtNzNuYjdpbmJtZG5nZGVfMjAyNjA1MDRUMTUzMDAwWiBjYWxlbmRhckBsbHZtLm9yZw>`__
- `Meeting notes <https://docs.google.com/document/d/1muS2gZ7PUhbypbl0bmjb2J-UUzY7K8AO9a8RHVw_Mjo/edit?tab=t.0>`__
- [gcal](https://calendar.google.com/calendar/event?eid=aHJpNnNzb3Zia3FtNzNuYjdpbmJtZG5nZGVfMjAyNjA1MDRUMTUzMDAwWiBjYWxlbmRhckBsbHZtLm9yZw)
- [Meeting notes](https://docs.google.com/document/d/1muS2gZ7PUhbypbl0bmjb2J-UUzY7K8AO9a8RHVw_Mjo/edit?tab=t.0)
* - Vectorizer Improvement Working Group
- 3rd Tuesday of the month
- `ics <https://www.icloud.com/iclouddrive/032PeZzdN6U4uRMwJRJPrS2Lw#Vectorizer_Improvements>`__
- `Meeting details/agenda: <https://docs.google.com/document/d/1Glzy2JiWuysbD-HBWGUOkZqT09GJ4_Ljodr0lXD5XfQ/edit>`__
* - `LLVM Qualification Working Group <https://llvm.org/docs/QualGroup.html>`__
- [ics](https://www.icloud.com/iclouddrive/032PeZzdN6U4uRMwJRJPrS2Lw#Vectorizer_Improvements)
- [Meeting details/agenda:](https://docs.google.com/document/d/1Glzy2JiWuysbD-HBWGUOkZqT09GJ4_Ljodr0lXD5XfQ/edit)
* - [LLVM Qualification Working Group](https://llvm.org/docs/QualGroup.html)
- Monthly: 2nd Tuesday (EU/Asia) and 2nd Friday JST / Thursday (Americas)
- `ics <https://calendar.google.com/calendar/ical/f731f5b57956a132f6c553ed30f496b16e1018f831be13eb6c4b896c108a6626%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/embed?src=f731f5b57956a132f6c553ed30f496b16e1018f831be13eb6c4b896c108a6626%40group.calendar.google.com&ctz=Asia%2FTokyo>`__
- `Minutes/docs <https://discourse.llvm.org/t/llvm-qualification-wg-sync-ups-meeting-minutes/87148>`__
- [ics](https://calendar.google.com/calendar/ical/f731f5b57956a132f6c553ed30f496b16e1018f831be13eb6c4b896c108a6626%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/embed?src=f731f5b57956a132f6c553ed30f496b16e1018f831be13eb6c4b896c108a6626%40group.calendar.google.com&ctz=Asia%2FTokyo)
- [Minutes/docs](https://discourse.llvm.org/t/llvm-qualification-wg-sync-ups-meeting-minutes/87148)
* - MLIR C/C++ Frontend Working Group
- Monthly, usually 1st Monday of the month
- `ics <https://calendar.google.com/calendar/ical/jvceakm3kbpku3f4jrsv1lkigo%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/embed?src=jvceakm3kbpku3f4jrsv1lkigo%40group.calendar.google.com&ctz=America%2FLos_Angeles>`__
- `Minutes/docs <https://docs.google.com/document/d/1-flHK3TjQUrkSO2Fdt4webZ2zCyeXxpTLMiRQbMW7hE>`__
- [ics](https://calendar.google.com/calendar/ical/jvceakm3kbpku3f4jrsv1lkigo%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/embed?src=jvceakm3kbpku3f4jrsv1lkigo%40group.calendar.google.com&ctz=America%2FLos_Angeles)
- [Minutes/docs](https://docs.google.com/document/d/1-flHK3TjQUrkSO2Fdt4webZ2zCyeXxpTLMiRQbMW7hE)
* - ClangIR Upstreaming Coordination Meeting
- Every 2 weeks on Mondays
- `ics <https://calendar.google.com/calendar/ical/c_673c6cd64474c0aff173bf8fa609559f93d654e0984d9d91d71abd32d28c0486%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/embed?src=c_673c6cd64474c0aff173bf8fa609559f93d654e0984d9d91d71abd32d28c0486%40group.calendar.google.com&ctz=America%2FLos_Angeles>`__
- [ics](https://calendar.google.com/calendar/ical/c_673c6cd64474c0aff173bf8fa609559f93d654e0984d9d91d71abd32d28c0486%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/embed?src=c_673c6cd64474c0aff173bf8fa609559f93d654e0984d9d91d71abd32d28c0486%40group.calendar.google.com&ctz=America%2FLos_Angeles)
-
* - GlobalISel
- Every 2nd Tuesday of the month
- `gcal <https://calendar.google.com/calendar/u/0?cid=YWZjNzhmMzE4MDNlNTAyNGY1NmE1MDIyODY0YTYwZmJmYzRjYTEwNTE1NmUxODA2NzBkYTliY2ZhYTVkNjk0NUBncm91cC5jYWxlbmRhci5nb29nbGUuY29t>`__
- `Meeting details/agenda <https://docs.google.com/document/d/1Ry8O4-Tm5BFj9AMjr8qTQFU80z-ptiNQ62687NaIvLs/edit?usp=sharing>`__
- [gcal](https://calendar.google.com/calendar/u/0?cid=YWZjNzhmMzE4MDNlNTAyNGY1NmE1MDIyODY0YTYwZmJmYzRjYTEwNTE1NmUxODA2NzBkYTliY2ZhYTVkNjk0NUBncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
- [Meeting details/agenda](https://docs.google.com/document/d/1Ry8O4-Tm5BFj9AMjr8qTQFU80z-ptiNQ62687NaIvLs/edit?usp=sharing)
* - Clang Static Analysis Working Group
- Every 2 weeks on Tuesdays
- `ics <https://calendar.google.com/calendar/ical/9c23f3a54dbb4fbac3801c50094fc43118a37c186f5c65b2898cd0fc251c8610%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/u/0?cid=OWMyM2YzYTU0ZGJiNGZiYWMzODAxYzUwMDk0ZmM0MzExOGEzN2MxODZmNWM2NWIyODk4Y2QwZmMyNTFjODYxMEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t>`__
- `Meeting notes <https://docs.google.com/document/d/1ijI8pWeyidmhFOd5Ndgvr5AziZwrMCbt2oUehv8qHmw/edit?usp=sharing>`__
- [ics](https://calendar.google.com/calendar/ical/9c23f3a54dbb4fbac3801c50094fc43118a37c186f5c65b2898cd0fc251c8610%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/u/0?cid=OWMyM2YzYTU0ZGJiNGZiYWMzODAxYzUwMDk0ZmM0MzExOGEzN2MxODZmNWM2NWIyODk4Y2QwZmMyNTFjODYxMEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
- [Meeting notes](https://docs.google.com/document/d/1ijI8pWeyidmhFOd5Ndgvr5AziZwrMCbt2oUehv8qHmw/edit?usp=sharing)
* - LLVM Memory Safety Working Group
- Every 4 weeks on Thursdays
- `ics <https://calendar.google.com/calendar/ical/2d77f9a2624d18cd46e5299d15cc0fa0c90dca53fd68802261d52121d21a0573%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/u/0?cid=MmQ3N2Y5YTI2MjRkMThjZDQ2ZTUyOTlkMTVjYzBmYTBjOTBkY2E1M2ZkNjg4MDIyNjFkNTIxMjFkMjFhMDU3M0Bncm91cC5jYWxlbmRhci5nb29nbGUuY29t>`__
- `Meeting notes <https://docs.google.com/document/d/1DkCik6BTnO-cox_9y_BTKzPaJJOo_hBxiNFP3lInvOM/edit?usp=sharing>`__
* - `Lifetime Safety Breakout Group <https://github.com/orgs/llvm/projects/39>`__
- [ics](https://calendar.google.com/calendar/ical/2d77f9a2624d18cd46e5299d15cc0fa0c90dca53fd68802261d52121d21a0573%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/u/0?cid=MmQ3N2Y5YTI2MjRkMThjZDQ2ZTUyOTlkMTVjYzBmYTBjOTBkY2E1M2ZkNjg4MDIyNjFkNTIxMjFkMjFhMDU3M0Bncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
- [Meeting notes](https://docs.google.com/document/d/1DkCik6BTnO-cox_9y_BTKzPaJJOo_hBxiNFP3lInvOM/edit?usp=sharing)
* - [Lifetime Safety Breakout Group](https://github.com/orgs/llvm/projects/39)
- Every 2 weeks on Wednesdays
- `ics <https://calendar.google.com/calendar/ical/2d77f9a2624d18cd46e5299d15cc0fa0c90dca53fd68802261d52121d21a0573%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/u/0?cid=MmQ3N2Y5YTI2MjRkMThjZDQ2ZTUyOTlkMTVjYzBmYTBjOTBkY2E1M2ZkNjg4MDIyNjFkNTIxMjFkMjFhMDU3M0Bncm91cC5jYWxlbmRhci5nb29nbGUuY29t>`__
- `Meeting notes <https://docs.google.com/document/d/1DkCik6BTnO-cox_9y_BTKzPaJJOo_hBxiNFP3lInvOM/edit?tab=t.nvvd6cfloi81>`__
- [ics](https://calendar.google.com/calendar/ical/2d77f9a2624d18cd46e5299d15cc0fa0c90dca53fd68802261d52121d21a0573%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/u/0?cid=MmQ3N2Y5YTI2MjRkMThjZDQ2ZTUyOTlkMTVjYzBmYTBjOTBkY2E1M2ZkNjg4MDIyNjFkNTIxMjFkMjFhMDU3M0Bncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
- [Meeting notes](https://docs.google.com/document/d/1DkCik6BTnO-cox_9y_BTKzPaJJOo_hBxiNFP3lInvOM/edit?tab=t.nvvd6cfloi81)
```
For event owners, our Discord bot also supports sending automated announcements
of upcoming sync-ups. Please see the :ref:`discord-bot-event-pings` section for
of upcoming sync-ups. Please see the {ref}`discord-bot-event-pings` section for
info.
Past online sync-ups
^^^^^^^^^^^^^^^^^^^^
### Past online sync-ups
Some online sync-ups are no longer happening. We keep pointing to them here to
keep track of the meeting notes and in case anyone would want to revive them in
the future.
.. list-table:: LLVM no-longer-happening sync-up calls
:widths: 25 25 25 25
:header-rows: 1
```{list-table} LLVM no-longer-happening sync-up calls
:widths: 25 25 25 25
:header-rows: 1
* - Topic
- Frequency
@ -268,42 +279,42 @@ the future.
- Minutes/docs link
* - Scalable Vectors and Arm SVE
- Monthly, every 3rd Tuesday
- `ics <https://calendar.google.com/calendar/ical/bjms39pe6k6bo5egtsp7don414%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/u/0/embed?src=bjms39pe6k6bo5egtsp7don414@group.calendar.google.com>`__
- `Minutes/docs <https://docs.google.com/document/d/1UPH2Hzou5RgGT8XfO39OmVXKEibWPfdYLELSaHr3xzo/edit>`__
- [ics](https://calendar.google.com/calendar/ical/bjms39pe6k6bo5egtsp7don414%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/u/0/embed?src=bjms39pe6k6bo5egtsp7don414@group.calendar.google.com)
- [Minutes/docs](https://docs.google.com/document/d/1UPH2Hzou5RgGT8XfO39OmVXKEibWPfdYLELSaHr3xzo/edit)
* - MemorySSA in LLVM
- Every 8 weeks on Mondays
- `ics <https://calendar.google.com/calendar/ical/c_1mincouiltpa24ac14of14lhi4%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/embed?src=c_1mincouiltpa24ac14of14lhi4%40group.calendar.google.com>`__
- `Minutes/docs <https://docs.google.com/document/d/1-uEEZfmRdPThZlctOq9eXlmUaSSAAi8oKxhrPY_lpjk/edit#>`__
- [ics](https://calendar.google.com/calendar/ical/c_1mincouiltpa24ac14of14lhi4%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/embed?src=c_1mincouiltpa24ac14of14lhi4%40group.calendar.google.com)
- [Minutes/docs](https://docs.google.com/document/d/1-uEEZfmRdPThZlctOq9eXlmUaSSAAi8oKxhrPY_lpjk/edit#)
* - Vector Predication
- Every 2 weeks on Tuesdays, 3pm UTC
-
- `Minutes/docs <https://docs.google.com/document/d/1q26ToudQjnqN5x31zk8zgq_s0lem1-BF8pQmciLa4k8/edit?usp=sharing>`__
* - `MLIR <https://mlir.llvm.org>`__ design meetings
- [Minutes/docs](https://docs.google.com/document/d/1q26ToudQjnqN5x31zk8zgq_s0lem1-BF8pQmciLa4k8/edit?usp=sharing)
* - [MLIR](https://mlir.llvm.org) design meetings
- Weekly, on Thursdays
-
- `Minutes/docs <https://docs.google.com/document/d/1y_9f1AbfgcoVdJh4_aM6-BaSHvrHl8zuA5G4jv_94K8/edit#heading=h.cite1kolful9>`__
- [Minutes/docs](https://docs.google.com/document/d/1y_9f1AbfgcoVdJh4_aM6-BaSHvrHl8zuA5G4jv_94K8/edit#heading=h.cite1kolful9)
```
.. _office-hours:
(office-hours)=
Office hours
------------
## Office hours
A number of experienced LLVM contributors make themselves available for a chat
on a regular schedule, to anyone who is looking for some guidance. Please find
the list of who is available when, through which medium, and what their area of
expertise is. Don't be too shy to dial in!
Office hours are also listed on the :ref:`llvm-community-calendar`. Of course,
Office hours are also listed on the {ref}`llvm-community-calendar`. Of course,
people take time off from time to time, so if you dial in and you don't find
anyone present, chances are they happen to be off that day.
The :doc:`CodeOfConduct` applies to all office hours.
The {doc}`CodeOfConduct` applies to all office hours.
.. list-table:: LLVM office hours
:widths: 15 40 15 15 15
:header-rows: 1
```{list-table} LLVM office hours
:widths: 15 40 15 15 15
:header-rows: 1
* - Name
- In-scope topics
@ -315,92 +326,92 @@ The :doc:`CodeOfConduct` applies to all office hours.
submitting talks; and other general LLVM-related topics. Arm/AArch64
codegen. LLVM security group. LLVM Office Hours.
- Every 2nd and 4th Wednesday of the month at 9.30am CET, for 30 minutes.
`ics <https://user.fm/calendar/v1-eac36694e3024854a9402da023f9e0fa/Kristof%20Beyls%20LLVM%20office%20hours.ics>`__
- `Jitsi <https://meet.jit.si/KristofBeylsLLVMOfficeHour>`__
[ics](https://user.fm/calendar/v1-eac36694e3024854a9402da023f9e0fa/Kristof%20Beyls%20LLVM%20office%20hours.ics)
- [Jitsi](https://meet.jit.si/KristofBeylsLLVMOfficeHour)
- English, Flemish, Dutch
* - Alina Sbirlea
- General questions on how to contribute to LLVM; women in compilers;
MemorySSA, BatchAA, various loop passes, new pass manager.
- Monthly, 2nd Tuesdays, 10.00am PT/7:00pm CET, for 30 minutes.
`ics <https://calendar.google.com/calendar/ical/c_pm6e7160iq7n5fcm1s6m3rjhh4%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/embed?src=c_pm6e7160iq7n5fcm1s6m3rjhh4%40group.calendar.google.com>`__
- `GoogleMeet <https://meet.google.com/hhk-xpdj-gvx>`__
[ics](https://calendar.google.com/calendar/ical/c_pm6e7160iq7n5fcm1s6m3rjhh4%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/embed?src=c_pm6e7160iq7n5fcm1s6m3rjhh4%40group.calendar.google.com)
- [GoogleMeet](https://meet.google.com/hhk-xpdj-gvx)
- English, Romanian
* - Aaron Ballman (he/him)
- Clang internals; frontend attributes; clang-tidy; clang-query; AST matchers
- Monthly, 2nd Monday and 3rd Friday of the month at 10:00am Eastern and again at 2:00pm Eastern, for 60 minutes.
`ics <https://calendar.google.com/calendar/ical/npgke5dug0uliud0qapptmps58%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/embed?src=npgke5dug0uliud0qapptmps58%40group.calendar.google.com>`__
- `GoogleMeet <https://meet.google.com/xok-iqne-gmi>`__
[ics](https://calendar.google.com/calendar/ical/npgke5dug0uliud0qapptmps58%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/embed?src=npgke5dug0uliud0qapptmps58%40group.calendar.google.com)
- [GoogleMeet](https://meet.google.com/xok-iqne-gmi)
- English, Norwegian (not fluently)
* - Johannes Doerfert (he/him)
- OpenMP, LLVM-IR, interprocedural optimizations, Attributor, workshops, research, ...
- Every week, Wednesdays 9:30am (Pacific Time), for 1 hour.
`ics <https://drive.google.com/file/d/1E_QkRvirmdJzlXf2EKBUX-v8Xj7-eW3v/view?usp=sharing>`__
- `MS Teams <https://teams.microsoft.com/l/meetup-join/19%3ameeting_MTMxNzU4MWYtYzViNS00OTM2LWJmNWQtMjg5ZWFhNGVjNzgw%40thread.v2/0?context=%7b%22Tid%22%3a%22a722dec9-ae4e-4ae3-9d75-fd66e2680a63%22%2c%22Oid%22%3a%22885bda30-ce8e-46db-aa7e-15de0474831a%22%7d>`__
[ics](https://drive.google.com/file/d/1E_QkRvirmdJzlXf2EKBUX-v8Xj7-eW3v/view?usp=sharing)
- [MS Teams](https://teams.microsoft.com/l/meetup-join/19%3ameeting_MTMxNzU4MWYtYzViNS00OTM2LWJmNWQtMjg5ZWFhNGVjNzgw%40thread.v2/0?context=%7b%22Tid%22%3a%22a722dec9-ae4e-4ae3-9d75-fd66e2680a63%22%2c%22Oid%22%3a%22885bda30-ce8e-46db-aa7e-15de0474831a%22%7d)
- English, German
* - Tobias Grosser
- General questions on how to contribute to LLVM/MLIR, Polly, Loop Optimization, FPL, Research in LLVM, PhD in CS, Summer of Code.
- Monthly, last Monday of the month at 18:00 London time (typically 9am PT), for 30 minutes.
- `Video Call <https://meet.grosser.science/LLVMOfficeHours>`__
- [Video Call](https://meet.grosser.science/LLVMOfficeHours)
- English, German, Spanish, French
* - Alexey Bader
- SYCL compiler, offload tools, OpenCL and SPIR-V, how to contribute.
- Monthly, 2nd Monday of the month at 9:30am PT, for 30 minutes.
- `GoogleMeet <https://meet.google.com/pdz-xhns-uus>`__
- [GoogleMeet](https://meet.google.com/pdz-xhns-uus)
- English, Russian
* - Maksim Panchenko
- BOLT internals, IR, new passes, proposals, etc.
- Monthly, 2nd Wednesday of the month at 11:00am PT, for 30 minutes.
- `Zoom <https://fb.zoom.us/j/97065697120?pwd=NTFaUWJjZW9uVkJuaVlPTE9qclE3dz09>`__
- [Zoom](https://fb.zoom.us/j/97065697120?pwd=NTFaUWJjZW9uVkJuaVlPTE9qclE3dz09)
- English, Russian
* - Quentin Colombet (he/him)
- LLVM/MLIR; Codegen (Instruction selection (GlobalISel/SDISel), Machine IR,
Register allocation, etc.); Optimizations; MCA
- Monthly, 1st Wednesday of the month at 8.00am PT, for 30 minutes.
`ics <https://calendar.google.com/calendar/ical/48c4ad60290a4df218e51e1ceec1106fe317b0ebc76938d9273592053f38204e%40group.calendar.google.com/public/basic.ics>`__
`gcal <https://calendar.google.com/calendar/embed?src=48c4ad60290a4df218e51e1ceec1106fe317b0ebc76938d9273592053f38204e%40group.calendar.google.com>`__
- `Google meet <https://meet.google.com/cbz-grrp-obs>`__
[ics](https://calendar.google.com/calendar/ical/48c4ad60290a4df218e51e1ceec1106fe317b0ebc76938d9273592053f38204e%40group.calendar.google.com/public/basic.ics)
[gcal](https://calendar.google.com/calendar/embed?src=48c4ad60290a4df218e51e1ceec1106fe317b0ebc76938d9273592053f38204e%40group.calendar.google.com)
- [Google meet](https://meet.google.com/cbz-grrp-obs)
- English, French
* - Phoebe Wang (she/her)
- X86 backend, General questions to X86, women in compilers.
- Monthly, 3rd Wednesday of the month at 8:30am Beijing time, for 30 minutes.
- `MS Teams <https://teams.microsoft.com/l/meetup-join/19%3ameeting_NWQ0MjU0NjYtZjUyMi00YTU3LThmM2EtY2Y2YTE4NGM3NmFi%40thread.v2/0?context=%7b%22Tid%22%3a%2246c98d88-e344-4ed4-8496-4ed7712e255d%22%2c%22Oid%22%3a%227b309d9c-a9bb-44c8-a940-ab97eef42d4d%22%7d>`__
- [MS Teams](https://teams.microsoft.com/l/meetup-join/19%3ameeting_NWQ0MjU0NjYtZjUyMi00YTU3LThmM2EtY2Y2YTE4NGM3NmFi%40thread.v2/0?context=%7b%22Tid%22%3a%2246c98d88-e344-4ed4-8496-4ed7712e255d%22%2c%22Oid%22%3a%227b309d9c-a9bb-44c8-a940-ab97eef42d4d%22%7d)
- English, Chinese
* - Amara Emerson
- GlobalISel questions.
- Monthly, 4th Wednesday of the month at 9:30am PT, for 30 minutes.
- `Google meet <https://meet.google.com/pdd-dibg-cwv>`__
- [Google meet](https://meet.google.com/pdd-dibg-cwv)
- English
* - Maksim Levental and Jeremy Kun
- MLIR newcomers and general discussion (`livestreamed <https://www.youtube.com/playlist?list=PLhxO86S3jsX2k7kOhZaV-qKWm8tNsUdAE>`__)
- MLIR newcomers and general discussion ([livestreamed](https://www.youtube.com/playlist?list=PLhxO86S3jsX2k7kOhZaV-qKWm8tNsUdAE))
- Every two weeks, Wednesdays at 2:00pm US Pacific, for 90 minutes.
- Livestream chat or `Google meet <https://meet.google.com/wit-tvzc-dwc>`__
- Livestream chat or [Google meet](https://meet.google.com/wit-tvzc-dwc)
- English
* - Renato Golin
- General LLVM, MLIR & Linalg, distributed computing, research, socials.
- Every first Friday of the month, 14:00 UK time, for 60 minutes.
- `Google meet <https://meet.google.com/jps-twgq-ivz>`__
- [Google meet](https://meet.google.com/jps-twgq-ivz)
- English, Portuguese
```
For event owners, our Discord bot also supports sending automated announcements
of upcoming office hours. Please see the :ref:`discord-bot-event-pings` section
of upcoming office hours. Please see the {ref}`discord-bot-event-pings` section
for info.
Guidance for office hours hosts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
### Guidance for office hours hosts
* If you're interested in becoming an office hours host, please add your
information to the list above. Please create a calendar event for it and
invite calendar@llvm.org to the event so that it'll show up on the
:ref:`llvm-community-calendar`.
Please see :ref:`llvm-community-calendar-host-guidance` for more guidance on
{ref}`llvm-community-calendar`.
Please see {ref}`llvm-community-calendar-host-guidance` for more guidance on
what to add to your calendar invite.
* When starting an office hours session, if you haven't set up the Discord bot
integration, consider typing something like "*Hi, I'm available for chats in
the next half hour at* video chat URL. *I'm looking forward to having
conversations on the video chat or here.*" on the
`#office-hours Discord channel <https://discord.com/channels/636084430946959380/976196303681896538>`__.
[#office-hours Discord channel](https://discord.com/channels/636084430946959380/976196303681896538).
Doing this can help:
* overcome potential anxiety to call in for a first time,
@ -411,66 +422,66 @@ Guidance for office hours hosts
from the list above.
Discord
-------
## Discord
Users and developers of the LLVM project (including subprojects such as Clang)
can be found on the community's `Discord <https://discord.gg/xS7Z362>`_
can be found on the community's [Discord](https://discord.gg/xS7Z362)
chat server. The server is actively moderated.
The #buildbot-status channel has a bot for
`LLVM buildbot <http://lab.llvm.org/buildbot/#/console>`_ status changes. The
[LLVM buildbot](http://lab.llvm.org/buildbot/#/console) status changes. The
bot will update the channel with a link to a build bot when a build goes from
passing to failing and again when the build goes from failing back to passing.
It is a great way to actively monitor the status of the build.
The bot also supports @mention-ing you when your email appears on a blamelist.
For more details, DM ``help`` to the bot.
For more details, DM `help` to the bot.
.. _discord-bot-event-pings:
(discord-bot-event-pings)=
Discord bot event pings
^^^^^^^^^^^^^^^^^^^^^^^
### Discord bot event pings
Our Discord bot supports automatically sending messages about upcoming events
on `the LLVM community calendar <https://calendar.google.com/calendar/u/0/embed?src=calendar@llvm.org>`_
on [the LLVM community calendar](https://calendar.google.com/calendar/u/0/embed?src=calendar@llvm.org)
to Discord. This behavior is controlled on a per-event basis, by metadata in the
event's description. Each piece of metadata should be on its own line in the
event description.
The currently supported metadata is:
- ``discord-bot-event-type`` - **Required**. Specifies the event type. Valid
values are ``office-hours`` and ``sync-up``.
- ``discord-bot-channels-to-mention`` - **Sometimes required**. A
- `discord-bot-event-type` - **Required**. Specifies the event type. Valid
values are `office-hours` and `sync-up`.
- `discord-bot-channels-to-mention` - **Sometimes required**. A
comma-separated list of Discord channels to post notifications in. If your
``discord-bot-event-type`` is ``office-hours``, the ``#office-hours`` channel
`discord-bot-event-type` is `office-hours`, the `#office-hours` channel
will be implicitly appended to this list (ergo, you don't need to specify this
item). Otherwise, you must specify a value here.
- ``discord-bot-mention`` - **Optional**. A comma-separated list of people to
- `discord-bot-mention` - **Optional**. A comma-separated list of people to
ping on each event notification. All names mentioned must be Discord
usernames, and must have a leading ``@``. e.g., ``@foo, @bar``.
- ``discord-bot-reminder-time-before-start`` - **Optional**. The number of
usernames, and must have a leading `@`. e.g., `@foo, @bar`.
- `discord-bot-reminder-time-before-start` - **Optional**. The number of
minutes before the beginning of an event to send a ping. This should be
formatted as an integer. Defaults to 30.
- ``discord-bot-message`` - **Optional**. Text to append to all event pings.
- `discord-bot-message` - **Optional**. Text to append to all event pings.
An example of an event description with valid metadata is::
An example of an event description with valid metadata is:
Regular office hours to chat with people about LLVM! We can help with
questions, troubleshooting bugs, etc.
```text
Regular office hours to chat with people about LLVM! We can help with
questions, troubleshooting bugs, etc.
discord-bot-channels-to-mention: #beginners, #foo
discord-bot-event-type: office-hours
discord-bot-mention: @gburgessiv, @bar
discord-bot-message: Come join us for office hours!
discord-bot-reminder-time-before-start: 5
discord-bot-channels-to-mention: #beginners, #foo
discord-bot-event-type: office-hours
discord-bot-mention: @gburgessiv, @bar
discord-bot-message: Come join us for office hours!
discord-bot-reminder-time-before-start: 5
```
This metadata will prompt the Discord bot to:
* send pings 5 minutes before the given event starts, mentioning ``@gburgessiv``
and ``@bar`` in the ping
* send the pings to the ``#beginners``, ``#foo``, and ``#office-hours`` channels
* send pings 5 minutes before the given event starts, mentioning `@gburgessiv`
and `@bar` in the ping
* send the pings to the `#beginners`, `#foo`, and `#office-hours` channels
* include the text "Come join us for office hours!" in the ping
A few minutes before sending a ping, the bot will double-check that the event
@ -479,79 +490,82 @@ hasn't been cancelled.
If you need help troubleshooting, or have feature requests/questions, please
feel free to ping @gburgessiv!
.. _meetups-social-events:
(meetups-social-events)=
Meetups and social events
-------------------------
## Meetups and social events
.. toctree::
:hidden:
```{toctree}
:hidden:
MeetupGuidelines
MeetupGuidelines
```
Besides developer `meetings and conferences <https://llvm.org/devmtg/>`_,
Besides developer [meetings and conferences](https://llvm.org/devmtg/),
there are several user groups called
`LLVM Socials <https://www.meetup.com/pro/llvm/>`_. We greatly encourage you to
[LLVM Socials](https://www.meetup.com/pro/llvm/). We greatly encourage you to
join one in your city. Or start a new one if there is none:
:doc:`MeetupGuidelines`
{doc}`MeetupGuidelines`
.. _community-proposals:
(community-proposals)=
Community wide proposals
------------------------
## Community wide proposals
Proposals for large-scale changes in how the community behaves and how the work flow
can be better.
.. toctree::
:hidden:
```{toctree}
:hidden:
Proposals/GitHubMove
BugpointRedesign
Proposals/TestSuite
Proposals/VariableNames
Proposals/VectorPredication
Proposals/GitHubMove
BugpointRedesign
Proposals/TestSuite
Proposals/VariableNames
Proposals/VectorPredication
```
:doc:`Proposals/GitHubMove`
Proposal to move from SVN/Git to GitHub.
* {doc}`Proposals/GitHubMove`
:doc:`BugpointRedesign`
Design doc for a redesign of the Bugpoint tool.
Proposal to move from SVN/Git to GitHub.
:doc:`Proposals/TestSuite`
Proposals for additional benchmarks/programs for llvm's test-suite.
* {doc}`BugpointRedesign`
:doc:`Proposals/VariableNames`
Proposal to change the variable names coding standard.
Design doc for a redesign of the Bugpoint tool.
:doc:`Proposals/VectorPredication`
Proposal for predicated vector instructions in LLVM.
* {doc}`Proposals/TestSuite`
.. _llvm-community-calendar:
Proposals for additional benchmarks/programs for llvm's test-suite.
LLVM community calendar
-----------------------
* {doc}`Proposals/VariableNames`
Proposal to change the variable names coding standard.
* {doc}`Proposals/VectorPredication`
Proposal for predicated vector instructions in LLVM.
(llvm-community-calendar)=
## LLVM community calendar
We aim to maintain a public calendar view of all events happening in the LLVM
community such as :ref:`online-sync-ups` and :ref:`office-hours`. The calendar
community such as {ref}`online-sync-ups` and {ref}`office-hours`. The calendar
can be found at
https://calendar.google.com/calendar/u/0/embed?src=calendar@llvm.org and can
also be seen inline below:
.. raw:: html
<iframe src="https://calendar.google.com/calendar/embed?height=600&wkst=1&bgcolor=%23ffffff&ctz=UTC&showCalendars=0&showDate=1&showNav=1&src=Y2FsZW5kYXJAbGx2bS5vcmc&color=%23039BE5" style="border:solid 1px #777" width="800" height="600" frameborder="0" scrolling="no"></iframe>
```{raw} html
<iframe src="https://calendar.google.com/calendar/embed?height=600&wkst=1&bgcolor=%23ffffff&ctz=UTC&showCalendars=0&showDate=1&showNav=1&src=Y2FsZW5kYXJAbGx2bS5vcmc&color=%23039BE5" style="border:solid 1px #777" width="800" height="600" frameborder="0" scrolling="no"></iframe>
```
Note that the web view of the LLVM community calendar shows events in
Coordinated Universal Time (UTC). If you use Google Calendar, consider
subscribing to it with the + button in the bottom-right corner to view all
events in your local time zone alongside your other calendars.
.. _llvm-community-calendar-host-guidance:
(llvm-community-calendar-host-guidance)=
Guidance on what to put into LLVM community calendar invites
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
### Guidance on what to put into LLVM community calendar invites
To add your event, create a calendar event for it and invite calendar@llvm.org
on it. Your event should then show up on the community calendar.
@ -560,7 +574,7 @@ Please put the following pieces of information in your calendar invite:
* Write a single paragraph describing what the event is about. Include things
such as who the event is for and what sort of topics are discussed.
* State explicitly that the :doc:`CodeOfConduct` applies to this event.
* State explicitly that the {doc}`CodeOfConduct` applies to this event.
* Make it clear who:
* the organizer is.
@ -573,25 +587,25 @@ Please put the following pieces of information in your calendar invite:
* If you're hosting a sync-up or office hours event and would like it to be
announced by the Discord bot, add the relevant metadata (full descriptions
available in the :ref:`discord-bot-event-pings` section).
available in the {ref}`discord-bot-event-pings` section).
An example invite looks as follows
.. code-block:: none
```text
This event is a meetup for all developers of LLDB. Meeting agendas are posted
on Discourse before the event.
This event is a meetup for all developers of LLDB. Meeting agendas are posted
on Discourse before the event.
Attendees must adhere to the LLVM Code of Conduct
(https://llvm.org/docs/CodeOfConduct.html). For any Code of Conduct reports,
please contact the organizers and also email conduct@llvm.org.
Attendees must adhere to the LLVM Code of Conduct
(https://llvm.org/docs/CodeOfConduct.html). For any Code of Conduct reports,
please contact the organizers and also email conduct@llvm.org.
Agenda/Meeting Minutes: Link to minutes
Agenda/Meeting Minutes: Link to minutes
Organizer(s): First Surname (name@email.com)
Organizer(s): First Surname (name@email.com)
discord-bot-channels-to-mention: #lldb
discord-bot-event-type: sync-up
discord-bot-mention: @host-username, @another-host
discord-bot-message: Come join us to chat about LLDB!
discord-bot-reminder-time-before-start: 30
discord-bot-channels-to-mention: #lldb
discord-bot-event-type: sync-up
discord-bot-mention: @host-username, @another-host
discord-bot-message: Come join us to chat about LLDB!
discord-bot-reminder-time-before-start: 30
```

1031
llvm/docs/GettingStarted.md
View file

File diff suppressed because it is too large Load diff

68
llvm/docs/GettingStartedTutorials.md
View file

@ -1,47 +1,47 @@
Getting Started/Tutorials
=========================
# Getting Started/Tutorials
For those new to the LLVM system.
.. toctree::
:hidden:
```{toctree}
:hidden:
CompilerWriterInfo
Frontend/PerformanceTips
GettingStarted
GettingStartedVS
ProgrammersManual
DebuggingLLVM
tutorial/index
MyFirstTypoFix
CompilerWriterInfo
Frontend/PerformanceTips
GettingStarted
GettingStartedVS
ProgrammersManual
DebuggingLLVM
tutorial/index
MyFirstTypoFix
```
:doc:`GettingStarted`
Discusses how to get up and running quickly with the LLVM infrastructure.
Everything from unpacking and compilation of the distribution to execution
of some tools.
{doc}`GettingStarted`
: Discusses how to get up and running quickly with the LLVM infrastructure.
Everything from unpacking and compilation of the distribution to execution
of some tools.
:doc:`tutorial/index`
Tutorials about using LLVM. Includes a tutorial about making a custom
language with LLVM.
{doc}`tutorial/index`
: Tutorials about using LLVM. Includes a tutorial about making a custom
language with LLVM.
:doc:`ProgrammersManual`
Introduction to the general layout of the LLVM sourcebase, important classes
{doc}`ProgrammersManual`
: Introduction to the general layout of the LLVM sourcebase, important classes
and APIs, and some tips & tricks.
:doc:`DebuggingLLVM`
Provides information about how to debug LLVM.
{doc}`DebuggingLLVM`
: Provides information about how to debug LLVM.
:doc:`Frontend/PerformanceTips`
A collection of tips for frontend authors on how to generate IR
which LLVM is able to effectively optimize.
{doc}`Frontend/PerformanceTips`
: A collection of tips for frontend authors on how to generate IR
which LLVM is able to effectively optimize.
:doc:`GettingStartedVS`
An addendum to the main Getting Started guide for those using Visual Studio
on Windows.
{doc}`GettingStartedVS`
: An addendum to the main Getting Started guide for those using Visual Studio
on Windows.
:doc:`CompilerWriterInfo`
A list of helpful links for compiler writers.
{doc}`CompilerWriterInfo`
: A list of helpful links for compiler writers.
:doc:`MyFirstTypoFix`
This tutorial will guide you through the process of making a change to
LLVM, and contributing it back to the LLVM project.
{doc}`MyFirstTypoFix`
: This tutorial will guide you through the process of making a change to
LLVM, and contributing it back to the LLVM project.

497
llvm/docs/GitHub.md
View file

@ -1,51 +1,50 @@
.. _github-reviews:
(github-reviews)=
======================
LLVM GitHub User Guide
======================
# LLVM GitHub User Guide
.. contents::
:local:
```{contents}
:local:
```
Introduction
============
The LLVM Project uses `GitHub <https://github.com/>`_ for
`Source Code <https://github.com/llvm/llvm-project>`_,
`Releases <https://github.com/llvm/llvm-project/releases>`_,
`Issue Tracking <https://github.com/llvm/llvm-project/issues>`_., and
`Code Reviews <https://github.com/llvm/llvm-project/pulls>`_.
## Introduction
The LLVM Project uses [GitHub](https://github.com/) for
[Source Code](https://github.com/llvm/llvm-project),
[Releases](https://github.com/llvm/llvm-project/releases),
[Issue Tracking](https://github.com/llvm/llvm-project/issues)., and
[Code Reviews](https://github.com/llvm/llvm-project/pulls).
This page describes how the LLVM Project users and developers can
participate in the project using GitHub.
Before your first PR
====================
## Before your first PR
Please ensure that you have set a valid email address in your GitHub account,
see :ref:`github-email-address`.
see {ref}`github-email-address`.
## Pull Requests
Pull Requests
=============
The LLVM project is using GitHub Pull Requests for Code Reviews. This document
describes the typical workflow of creating a Pull Request and getting it reviewed
and accepted. This is meant as an overview of the GitHub workflow, for complete
documentation refer to `GitHub's documentation <https://docs.github.com/pull-requests>`_.
documentation refer to [GitHub's documentation](https://docs.github.com/pull-requests).
.. note::
If you are using a Pull Request for purposes other than review
(eg: precommit CI results, convenient web-based reverts, etc)
add the `skip-precommit-approval <https://github.com/llvm/llvm-project/labels?q=skip-precommit-approval>`_
label to the PR.
```{note}
If you are using a Pull Request for purposes other than review
(eg: precommit CI results, convenient web-based reverts, etc)
add the [skip-precommit-approval](https://github.com/llvm/llvm-project/labels?q=skip-precommit-approval)
label to the PR.
```
### GitHub Tools
GitHub Tools
------------
You can interact with GitHub in several ways: via git command line tools,
the web browser, `GitHub Desktop <https://desktop.github.com/>`_, or the
`GitHub CLI <https://cli.github.com>`_. This guide will cover the git command line
the web browser, [GitHub Desktop](https://desktop.github.com/), or the
[GitHub CLI](https://cli.github.com). This guide will cover the git command line
tools and the GitHub CLI.
Creating Pull Requests
----------------------
### Creating Pull Requests
Keep in mind that when creating a pull request, it should generally only contain one
self-contained commit initially.
This makes it easier for reviewers to understand the introduced changes and
@ -54,32 +53,32 @@ for the project. If you have multiple changes you want to introduce, it's
recommended to create separate pull requests for each change.
Create a local branch per commit you want to submit and then push that branch
to your `fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks>`_
to your [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks)
of the llvm-project and
`create a pull request from the fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.
[create a pull request from the fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
As GitHub uses the first line of the commit message truncated to 72 characters
as the pull request title, you may have to edit to reword or to undo this
truncation.
Creating Pull Requests with GitHub CLI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#### Creating Pull Requests with GitHub CLI
With the CLI it's enough to create the branch locally and then run:
::
gh pr create
```console
gh pr create
```
When prompted select to create and use your own fork and follow
the instructions to add more information needed.
.. note::
```{note}
When you let the GitHub CLI create a fork of llvm-project to
your user, it will change the git "remotes" so that "origin" points
to your fork and "upstream" points to the main llvm-project repository.
```
When you let the GitHub CLI create a fork of llvm-project to
your user, it will change the git "remotes" so that "origin" points
to your fork and "upstream" points to the main llvm-project repository.
### Updating Pull Requests
Updating Pull Requests
----------------------
In order to update your pull request, the only thing you need to do is to push
your new commits to the branch in your fork. That will automatically update
the pull request. You can also use the Update Branch button in GitHub's Pull
@ -88,7 +87,7 @@ Request UI, but be aware that it will create a merge commit on your branch.
When updating a pull request, you should push additional "fix up" commits to
your branch instead of force pushing. This makes it easier for GitHub to
track the context of previous review comments. Consider using the
`built-in support for fixups <https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt>`_
[built-in support for fixups](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt)
in git.
If you create fix up or merge commits, you must squash and merge before
@ -100,14 +99,14 @@ fix below.
When pushing to your branch, make sure you push to the correct fork. Check your
remotes with:
::
git remote -v
```console
git remote -v
```
And make sure you push to the remote that's pointing to your fork.
Rebasing Pull Requests and Force Pushes
---------------------------------------
### Rebasing Pull Requests and Force Pushes
In general, you should avoid rebasing a Pull Request and force pushing to the
branch that's the root of the Pull Request during the review. This action will
make the context of the old changes and comments harder to find and read. If
@ -120,37 +119,37 @@ or in some dependent code.
After your PR is reviewed and accepted, you want to rebase your branch to ensure
you won't encounter merge conflicts when landing the PR.
.. note::
This guide assumes that the PR branch only has 1 author. If you are
collaborating with others on a single branch, be careful how and when you push
changes. ``--force-with-lease`` may be useful in this situation.
```{note}
This guide assumes that the PR branch only has 1 author. If you are
collaborating with others on a single branch, be careful how and when you push
changes. `--force-with-lease` may be useful in this situation.
```
Approvals
---------
### Approvals
Before merging a PR you must have the required approvals. See
:ref:`lgtm_how_a_patch_is_accepted` for more details.
{ref}`lgtm_how_a_patch_is_accepted` for more details.
Landing your change
-------------------
### Landing your change
After your PR is approved, ensure that:
* The PR title and description describe the final changes. These will be used
as the title and message of the final squashed commit. The titles and
messages of commits in the PR will **not** be used.
* You have set a valid email address in your GitHub account, see :ref:`github-email-address`.
* You have set a valid email address in your GitHub account, see {ref}`github-email-address`.
.. note::
The LLVM Project monorepo on GitHub is configured to always use "Squash
and Merge" as the pull request merge option when using the web interface.
With this option, GitHub uses the PR summary as the default commit
message.
```{note}
The LLVM Project monorepo on GitHub is configured to always use "Squash
and Merge" as the pull request merge option when using the web interface.
With this option, GitHub uses the PR summary as the default commit
message.
Users with write access who can merge PRs have a final opportunity to edit
the commit title and message before merging. However, this option is not
available to contributors without write access.
Users with write access who can merge PRs have a final opportunity to edit
the commit title and message before merging. However, this option is not
available to contributors without write access.
```
At this point, you can merge your changes. If you do not have write permissions
for the repository, the merge button in GitHub's web interface will be
@ -170,7 +169,7 @@ commonly used first:
Afterwards you can select the option `Delete branch` to delete the branch
from your fork.
* `Interactive rebase <https://git-scm.com/docs/git-rebase#_interactive_mode>`_
* [Interactive rebase](https://git-scm.com/docs/git-rebase#_interactive_mode)
with fixups. This is the recommended method since you can control the final
commit message and check that the final commit looks as you expect. When
your local state is correct, remember to force-push to your branch and press
@ -179,9 +178,9 @@ commonly used first:
* Merge using the GitHub command line interface. Switch to your branch locally
and run:
::
gh pr merge --squash --delete-branch
```console
gh pr merge --squash --delete-branch
```
If you observe an error message from the above informing you that your pull
request is not mergeable, then that is likely because upstream has been
@ -189,26 +188,26 @@ commonly used first:
merge conflict. You must first resolve this merge conflict in order to merge
your pull request. In order to do that:
::
git fetch upstream
git rebase upstream/main
```console
git fetch upstream
git rebase upstream/main
```
Then fix the source files causing merge conflicts and make sure to rebuild and
retest the result. Then:
::
git add <files with resolved merge conflicts>
git rebase --continue
```console
git add <files with resolved merge conflicts>
git rebase --continue
```
Finally, you'll need to force push to your branch one more time before you can
merge:
::
git push --force
gh pr merge --squash --delete-branch
```console
git push --force
gh pr merge --squash --delete-branch
```
This force push may ask if you intend to push hundreds, or potentially
thousands of patches (depending on how long it's been since your pull request
@ -217,10 +216,9 @@ commonly used first:
request will understand that you're rebasing just your patches, and display
this result correctly with a note that a force push did occur.
.. _github_branches:
(github_branches)=
Branches
========
## Branches
It is possible to create branches in `llvm/llvm-project/` that start with
`users/<username>/`, however this is intended to be able to support "stacked"
@ -228,31 +226,31 @@ pull-request. Do not create any branches in the `llvm/llvm-project` repository
otherwise, please use a fork (see above). User branches that aren't
associated with a pull-request **will be deleted**.
.. _stacked_pull_requests:
(stacked_pull_requests)=
Stacked Pull Requests
=====================
## Stacked Pull Requests
To separate related changes or to break down a larger PR into smaller, reviewable
pieces, use "stacked pull requests" — this helps make the review process
smoother.
.. note::
The LLVM Project monorepo on GitHub is configured to always use "Squash and
Merge" as the pull request merge option. As a result, each PR results in
exactly one commit being merged into the project.
```{note}
The LLVM Project monorepo on GitHub is configured to always use "Squash and
Merge" as the pull request merge option. As a result, each PR results in
exactly one commit being merged into the project.
This means that stacked pull requests are the only available option for
landing a series of related changes. In contrast, submitting a PR with
multiple commits and merging them as-is (without squashing) is not supported
in LLVM.
This means that stacked pull requests are the only available option for
landing a series of related changes. In contrast, submitting a PR with
multiple commits and merging them as-is (without squashing) is not supported
in LLVM.
```
While GitHub does not natively support stacked pull requests, there are several
common alternatives.
To illustrate, assume that you are working on two branches in your fork of the
``llvm/llvm-project`` repository, and you want to eventually merge both into
``main``:
`llvm/llvm-project` repository, and you want to eventually merge both into
`main`:
- `feature_1`, which contains commit `feature_commit_1`
- `feature_2`, which contains commit `feature_commit_2` and depends on
@ -260,10 +258,10 @@ To illustrate, assume that you are working on two branches in your fork of the
Your options are as follows:
#. Use user branches in ``llvm/llvm-project``
1. Use user branches in `llvm/llvm-project`
Create user branches in the main repository, as described
:ref:`above<github_branches>`. Then:
{ref}`above <github_branches>`. Then:
- Open a pull request from `users/<username>/feature_1` → `main`
- Open another from `users/<username>/feature_2` → `users/<username>/feature_1`
@ -275,9 +273,9 @@ Your options are as follows:
perform this step using the web interface.
This approach requires commit access. See how to obtain it
`here <https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access>`_.
[here](https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access).
#. Two PRs with a dependency note
2. Two PRs with a dependency note
Create PR_1 for `feature_1` and PR_2 for `feature_2`. In PR_2, include a
note in the PR summary indicating that it depends on PR_1 (e.g.,
@ -287,44 +285,43 @@ Your options are as follows:
and which are new, e.g. "The first N commits are from the base PR". This
helps reviewers focus only on the incremental changes.
#. Use a stacked PR tool
3. Use a stacked PR tool
Use tools like SPR or Graphite (described below) to automate managing
stacked PRs. These tools are also based on using user branches
in ``llvm/llvm-project``.
in `llvm/llvm-project`.
.. note::
When not using user branches, GitHub will not display proper diffs for
subsequent PRs in a stack. Instead, it will show a combined diff that
includes all commits from earlier PRs.
```{note}
When not using user branches, GitHub will not display proper diffs for
subsequent PRs in a stack. Instead, it will show a combined diff that
includes all commits from earlier PRs.
As described above, it is the PR author’s responsibility to clearly indicate
which commits are relevant to the current PR.
For example: “The first N commits are from the base PR.”
As described above, it is the PR author’s responsibility to clearly indicate
which commits are relevant to the current PR.
For example: “The first N commits are from the base PR.”
You can avoid this issue by using user branches directly in the
``llvm/llvm-project`` repository.
You can avoid this issue by using user branches directly in the
`llvm/llvm-project` repository.
```
Using Graphite for stacked Pull Requests
----------------------------------------
### Using Graphite for stacked Pull Requests
`Graphite <https://app.graphite.dev/>`_ is a stacked pull request tool supported
by the LLVM repo (the other being `reviewable.io <https://reviewable.io>`_).
[Graphite](https://app.graphite.dev/) is a stacked pull request tool supported
by the LLVM repo (the other being [reviewable.io](https://reviewable.io)).
Graphite will want to create branches under ``llvm/llvm-project`` rather than your
Graphite will want to create branches under `llvm/llvm-project` rather than your
private fork, so the guidance above, about branch naming, is critical, otherwise
``gt submit`` (i.e. publish your PRs for review) will fail.
`gt submit` (i.e. publish your PRs for review) will fail.
Use ``gt config`` then ``Branch naming settings`` and ``Set a prefix for branch names``.
Include the last ``/``.
Use `gt config` then `Branch naming settings` and `Set a prefix for branch names`.
Include the last `/`.
If you didn't do the above and Graphite created non-prefixed branches, a simple way to
unblock is to rename (``git -m <old name> <new name>``), and then checkout the branch
and ``gt track``.
unblock is to rename (`git -m <old name> <new name>`), and then checkout the branch
and `gt track`.
Pre-merge Continuous Integration (CI)
-------------------------------------
### Pre-merge Continuous Integration (CI)
Multiple checks will be applied on a pull-request, either for linting/formatting
or some build and tests. None of these are perfect and you will encounter
@ -342,112 +339,110 @@ project.
However, please make sure you do not force-merge any changes that have clear
test failures directly linked to your changes. Our policy is still to keep the
``main`` branch in a good condition, and introducing failures to be fixed later
`main` branch in a good condition, and introducing failures to be fixed later
violates that policy.
Problems After Landing Your Change
==================================
## Problems After Landing Your Change
Even though your PR passed the pre-commit checks and is approved by reviewers, it
may cause problems for some configurations after it lands. You will be notified
if this happens and the community is ready to help you fix the problems.
This process is described in detail
:ref:`here <MyFirstTypoFix Issues After Landing Your PR>`.
{ref}`here <MyFirstTypoFix Issues After Landing Your PR>`.
Checking out another PR locally
-------------------------------
### Checking out another PR locally
Sometimes you want to review another person's PR on your local machine to run
tests or inspect code in your preferred editor. This is easily done with the
CLI:
::
gh pr checkout <PR Number>
```console
gh pr checkout <PR Number>
```
This is also possible with the web interface and the normal git command line
tools, but the process is a bit more complicated. See GitHub's
`documentation <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally?platform=linux&tool=webui#modifying-an-inactive-pull-request-locally>`_
[documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally?platform=linux&tool=webui#modifying-an-inactive-pull-request-locally)
on the topic.
Example Pull Request with GitHub CLI
====================================
## Example Pull Request with GitHub CLI
Here is an example for creating a Pull Request with the GitHub CLI:
::
```console
# Clone the repo
gh repo clone llvm/llvm-project
# Clone the repo
gh repo clone llvm/llvm-project
# Switch to the repo and create a new branch
cd llvm-project
git switch -c my_change
# Switch to the repo and create a new branch
cd llvm-project
git switch -c my_change
# Create your changes
$EDITOR file.cpp
# Create your changes
$EDITOR file.cpp
# Don't forget clang-format
git clang-format
# Don't forget clang-format
git clang-format
# and don't forget running your tests
ninja check-llvm
# and don't forget running your tests
ninja check-llvm
# Commit, use a good commit message
git commit file.cpp
# Commit, use a good commit message
git commit file.cpp
# Create the PR, select to use your own fork when prompted.
# If you don't have a fork, gh will create one for you.
gh pr create
# Create the PR, select to use your own fork when prompted.
# If you don't have a fork, gh will create one for you.
gh pr create
# If you get any review comments, come back to the branch and
# adjust them.
git switch my_change
$EDITOR file.cpp
# If you get any review comments, come back to the branch and
# adjust them.
git switch my_change
$EDITOR file.cpp
# Commit your changes
git commit file.cpp -m "Code Review adjustments"
# Commit your changes
git commit file.cpp -m "Code Review adjustments"
# Format changes
git clang-format HEAD~
# Format changes
git clang-format HEAD~
# Recommit if any formatting changes
git commit -a --amend
# Recommit if any formatting changes
git commit -a --amend
# Push your changes to your fork branch, be mindful of
# your remotes here, if you don't remember what points to your
# fork, use git remote -v to see. Usually origin points to your
# fork and upstream to llvm/llvm-project
git push origin my_change
# Push your changes to your fork branch, be mindful of
# your remotes here, if you don't remember what points to your
# fork, use git remote -v to see. Usually origin points to your
# fork and upstream to llvm/llvm-project
git push origin my_change
```
Before merging the PR, it is recommended that you rebase locally and re-run test
checks:
::
```console
# Add upstream as a remote (if you don't have it already)
git remote add upstream https://github.com/llvm/llvm-project.git
# Add upstream as a remote (if you don't have it already)
git remote add upstream https://github.com/llvm/llvm-project.git
# Make sure you have all the latest changes
git fetch upstream && git rebase -i upstream/main
# Make sure you have all the latest changes
git fetch upstream && git rebase -i upstream/main
# Make sure tests pass with latest changes and your change
ninja check
# Make sure tests pass with latest changes and your change
ninja check
# Push the rebased changes to your fork.
git push origin my_change --force
# Push the rebased changes to your fork.
git push origin my_change --force
# Now merge it
gh pr merge --squash --delete-branch
# Now merge it
gh pr merge --squash --delete-branch
```
See more in-depth information about how to contribute in the following documentation:
* :doc:`Contributing`
* :doc:`MyFirstTypoFix`
* {doc}`Contributing`
* {doc}`MyFirstTypoFix`
Example Pull Request with git
====================================
## Example Pull Request with git
Instead of using the GitHub CLI to create a PR, you can push your code to a
remote branch on your fork and create the PR to upstream using the GitHub web
@ -455,98 +450,97 @@ interface.
Here is an example of making a PR using git and the GitHub web interface:
First follow the instructions to `fork the repository <https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#forking-a-repository>`_.
First follow the instructions to [fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#forking-a-repository).
Next follow the instructions to `clone your forked repository <https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#cloning-your-forked-repository>`_.
Next follow the instructions to [clone your forked repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#cloning-your-forked-repository).
Once you've cloned your forked repository,
::
```console
# Switch to the forked repo
cd llvm-project
# Switch to the forked repo
cd llvm-project
# Create a new branch
git switch -c my_change
# Create a new branch
git switch -c my_change
# Create your changes
$EDITOR file.cpp
# Create your changes
$EDITOR file.cpp
# Don't forget clang-format
git clang-format
# Don't forget clang-format
git clang-format
# and don't forget running your tests
ninja check-llvm
# and don't forget running your tests
ninja check-llvm
# Commit, use a good commit message
git commit file.cpp
# Commit, use a good commit message
git commit file.cpp
# Push your changes to your fork branch, be mindful of
# your remotes here, if you don't remember what points to your
# fork, use git remote -v to see. Usually origin points to your
# fork and upstream to llvm/llvm-project
git push origin my_change
# Push your changes to your fork branch, be mindful of
# your remotes here, if you don't remember what points to your
# fork, use git remote -v to see. Usually origin points to your
# fork and upstream to llvm/llvm-project
git push origin my_change
```
Navigate to the URL printed to the console from the git push command in the last step.
Create a pull request from your branch to llvm::main.
::
```console
# If you get any review comments, come back to the branch and
# adjust them.
git switch my_change
$EDITOR file.cpp
# If you get any review comments, come back to the branch and
# adjust them.
git switch my_change
$EDITOR file.cpp
# Commit your changes
git commit file.cpp -m "Code Review adjustments"
# Commit your changes
git commit file.cpp -m "Code Review adjustments"
# Format changes
git clang-format HEAD~
# Format changes
git clang-format HEAD~
# Recommit if any formatting changes
git commit -a --amend
# Recommit if any formatting changes
git commit -a --amend
# Re-run tests and make sure nothing broke.
ninja check
# Re-run tests and make sure nothing broke.
ninja check
# Push your changes to your fork branch, be mindful of
# your remotes here, if you don't remember what points to your
# fork, use git remote -v to see. Usually origin points to your
# fork and upstream to llvm/llvm-project
git push origin my_change
# Push your changes to your fork branch, be mindful of
# your remotes here, if you don't remember what points to your
# fork, use git remote -v to see. Usually origin points to your
# fork and upstream to llvm/llvm-project
git push origin my_change
```
Before merging the PR, it is recommended that you rebase locally and re-run test
checks:
::
```console
# Add upstream as a remote (if you don't have it already)
git remote add upstream https://github.com/llvm/llvm-project.git
# Add upstream as a remote (if you don't have it already)
git remote add upstream https://github.com/llvm/llvm-project.git
# Make sure you have all the latest changes
git fetch upstream && git rebase -i upstream/main
# Make sure you have all the latest changes
git fetch upstream && git rebase -i upstream/main
# Make sure tests pass with latest changes and your change
ninja check
# Make sure tests pass with latest changes and your change
ninja check
# Push the rebased changes to your fork.
git push origin my_change --force
# Push the rebased changes to your fork.
git push origin my_change --force
```
Once your PR is approved, rebased, and tests are passing, click `Squash and
Merge` on your PR in the GitHub web interface.
See more in-depth information about how to contribute in the following documentation:
* :doc:`Contributing`
* :doc:`MyFirstTypoFix`
* {doc}`Contributing`
* {doc}`MyFirstTypoFix`
Releases
========
## Releases
.. _backporting:
(backporting)=
### Backporting Fixes to the Release Branches
Backporting Fixes to the Release Branches
-----------------------------------------
You can use special comments on issues or pull requests to make backport
requests for the release branches. To do this, after your pull request has been
merged:
@ -556,9 +550,9 @@ merged:
2. Add a comment to it in the following format:
::
/cherry-pick <commit> <commit> <...>
```console
/cherry-pick <commit> <commit> <...>
```
This command takes one or more git commit hashes as arguments and will attempt
to cherry-pick the commit(s) to the release branch. If the commit(s) fail to
@ -570,14 +564,13 @@ If a commit you want to backport does not apply cleanly, you may resolve
the conflicts locally and then create a pull request against the release
branch. Just make sure to add the release milestone to the pull request.
Getting admin access to CI infrastructure
=========================================
## Getting admin access to CI infrastructure
Any individual who is responsible for setting up and/or maintaining CI
infrastructure for a LLVM project can request to be granted the CI/CD role by
the LLVM infrastructure area team. The request can be made by creating `a
Github issue <https://github.com/llvm/llvm-project/issues/new>`_ and using the
``infrastructure`` label. Applicants must include a justification for why the
the LLVM infrastructure area team. The request can be made by creating [a
Github issue](https://github.com/llvm/llvm-project/issues/new) and using the
`infrastructure` label. Applicants must include a justification for why the
role is being requested. Applications are reviewed on a case-by-case basis by
the LLVM infrastructure area team and the role can be revoked at any point as
the area team sees fit.

705
llvm/docs/Passes.md
View file

File diff suppressed because it is too large Load diff

4303
llvm/docs/ProgrammersManual.md
View file

File diff suppressed because it is too large Load diff

70
llvm/docs/RFCProcess.md
View file

@ -1,22 +1,20 @@
=================================
Request For Comment (RFC) process
=================================
# Request For Comment (RFC) process
.. contents::
:local:
:depth: 1
```{contents}
:local:
:depth: 1
```
## Introduction
Introduction
============
Substantive changes to LLVM projects need to be acceptable to the wider
community, which requires gaining community consensus to adopt the changes.
This is done by posting an RFC and obtaining feedback about the proposal.
Process
=======
## Process
### Writing an RFC
Writing an RFC
--------------
The process begins with writing a proposal for the changes you'd like to see
made. The proposal should include:
@ -26,10 +24,10 @@ made. The proposal should include:
* any open questions the community should address.
The proposal should be posted to the appropriate forum on
`Discourse <https://discourse.llvm.org/>`_.
[Discourse](https://discourse.llvm.org/).
### Feedback Period
Feedback Period
---------------
Once the RFC is posted, the community will provide feedback on the proposal.
The feedback period is a collaborative effort between the community and the
proposal authors. Authors should take the community's feedback into
@ -45,14 +43,13 @@ discussion is actively continuing on the proposal.
After posting a major proposal, it is common to receive lots of conflicting
feedback from different parties, or no feedback at all, leaving authors without
clear next steps. As a community, we are aiming for `"rough consensus"
<https://en.wikipedia.org/wiki/Rough_consensus>`_, similar in spirit to what is
described in `IETF RFC7282 <https://datatracker.ietf.org/doc/html/rfc7282>`_.
clear next steps. As a community, we are aiming for ["rough consensus"][rc],
similar in spirit to what is
described in [IETF RFC7282][rfc7282].
This requires considering and addressing all of the objections to the RFC, and
confirming that we can all live with the tradeoffs embodied in the proposal.
The LLVM Area Teams (defined in `LP0004
<https://github.com/llvm/llvm-www/blob/main/proposals/LP0004-project-governance.md>`_)
The LLVM Area Teams (defined in [LP0004][lp0004])
are responsible for facilitating project decision making. In cases where there
isn't obvious agreement, area teams should step in to restate their perceived
consensus. In cases of deeper disagreement, area teams should try to identify
@ -60,20 +57,23 @@ the next steps for the proposal, such as gathering more data, changing the
proposal, or rejecting it in the absence of major changes in the design or
context. They can also act as moderators by scheduling calls for participants
to speak directly to resolve disagreements, subject to normal
:ref:`Code of Conduct <LLVM Community Code of Conduct>` guidelines.
{ref}`Code of Conduct <LLVM Community Code of Conduct>` guidelines.
Once the design of the new feature is finalized, the work itself should be done
as a series of :ref:`incremental changes <incremental-changes>`, not as a long-term development branch.
as a series of {ref}`incremental changes <incremental-changes>`, not as a long-term development branch.
[rc]: https://en.wikipedia.org/wiki/Rough_consensus
[rfc7282]: https://datatracker.ietf.org/doc/html/rfc7282
[lp0004]: https://github.com/llvm/llvm-www/blob/main/proposals/LP0004-project-governance.md
### Trivial Acceptance or Rejection
Trivial Acceptance or Rejection
-------------------------------
Some proposals have obvious consensus (for or against) after discussion in the
community. It is acceptable to presume a post which appears to have obvious
consensus has been accepted.
Non-trivial Acceptance or Rejection
-----------------------------------
### Non-trivial Acceptance or Rejection
If the proposal does not have obvious consensus after community discussion,
a maintainer for each of the impacted parts of the project should explicitly
accept or reject the RFC by leaving a comment stating their decision and
@ -81,16 +81,16 @@ possibly detailing any provisions for their acceptance. Overall consensus is
determined once a maintainer from each impacted part of the project has
accepted the proposal.
Low Engagement Level
~~~~~~~~~~~~~~~~~~~~
#### Low Engagement Level
If the proposal gets little or no engagement by the community, it is a sign that
the proposal does not have consensus and is rejected. Engagement means comments
on the proposal. If there are few or no comments but the are a lot of people
pressing the like/heart button on the post, the appropriate area team can make
a value judgement on whether to accept or reject.
After Acceptance
----------------
### After Acceptance
Once an RFC has been accepted, the authors may begin merging pull requests
related to the proposal. While the RFC process typically makes reviewing the
pull requests go more smoothly, the review process may identify additional
@ -98,16 +98,16 @@ necessary changes to the proposal. Minor changes to the proposal do not require
an additional RFC. However, if the proposal changes significantly in a material
way, the authors may be asked to run another RFC.
After Rejection
---------------
### After Rejection
Any rejected RFC can be brought back to the community as a new RFC in the
future. The new RFC should either clearly identify new information that may
change the community's perception of the proposal and/or explicitly address the
concerns previously raised by the community. It is helpful to explicitly call
out such information in the subsequent RFC.
Suggestions on Getting a Change Accepted
----------------------------------------
### Suggestions on Getting a Change Accepted
These are some suggestions for how to get a major change accepted:
* Make it targeted, and avoid touching components irrelevant to the task.
@ -122,4 +122,4 @@ These are some suggestions for how to get a major change accepted:
* Compilers are foundational infrastructure, so there is a high quality bar,
and the burden of proof is on the proposer. If reviewers repeatedly ask for
an unreasonable amount of evidence or data, proposal authors can escalate to
the area team to resolve disagreements.
the area team to resolve disagreements.

435
llvm/docs/Reference.md
View file

@ -1,258 +1,243 @@
Reference
=========
# Reference
LLVM and API reference documentation.
.. contents::
:local:
```{contents}
:local:
```
.. toctree::
:hidden:
```{toctree}
:hidden:
HowToUseAttributes
CommandGuide/index
CommandGuide/llvm-reduce
OptBisect
SymbolizerMarkupFormat
PDB/index
GarbageCollection
Statepoints
LibFuzzer
FuzzingLLVM
LangRef
UndefinedBehavior
InAlloca
BitCodeFormat
MIRLangRef
GlobalISel/index
ConvergentOperations
TestingGuide
TestSuiteGuide
GwpAsan
XRay
XRayExample
FaultMaps
Atomics
ExceptionHandling
Extensions
HowToSetUpLLVMStyleRTTI
BlockFrequencyTerminology
BranchWeightMetadata
GetElementPtr
ScudoHardenedAllocator
MemoryModelRelaxationAnnotations
MemTagSanitizer
DependenceGraphs/index
SpeculativeLoadHardening
SegmentedStacks
MarkedUpDisassembly
StackMaps
Coroutines
PointerAuth
YamlIO
ConvergenceAndUniformity
MLGO
ContentAddressableStorage
CIBestPractices
AIToolPolicy
CalleeTypeMetadata
CallGraphSection
InterfaceExportAnnotations
PCSectionsMetadata
QualGroup
Security
SecurityTransparencyReports
SystemLibrary
TransformMetadata
TypeMetadata
XRayFDRFormat
API Reference
-------------
`Doxygen generated documentation <https://llvm.org/doxygen/>`_
(`classes <https://llvm.org/doxygen/inherits.html>`_)
:doc:`HowToUseAttributes`
Answers some questions about the new Attributes infrastructure.
LLVM Reference
--------------
======================
Command Line Utilities
======================
:doc:`LLVM Command Guide <CommandGuide/index>`
A reference manual for the LLVM command line utilities ("man" pages for LLVM
tools).
:doc:`llvm-reduce <CommandGuide/llvm-reduce>`
Automatic bug finder and test-case reducer description and usage
information.
:doc:`OptBisect`
A command line option for debugging optimization-induced failures.
:doc:`SymbolizerMarkupFormat`
A reference for the log symbolizer markup accepted by ``llvm-symbolizer``.
:doc:`The Microsoft PDB File Format <PDB/index>`
A detailed description of the Microsoft PDB (Program Database) file format.
==================
Garbage Collection
==================
:doc:`GarbageCollection`
The interfaces source-language compilers should use for compiling GC'd
programs.
:doc:`Statepoints`
This describes a set of experimental extensions for garbage
collection support.
=========
HowToUseAttributes
CommandGuide/index
CommandGuide/llvm-reduce
OptBisect
SymbolizerMarkupFormat
PDB/index
GarbageCollection
Statepoints
LibFuzzer
=========
:doc:`LibFuzzer`
A library for writing in-process guided fuzzers.
:doc:`FuzzingLLVM`
Information on writing and using Fuzzers to find bugs in LLVM.
========
LLVM IR
========
:doc:`LLVM Language Reference Manual <LangRef>`
Defines the LLVM intermediate representation and the assembly form of the
different nodes.
:doc:`Undefined Behavior (UB) <UndefinedBehavior>`
A guide on what UB/undef/poison are and when to use each one.
:doc:`InAlloca`
Description of the ``inalloca`` argument attribute.
:doc:`BitCodeFormat`
This describes the file format and encoding used for LLVM "bc" files.
:doc:`Machine IR (MIR) Format Reference Manual <MIRLangRef>`
A reference manual for the MIR serialization format, which is used to test
LLVM's code generation passes.
:doc:`GlobalISel/index`
This describes the prototype instruction selection replacement, GlobalISel.
:doc:`ConvergentOperations`
Description of ``convergent`` operation semantics and related intrinsics.
=====================
Testing and Debugging
=====================
:doc:`LLVM Testing Infrastructure Guide <TestingGuide>`
A reference manual for using the LLVM testing infrastructure.
:doc:`TestSuiteGuide`
Describes how to compile and run the test-suite benchmarks.
:doc:`GwpAsan`
A sampled heap memory error detection toolkit designed for production use.
====
FuzzingLLVM
LangRef
UndefinedBehavior
InAlloca
BitCodeFormat
MIRLangRef
GlobalISel/index
ConvergentOperations
TestingGuide
TestSuiteGuide
GwpAsan
XRay
====
XRayExample
FaultMaps
Atomics
ExceptionHandling
Extensions
HowToSetUpLLVMStyleRTTI
BlockFrequencyTerminology
BranchWeightMetadata
GetElementPtr
ScudoHardenedAllocator
MemoryModelRelaxationAnnotations
MemTagSanitizer
DependenceGraphs/index
SpeculativeLoadHardening
SegmentedStacks
MarkedUpDisassembly
StackMaps
Coroutines
PointerAuth
YamlIO
ConvergenceAndUniformity
MLGO
ContentAddressableStorage
CIBestPractices
AIToolPolicy
CalleeTypeMetadata
CallGraphSection
InterfaceExportAnnotations
PCSectionsMetadata
QualGroup
Security
SecurityTransparencyReports
SystemLibrary
TransformMetadata
TypeMetadata
XRayFDRFormat
```
:doc:`XRay`
High-level documentation of how to use XRay in LLVM.
## API Reference
:doc:`XRayExample`
An example of how to debug an application with XRay.
[Doxygen generated documentation](https://llvm.org/doxygen/)
: ([classes](https://llvm.org/doxygen/inherits.html))
=================
Additional Topics
=================
{doc}`HowToUseAttributes`
: Answers some questions about the new Attributes infrastructure.
:doc:`FaultMaps`
LLVM support for folding control flow into faulting machine instructions.
## LLVM Reference
:doc:`Atomics`
Information about LLVM's concurrency model.
### Command Line Utilities
:doc:`ExceptionHandling`
This document describes the design and implementation of exception handling
in LLVM.
{doc}`LLVM Command Guide <CommandGuide/index>`
: A reference manual for the LLVM command line utilities ("man" pages for LLVM
tools).
:doc:`Extensions`
LLVM-specific extensions to tools and formats LLVM seeks compatibility with.
{doc}`llvm-reduce <CommandGuide/llvm-reduce>`
: Automatic bug finder and test-case reducer description and usage
information.
:doc:`HowToSetUpLLVMStyleRTTI`
How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your
class hierarchy.
{doc}`OptBisect`
: A command line option for debugging optimization-induced failures.
:doc:`BlockFrequencyTerminology`
Provides information about terminology used in the ``BlockFrequencyInfo``
analysis pass.
{doc}`SymbolizerMarkupFormat`
: A reference for the log symbolizer markup accepted by `llvm-symbolizer`.
:doc:`BranchWeightMetadata`
Provides information about Branch Prediction Information.
{doc}`The Microsoft PDB File Format <PDB/index>`
: A detailed description of the Microsoft PDB (Program Database) file format.
:doc:`GetElementPtr`
Answers to some very frequent questions about LLVM's most frequently
misunderstood instruction.
### Garbage Collection
:doc:`ScudoHardenedAllocator`
A library that implements a security-hardened `malloc()`.
{doc}`GarbageCollection`
: The interfaces source-language compilers should use for compiling GC'd
programs.
:doc:`MemoryModelRelaxationAnnotations`
Target-defined relaxation to LLVM's concurrency model.
{doc}`Statepoints`
: This describes a set of experimental extensions for garbage
collection support.
:doc:`MemTagSanitizer`
Security hardening for production code aiming to mitigate memory
related vulnerabilities. Based on the Armv8.5-A Memory Tagging Extension.
### LibFuzzer
:doc:`Dependence Graphs <DependenceGraphs/index>`
A description of the design of the various dependence graphs such as
the DDG (Data Dependence Graph).
{doc}`LibFuzzer`
: A library for writing in-process guided fuzzers.
:doc:`SpeculativeLoadHardening`
A description of the Speculative Load Hardening mitigation for Spectre v1.
{doc}`FuzzingLLVM`
: Information on writing and using Fuzzers to find bugs in LLVM.
:doc:`SegmentedStacks`
This document describes segmented stacks and how they are used in LLVM.
### LLVM IR
:doc:`MarkedUpDisassembly`
This document describes the optional rich disassembly output syntax.
{doc}`LLVM Language Reference Manual <LangRef>`
: Defines the LLVM intermediate representation and the assembly form of the
different nodes.
:doc:`StackMaps`
LLVM support for mapping instruction addresses to the location of
values and allowing code to be patched.
{doc}`Undefined Behavior (UB) <UndefinedBehavior>`
: A guide on what UB/undef/poison are and when to use each one.
:doc:`Coroutines`
LLVM support for coroutines.
{doc}`InAlloca`
: Description of the `inalloca` argument attribute.
:doc:`PointerAuth`
A description of pointer authentication, its LLVM IR representation, and its
support in the backend.
{doc}`BitCodeFormat`
: This describes the file format and encoding used for LLVM "bc" files.
:doc:`YamlIO`
A reference guide for using LLVM's YAML I/O library.
{doc}`Machine IR (MIR) Format Reference Manual <MIRLangRef>`
: A reference manual for the MIR serialization format, which is used to test
LLVM's code generation passes.
:doc:`ConvergenceAndUniformity`
A description of uniformity analysis in the presence of irreducible
control flow, and its implementation.
{doc}`GlobalISel/index`
: This describes the prototype instruction selection replacement, GlobalISel.
:doc:`MLGO`
Facilities for ML-Guided Optimization, such as collecting IR corpora from a
build, interfacing with ML models, an exposing features for training.
{doc}`ConvergentOperations`
: Description of `convergent` operation semantics and related intrinsics.
:doc:`ContentAddressableStorage`
A reference guide for using LLVM's CAS library.
### Testing and Debugging
:doc:`CIBestPractices`
A list of guidelines and best practices to use when working on LLVM's
CI systems.
{doc}`LLVM Testing Infrastructure Guide <TestingGuide>`
: A reference manual for using the LLVM testing infrastructure.
{doc}`TestSuiteGuide`
: Describes how to compile and run the test-suite benchmarks.
{doc}`GwpAsan`
: A sampled heap memory error detection toolkit designed for production use.
### XRay
{doc}`XRay`
: High-level documentation of how to use XRay in LLVM.
{doc}`XRayExample`
: An example of how to debug an application with XRay.
### Additional Topics
{doc}`FaultMaps`
: LLVM support for folding control flow into faulting machine instructions.
{doc}`Atomics`
: Information about LLVM's concurrency model.
{doc}`ExceptionHandling`
: This document describes the design and implementation of exception handling
in LLVM.
{doc}`Extensions`
: LLVM-specific extensions to tools and formats LLVM seeks compatibility with.
{doc}`HowToSetUpLLVMStyleRTTI`
: How to make `isa<>`, `dyn_cast<>`, etc. available for clients of your
class hierarchy.
{doc}`BlockFrequencyTerminology`
: Provides information about terminology used in the `BlockFrequencyInfo`
analysis pass.
{doc}`BranchWeightMetadata`
: Provides information about Branch Prediction Information.
{doc}`GetElementPtr`
: Answers to some very frequent questions about LLVM's most frequently
misunderstood instruction.
{doc}`ScudoHardenedAllocator`
: A library that implements a security-hardened `malloc()`.
{doc}`MemoryModelRelaxationAnnotations`
: Target-defined relaxation to LLVM's concurrency model.
{doc}`MemTagSanitizer`
: Security hardening for production code aiming to mitigate memory
related vulnerabilities. Based on the Armv8.5-A Memory Tagging Extension.
{doc}`Dependence Graphs <DependenceGraphs/index>`
: A description of the design of the various dependence graphs such as
the DDG (Data Dependence Graph).
{doc}`SpeculativeLoadHardening`
: A description of the Speculative Load Hardening mitigation for Spectre v1.
{doc}`SegmentedStacks`
: This document describes segmented stacks and how they are used in LLVM.
{doc}`MarkedUpDisassembly`
: This document describes the optional rich disassembly output syntax.
{doc}`StackMaps`
: LLVM support for mapping instruction addresses to the location of
values and allowing code to be patched.
{doc}`Coroutines`
: LLVM support for coroutines.
{doc}`PointerAuth`
: A description of pointer authentication, its LLVM IR representation, and its
support in the backend.
{doc}`YamlIO`
: A reference guide for using LLVM's YAML I/O library.
{doc}`ConvergenceAndUniformity`
: A description of uniformity analysis in the presence of irreducible
control flow, and its implementation.
{doc}`MLGO`
: Facilities for ML-Guided Optimization, such as collecting IR corpora from a
build, interfacing with ML models, an exposing features for training.
{doc}`ContentAddressableStorage`
: A reference guide for using LLVM's CAS library.
{doc}`CIBestPractices`
: A list of guidelines and best practices to use when working on LLVM's
CI systems.

2763
llvm/docs/SourceLevelDebugging.md
View file

File diff suppressed because it is too large Load diff

331
llvm/docs/TableGen/index.md
View file

@ -1,19 +1,18 @@
=================
TableGen Overview
=================
# TableGen Overview
.. contents::
:local:
```{contents}
:local:
```
.. toctree::
:hidden:
```{toctree}
:hidden:
BackEnds
BackGuide
ProgRef
BackEnds
BackGuide
ProgRef
```
Introduction
============
## Introduction
TableGen's purpose is to help a human develop and maintain records of
domain-specific information. Because there may be a large number of these
@ -23,141 +22,140 @@ amount of duplication in the description, reduces the chance of error, and makes
it easier to structure domain-specific information.
The TableGen front end parses a file, instantiates the declarations, and
hands the result off to a domain-specific `backend`_ for processing. See
the :doc:`TableGen Programmer's Reference <./ProgRef>` for an in-depth
description of TableGen. See :doc:`tblgen - Description to C++ Code
<../CommandGuide/tblgen>` for details on the ``*-tblgen`` commands
that run the various flavors of TableGen.
hands the result off to a domain-specific {ref}`backend <backend>` for processing. See
the {doc}`TableGen Programmer's Reference <./ProgRef>` for an in-depth
description of TableGen. See
{doc}`tblgen - Description to C++ Code <../CommandGuide/tblgen>` for details on the
`*-tblgen` commands that run the various flavors of TableGen.
The current major users of TableGen are :doc:`The LLVM Target-Independent
Code Generator <../CodeGenerator>` and the `Clang diagnostics and attributes
<https://clang.llvm.org/docs/UsersManual.html#controlling-errors-and-warnings>`_.
The current major users of TableGen are
{doc}`The LLVM Target-Independent Code Generator <../CodeGenerator>` and the
[Clang diagnostics and attributes][clang-diagnostics-and-attributes].
[clang-diagnostics-and-attributes]: https://clang.llvm.org/docs/UsersManual.html#controlling-errors-and-warnings
Note that if you work with TableGen frequently and use emacs or vim,
you can find an emacs "TableGen mode" and a vim language file in the
``llvm/utils/emacs`` and ``llvm/utils/vim`` directories of your LLVM
`llvm/utils/emacs` and `llvm/utils/vim` directories of your LLVM
distribution, respectively.
.. _intro:
(intro)=
The TableGen program
====================
## The TableGen program
TableGen files are interpreted by the TableGen program: ``llvm-tblgen`` available
in your build directory under ``bin``. It is not installed in the system (or where
TableGen files are interpreted by the TableGen program: `llvm-tblgen` available
in your build directory under `bin`. It is not installed in the system (or where
your sysroot is set to), since it has no use beyond LLVM's build process.
Running TableGen
----------------
### Running TableGen
TableGen runs just like any other LLVM tool. The first (optional) argument
specifies the file to read. If a filename is not specified, ``llvm-tblgen``
specifies the file to read. If a filename is not specified, `llvm-tblgen`
reads from standard input.
The ``-o`` option specifies the output file or ``-`` to output to
The `-o` option specifies the output file or `-` to output to
stdout. Where TableGen produces multiple output files, the option
specifies the name of the main output file, which also works as the
name prefix for other output files.
To be useful, one of the `backends`_ must be used. These backends are
selectable on the command line (type '``llvm-tblgen -help``' for a list). For
To be useful, one of the {ref}`backends <backends>` must be used. These backends are
selectable on the command line (type '`llvm-tblgen -help`' for a list). For
example, to get a list of all of the definitions that subclass a particular type
(which can be useful for building up an enum list of these records), use the
``-print-enums`` option:
`-print-enums` option:
.. code-block:: bash
```console
$ llvm-tblgen X86.td -print-enums -class=Register
AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
XMM6, XMM7, XMM8, XMM9,
$ llvm-tblgen X86.td -print-enums -class=Register
AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
XMM6, XMM7, XMM8, XMM9,
$ llvm-tblgen X86.td -print-enums -class=Instruction
ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
$ llvm-tblgen X86.td -print-enums -class=Instruction
ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
```
The default backend prints out all of the records. There is also a general
backend which outputs all the records as a JSON data structure, enabled using
the `-dump-json` option.
If you plan to use TableGen, you will most likely have to write a `backend`_
If you plan to use TableGen, you will most likely have to write a {ref}`backend <backend>`
that extracts the information specific to what you need and formats it in the
appropriate way. You can do this by extending TableGen itself in C++ or by
writing a script in any language that can consume the JSON output.
Example
-------
### Example
With no other arguments, `llvm-tblgen` parses the specified file and prints out all
of the classes, then all of the definitions. This is a good way to see what the
various definitions expand to fully. Running this on the ``X86.td`` file prints
various definitions expand to fully. Running this on the `X86.td` file prints
this (at the time of this writing):
.. code-block:: text
```text
...
def ADD32rr { // Instruction X86Inst I
string Namespace = "X86";
dag OutOperandList = (outs GR32:$dst);
dag InOperandList = (ins GR32:$src1, GR32:$src2);
string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
list<Register> Uses = [];
list<Register> Defs = [EFLAGS];
list<Predicate> Predicates = [];
int CodeSize = 3;
int AddedComplexity = 0;
bit isReturn = 0;
bit isBranch = 0;
bit isIndirectBranch = 0;
bit isBarrier = 0;
bit isCall = 0;
bit canFoldAsLoad = 0;
bit mayLoad = 0;
bit mayStore = 0;
bit isImplicitDef = 0;
bit isConvertibleToThreeAddress = 1;
bit isCommutable = 1;
bit isTerminator = 0;
bit isReMaterializable = 0;
bit isPredicable = 0;
bit hasDelaySlot = 0;
bit usesCustomInserter = 0;
bit hasCtrlDep = 0;
bit isNotDuplicable = 0;
bit hasSideEffects = 0;
InstrItinClass Itinerary = NoItinerary;
string Constraints = "";
string DisableEncoding = "";
bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
Format Form = MRMDestReg;
bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
ImmType ImmT = NoImm;
bits<3> ImmTypeBits = { 0, 0, 0 };
bit hasOpSizePrefix = 0;
bit hasAdSizePrefix = 0;
bits<4> Prefix = { 0, 0, 0, 0 };
bit hasREX_WPrefix = 0;
FPFormat FPForm = ?;
bits<3> FPFormBits = { 0, 0, 0 };
}
...
```
...
def ADD32rr { // Instruction X86Inst I
string Namespace = "X86";
dag OutOperandList = (outs GR32:$dst);
dag InOperandList = (ins GR32:$src1, GR32:$src2);
string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
list<Register> Uses = [];
list<Register> Defs = [EFLAGS];
list<Predicate> Predicates = [];
int CodeSize = 3;
int AddedComplexity = 0;
bit isReturn = 0;
bit isBranch = 0;
bit isIndirectBranch = 0;
bit isBarrier = 0;
bit isCall = 0;
bit canFoldAsLoad = 0;
bit mayLoad = 0;
bit mayStore = 0;
bit isImplicitDef = 0;
bit isConvertibleToThreeAddress = 1;
bit isCommutable = 1;
bit isTerminator = 0;
bit isReMaterializable = 0;
bit isPredicable = 0;
bit hasDelaySlot = 0;
bit usesCustomInserter = 0;
bit hasCtrlDep = 0;
bit isNotDuplicable = 0;
bit hasSideEffects = 0;
InstrItinClass Itinerary = NoItinerary;
string Constraints = "";
string DisableEncoding = "";
bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
Format Form = MRMDestReg;
bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
ImmType ImmT = NoImm;
bits<3> ImmTypeBits = { 0, 0, 0 };
bit hasOpSizePrefix = 0;
bit hasAdSizePrefix = 0;
bits<4> Prefix = { 0, 0, 0, 0 };
bit hasREX_WPrefix = 0;
FPFormat FPForm = ?;
bits<3> FPFormBits = { 0, 0, 0 };
}
...
This definition corresponds to the 32-bit register-register ``add`` instruction
of the x86 architecture. ``def ADD32rr`` defines a record named
``ADD32rr``, and the comment at the end of the line indicates the superclasses
This definition corresponds to the 32-bit register-register `add` instruction
of the x86 architecture. `def ADD32rr` defines a record named
`ADD32rr`, and the comment at the end of the line indicates the superclasses
of the definition. The body of the record contains all of the data that
TableGen assembled for the record, indicating that the instruction is part of
the ``X86`` namespace, the pattern indicating how the instruction is selected by
the `X86` namespace, the pattern indicating how the instruction is selected by
the code generator, that it is a two-address instruction, has a particular
encoding, etc. The contents and semantics of the information in the record are
specific to the needs of the X86 backend, and are only shown as an example.
@ -167,31 +165,29 @@ by the code generator, and specifying it all manually would be unmaintainable,
prone to bugs, and tiring to do in the first place. Because we are using
TableGen, all of the information was derived from the following definition:
.. code-block:: text
```text
let Defs = [EFLAGS],
isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
isConvertibleToThreeAddress = 1 in // Can transform into LEA.
def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
(ins GR32:$src1, GR32:$src2),
"add{l}\t{$src2, $dst|$dst, $src2}",
[(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
```
let Defs = [EFLAGS],
isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
isConvertibleToThreeAddress = 1 in // Can transform into LEA.
def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
(ins GR32:$src1, GR32:$src2),
"add{l}\t{$src2, $dst|$dst, $src2}",
[(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
This definition makes use of the custom class ``I`` (extended from the custom
class ``X86Inst``), which is defined in the X86-specific TableGen file, to
This definition makes use of the custom class `I` (extended from the custom
class `X86Inst`), which is defined in the X86-specific TableGen file, to
factor out the common features that instructions of its class share. A key
feature of TableGen is that it allows the end user to define the abstractions
they prefer to use when describing their information.
Syntax
======
## Syntax
TableGen has a syntax loosely based on C++ templates, with built-in
types and specification. In addition, TableGen's syntax introduces some
automation concepts like multiclass, foreach, let, etc.
Basic concepts
--------------
### Basic concepts
TableGen files consist of two key parts: 'classes' and 'definitions', both of
which are considered 'records'.
@ -199,40 +195,40 @@ which are considered 'records'.
**TableGen records** have a unique name, a list of values, and a list of
superclasses. The list of values is the main data that TableGen builds for each
record; it is this that holds the domain-specific information for the
application. The interpretation of this data is left to a specific `backend`_,
application. The interpretation of this data is left to a specific {ref}`backend <backend>`,
but the structure and format rules are taken care of and fixed by
TableGen.
**TableGen definitions** are the concrete form of 'records'. These generally do
not have any undefined values and are marked with the '``def``' keyword.
not have any undefined values and are marked with the '`def`' keyword.
.. code-block:: text
```text
def FeatureFPARMv8 : SubtargetFeature<"fp-armv8", "HasFPARMv8", "true",
"Enable ARMv8 FP">;
```
def FeatureFPARMv8 : SubtargetFeature<"fp-armv8", "HasFPARMv8", "true",
"Enable ARMv8 FP">;
In this example, ``FeatureFPARMv8`` is ``SubtargetFeature`` record initialised
In this example, `FeatureFPARMv8` is `SubtargetFeature` record initialised
with some values. The names of the classes are defined via the
keyword `class` either in the same file or some other included. Most target
TableGen files include the generic ones in ``include/llvm/Target``.
TableGen files include the generic ones in `include/llvm/Target`.
**TableGen classes** are abstract records that are used to build and describe
other records. These classes allow the end-user to build abstractions for
either the domain they are targeting (such as ``Register``, ``RegisterClass``, and
``Instruction`` in the LLVM code generator) or for the implementor to help factor
out common properties of records (such as ``FPInst``, which is used to represent
either the domain they are targeting (such as `Register`, `RegisterClass`, and
`Instruction` in the LLVM code generator) or for the implementor to help factor
out common properties of records (such as `FPInst`, which is used to represent
floating point instructions in the X86 backend). TableGen keeps track of all of
the classes that are used to build up a definition, so the backend can find all
definitions of a particular class, such as ``Instruction``.
definitions of a particular class, such as `Instruction`.
.. code-block:: text
```text
class ProcNoItin<string Name, list<SubtargetFeature> Features>
: Processor<Name, NoItineraries, Features>;
```
class ProcNoItin<string Name, list<SubtargetFeature> Features>
: Processor<Name, NoItineraries, Features>;
Here, the class ``ProcNoItin``, receiving parameters ``Name`` of type ``string`` and
a list of target features is specializing the class ``Processor`` by passing the
arguments down as well as hard-coding ``NoItineraries``.
Here, the class `ProcNoItin`, receiving parameters `Name` of type `string` and
a list of target features is specializing the class `Processor` by passing the
arguments down as well as hard-coding `NoItineraries`.
**TableGen multiclasses** are groups of abstract records that are instantiated
all at once. Each instantiation can result in multiple TableGen definitions.
@ -240,36 +236,35 @@ If a multiclass inherits from another multiclass, the definitions in the
sub-multiclass become part of the current multiclass, as if they were declared
in the current multiclass.
.. code-block:: text
```text
multiclass ro_signed_pats<string T, string Rm, dag Base, dag Offset, dag Extend,
dag address, ValueType sty> {
def : Pat<(i32 (!cast<SDNode>("sextload" # sty) address)),
(!cast<Instruction>("LDRS" # T # "w_" # Rm # "_RegOffset")
Base, Offset, Extend)>;
multiclass ro_signed_pats<string T, string Rm, dag Base, dag Offset, dag Extend,
dag address, ValueType sty> {
def : Pat<(i32 (!cast<SDNode>("sextload" # sty) address)),
(!cast<Instruction>("LDRS" # T # "w_" # Rm # "_RegOffset")
Base, Offset, Extend)>;
def : Pat<(i64 (!cast<SDNode>("sextload" # sty) address)),
(!cast<Instruction>("LDRS" # T # "x_" # Rm # "_RegOffset")
Base, Offset, Extend)>;
}
def : Pat<(i64 (!cast<SDNode>("sextload" # sty) address)),
(!cast<Instruction>("LDRS" # T # "x_" # Rm # "_RegOffset")
Base, Offset, Extend)>;
}
defm : ro_signed_pats<"B", Rm, Base, Offset, Extend,
!foreach(decls.pattern, address,
!subst(SHIFT, imm_eq0, decls.pattern)),
i8>;
```
defm : ro_signed_pats<"B", Rm, Base, Offset, Extend,
!foreach(decls.pattern, address,
!subst(SHIFT, imm_eq0, decls.pattern)),
i8>;
See the :doc:`TableGen Programmer's Reference <./ProgRef>` for an in-depth
See the {doc}`TableGen Programmer's Reference <./ProgRef>` for an in-depth
description of TableGen.
.. _backend:
.. _backends:
(backend)=
(backends)=
TableGen backends
=================
## TableGen backends
TableGen files have no real meaning without a backend. The default operation
when running ``*-tblgen`` is to print the information in a textual format, but
when running `*-tblgen` is to print the information in a textual format, but
that's only useful for debugging the TableGen files themselves. The power
in TableGen is, however, to interpret the source files into an internal
representation that can be generated into anything you want.
@ -284,19 +279,17 @@ Pre-processed output should be used if the same information needs to be used
in different contexts (like Instruction names), so your backend should print
a meta-information list that can be shaped into different compile-time formats.
See :doc:`TableGen BackEnds <./BackEnds>` for a list of available
backends, and see the :doc:`TableGen Backend Developer's Guide <./BackGuide>`
See {doc}`TableGen BackEnds <./BackEnds>` for a list of available
backends, and see the {doc}`TableGen Backend Developer's Guide <./BackGuide>`
for information on how to write and debug a new backend.
Tools and Resources
===================
## Tools and Resources
In addition to this documentation, a list of tools and resources for TableGen
can be found in TableGen's
`README <https://github.com/llvm/llvm-project/blob/main/llvm/utils/TableGen/README.md>`_.
[README](https://github.com/llvm/llvm-project/blob/main/llvm/utils/TableGen/README.md).
TableGen Deficiencies
=====================
## TableGen Deficiencies
Despite being very generic, TableGen has some deficiencies that have been
pointed out numerous times. The common theme is that, while TableGen allows

1165
llvm/docs/TestingGuide.md
View file

File diff suppressed because it is too large Load diff

549
llvm/docs/UserGuides.md
View file

@ -1,343 +1,398 @@
User Guides
===========
# User Guides
NOTE: If you are a user who is only interested in using an LLVM-based compiler,
you should look into `Clang <https://clang.llvm.org>`_ instead. The
you should look into [Clang](https://clang.llvm.org) instead. The
documentation here is intended for users who have a need to work with the
intermediate LLVM representation.
.. contents::
:local:
```{contents}
:local:
```
.. toctree::
:hidden:
```{toctree}
:hidden:
HowToBuildOnARM
HowToBuildWithPGO
HowToCrossCompileLLVM
CoverageMappingFormat
CFIVerify
BuildingADistribution
CMake
Docker
SupportLibrary
AdvancedBuilds
WritingAnLLVMNewPMPass
WritingAnLLVMPass
Passes
StackSafetyAnalysis
MergeFunctions
AliasAnalysis
MemorySSA
MemProf
LoopTerminology
CycleTerminology
Vectorizers
LinkTimeOptimization
DTLTO
GoldPlugin
Remarks
SourceLevelDebugging
HowToUpdateDebugInfo
Instrumentor
InstrRefDebugInfo
RemoveDIsDebugInfo
KeyInstructionsDebugInfo
InstrProfileFormat
InstCombineContributorGuide
WritingAnLLVMBackend
CodeGenerator
TableGen/index
GlobalISel/MIRPatterns
MCJITDesignAndImplementation
ORCv2
JITLink
DebuggingJITedCode
CommandLine
ExtendingLLVM
AddingConstrainedIntrinsics
HowToBuildWindowsItaniumPrograms
HowToCrossCompileBuiltinsOnArm
BigEndianNEON
AArch64SME
CompileCudaWithLLVM
NVPTXUsage
AMDGPUUsage
AMDGPUAsyncOperations
AMDGPUDwarfExtensionsForHeterogeneousDebugging
AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack
AMDGPUExecutionSynchronization
AMDGPUMemoryModel
SPIRVUsage
DirectXUsage
RISCVUsage
RISCV/RISCVVectorExtension
RISCV/RISCVVCIX
SandboxIR
Telemetry
LFI
AdminTasks
Benchmarking
CMakePrimer
CodeOfConduct
FatLTO
GitHub
MarkdownQuickstartTemplate
MisExpect
OpaquePointers
NewPassManager
ReportingGuide
ResponseGuide
TableGenFundamentals
yaml2obj
HowToBuildOnARM
HowToBuildWithPGO
HowToCrossCompileLLVM
CoverageMappingFormat
CFIVerify
BuildingADistribution
CMake
Docker
SupportLibrary
AdvancedBuilds
WritingAnLLVMNewPMPass
WritingAnLLVMPass
Passes
StackSafetyAnalysis
MergeFunctions
AliasAnalysis
MemorySSA
MemProf
LoopTerminology
CycleTerminology
Vectorizers
LinkTimeOptimization
DTLTO
GoldPlugin
Remarks
SourceLevelDebugging
HowToUpdateDebugInfo
Instrumentor
InstrRefDebugInfo
RemoveDIsDebugInfo
KeyInstructionsDebugInfo
InstrProfileFormat
InstCombineContributorGuide
WritingAnLLVMBackend
CodeGenerator
TableGen/index
GlobalISel/MIRPatterns
MCJITDesignAndImplementation
ORCv2
JITLink
DebuggingJITedCode
CommandLine
ExtendingLLVM
AddingConstrainedIntrinsics
HowToBuildWindowsItaniumPrograms
HowToCrossCompileBuiltinsOnArm
BigEndianNEON
AArch64SME
CompileCudaWithLLVM
NVPTXUsage
AMDGPUUsage
AMDGPUAsyncOperations
AMDGPUDwarfExtensionsForHeterogeneousDebugging
AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack
AMDGPUExecutionSynchronization
AMDGPUMemoryModel
SPIRVUsage
DirectXUsage
RISCVUsage
RISCV/RISCVVectorExtension
RISCV/RISCVVCIX
SandboxIR
Telemetry
LFI
AdminTasks
Benchmarking
CMakePrimer
CodeOfConduct
FatLTO
GitHub
MarkdownQuickstartTemplate
MisExpect
OpaquePointers
NewPassManager
ReportingGuide
ResponseGuide
TableGenFundamentals
yaml2obj
```
Clang
-----
## Clang
:doc:`HowToBuildOnARM`
Notes on building and testing LLVM/Clang on ARM.
- {doc}`HowToBuildOnARM`
:doc:`HowToBuildWithPGO`
Notes on building LLVM/Clang with PGO.
Notes on building and testing LLVM/Clang on ARM.
:doc:`HowToCrossCompileLLVM`
Notes on cross-building and testing LLVM/Clang.
- {doc}`HowToBuildWithPGO`
`How to build the C, C++, ObjC, and ObjC++ front end`__
Instructions for building the clang front-end from source.
Notes on building LLVM/Clang with PGO.
.. __: https://clang.llvm.org/get_started.html
- {doc}`HowToCrossCompileLLVM`
Notes on cross-building and testing LLVM/Clang.
- [How to build the C, C++, ObjC, and ObjC++ front end](https://clang.llvm.org/get_started.html)
Instructions for building the clang front-end from source.
- {doc}`CoverageMappingFormat`
:doc:`CoverageMappingFormat`
This describes the format and encoding used for LLVM’s code coverage mapping.
:doc:`CFIVerify`
- {doc}`CFIVerify`
A description of the verification tool for Control Flow Integrity.
LLVM Builds and Distributions
-----------------------------
## LLVM Builds and Distributions
- {doc}`BuildingADistribution`
:doc:`BuildingADistribution`
A best-practices guide for using LLVM's CMake build system to package and
distribute LLVM-based tools.
:doc:`CMake`
An addendum to the main Getting Started guide for those using the `CMake
build system <http://www.cmake.org>`_.
- {doc}`CMake`
:doc:`Docker`
A reference for using Dockerfiles provided with LLVM.
An addendum to the main Getting Started guide for those using the [CMake
build system](http://www.cmake.org).
:doc:`Support Library <SupportLibrary>`
This document describes the LLVM Support Library (``lib/Support``) and
how to keep LLVM source code portable.
- {doc}`Docker`
:doc:`AdvancedBuilds`
This document describes more advanced build configurations.
A reference for using Dockerfiles provided with LLVM.
Optimizations
-------------
- {doc}`Support Library <SupportLibrary>`
:doc:`WritingAnLLVMNewPMPass`
Information on how to write LLVM transformations under the new pass
manager.
This document describes the LLVM Support Library (`lib/Support`) and
how to keep LLVM source code portable.
:doc:`WritingAnLLVMPass`
Information on how to write LLVM transformations and analyses under the
legacy pass manager.
- {doc}`AdvancedBuilds`
:doc:`Passes`
A list of optimizations and analyses implemented in LLVM.
This document describes more advanced build configurations.
## Optimizations
- {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.
- {doc}`StackSafetyAnalysis`
:doc:`StackSafetyAnalysis`
This document describes the design of the stack safety analysis of local
variables.
:doc:`MergeFunctions`
- {doc}`MergeFunctions`
Describes functions merging optimization.
:doc:`AliasAnalysis`
Information on how to write a new alias analysis implementation or how to
use existing analyses.
- {doc}`AliasAnalysis`
:doc:`MemorySSA`
Information about the MemorySSA utility in LLVM, as well as how to use it.
Information on how to write a new alias analysis implementation or how to
use existing analyses.
:doc:`MemProf`
User guide and internals of MemProf, profile guided optimizations for memory.
- {doc}`MemorySSA`
Information about the MemorySSA utility in LLVM, as well as how to use it.
- {doc}`MemProf`
User guide and internals of MemProf, profile guided optimizations for memory.
- {doc}`LoopTerminology`
:doc:`LoopTerminology`
A document describing Loops and associated terms as used in LLVM.
:doc:`CycleTerminology`
- {doc}`CycleTerminology`
A document describing cycles as a generalization of loops.
:doc:`Vectorizers`
This document describes the current status of vectorization in LLVM.
- {doc}`Vectorizers`
:doc:`LinkTimeOptimization`
This document describes the interface between LLVM intermodular optimizer
and the linker and its design
This document describes the current status of vectorization in LLVM.
:doc:`DTLTO`
This document describes the DTLTO implementation, which allows for
distributing ThinLTO backend compilations without requiring support from
the build system.
- {doc}`LinkTimeOptimization`
:doc:`GoldPlugin`
How to build your programs with link-time optimization on Linux.
This document describes the interface between LLVM intermodular optimizer
and the linker and its design
:doc:`Remarks`
A reference on the implementation of remarks in LLVM.
- {doc}`DTLTO`
:doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
This document describes the design and philosophy behind the LLVM
source-level debugger.
This document describes the DTLTO implementation, which allows for
distributing ThinLTO backend compilations without requiring support from
the build system.
:doc:`How to Update Debug Info <HowToUpdateDebugInfo>`
This document specifies how to correctly update debug info in various kinds
of code transformations.
- {doc}`GoldPlugin`
:doc:`InstrRefDebugInfo`
This document explains how LLVM uses value tracking, or instruction
referencing, to determine variable locations for debug info in the final
stages of compilation.
How to build your programs with link-time optimization on Linux.
:doc:`RemoveDIsDebugInfo`
This is a migration guide describing how to move from debug info using
intrinsics such as dbg.value to using the non-instruction DbgRecord object.
- {doc}`Remarks`
:doc:`KeyInstructionsDebugInfo`
This document explains how the debug info feature Key Instructions is
implemented in LLVM.
A reference on the implementation of remarks in LLVM.
:doc:`InstrProfileFormat`
This document explains two binary formats of instrumentation-based profiles.
- {doc}`Source Level Debugging with LLVM <SourceLevelDebugging>`
:doc:`InstCombineContributorGuide`
This document specifies guidelines for contributions for InstCombine and
related passes.
This document describes the design and philosophy behind the LLVM
source-level debugger.
:doc:`Instrumentor`
A comprehensive guide to the highly configurable Instrumentor pass for custom
program instrumentation, including the interactive configuration wizard.
- {doc}`How to Update Debug Info <HowToUpdateDebugInfo>`
This document specifies how to correctly update debug info in various kinds
of code transformations.
Code Generation
---------------
- {doc}`InstrRefDebugInfo`
:doc:`WritingAnLLVMBackend`
Information on how to write LLVM backends for machine targets.
This document explains how LLVM uses value tracking, or instruction
referencing, to determine variable locations for debug info in the final
stages of compilation.
:doc:`CodeGenerator`
The design and implementation of the LLVM code generator. Useful if you are
working on retargetting LLVM to a new architecture, designing a new codegen
pass, or enhancing existing components.
- {doc}`RemoveDIsDebugInfo`
:doc:`TableGen <TableGen/index>`
Describes the TableGen tool, which is used heavily by the LLVM code
generator.
This is a migration guide describing how to move from debug info using
intrinsics such as dbg.value to using the non-instruction DbgRecord object.
==========
GlobalISel
==========
- {doc}`KeyInstructionsDebugInfo`
:doc:`MIRPatterns <GlobalISel/MIRPatterns>`
Describes the design of MIR Patterns and how to use them.
This document explains how the debug info feature Key Instructions is
implemented in LLVM.
===
JIT
===
- {doc}`InstrProfileFormat`
:doc:`MCJITDesignAndImplementation`
Describes the inner workings of MCJIT execution engine.
This document explains two binary formats of instrumentation-based profiles.
:doc:`ORCv2`
Describes the design and implementation of the ORC APIs, including some
usage examples, and a guide for users transitioning from ORCv1 to ORCv2.
- {doc}`InstCombineContributorGuide`
:doc:`JITLink`
Describes the design and APIs for the JITLink library, ORC's new JIT
linker.
This document specifies guidelines for contributions for InstCombine and
related passes.
:doc:`DebuggingJITedCode`
How to debug JITed code with GDB.
- {doc}`Instrumentor`
Additional Topics
-----------------
A comprehensive guide to the highly configurable Instrumentor pass for custom
program instrumentation, including the interactive configuration wizard.
## Code Generation
- {doc}`WritingAnLLVMBackend`
Information on how to write LLVM backends for machine targets.
- {doc}`CodeGenerator`
The design and implementation of the LLVM code generator. Useful if you are
working on retargetting LLVM to a new architecture, designing a new codegen
pass, or enhancing existing components.
- {doc}`TableGen <TableGen/index>`
Describes the TableGen tool, which is used heavily by the LLVM code
generator.
### GlobalISel
- {doc}`MIRPatterns <GlobalISel/MIRPatterns>`
Describes the design of MIR Patterns and how to use them.
### JIT
- {doc}`MCJITDesignAndImplementation`
Describes the inner workings of MCJIT execution engine.
- {doc}`ORCv2`
Describes the design and implementation of the ORC APIs, including some
usage examples, and a guide for users transitioning from ORCv1 to ORCv2.
- {doc}`JITLink`
Describes the design and APIs for the JITLink library, ORC's new JIT
linker.
- {doc}`DebuggingJITedCode`
How to debug JITed code with GDB.
## Additional Topics
- {doc}`CommandLine`
:doc:`CommandLine`
Provides information on using the command line parsing library.
:doc:`ExtendingLLVM`
- {doc}`ExtendingLLVM`
Look here to see how to add instructions and intrinsics to LLVM.
:doc:`AddingConstrainedIntrinsics`
Gives the steps necessary when adding a new constrained math intrinsic
to LLVM.
- {doc}`AddingConstrainedIntrinsics`
:doc:`HowToBuildWindowsItaniumPrograms`
Notes on assembling a Windows Itanium environment.
Gives the steps necessary when adding a new constrained math intrinsic
to LLVM.
:doc:`HowToCrossCompileBuiltinsOnArm`
Notes on cross-building and testing the compiler-rt builtins for Arm.
- {doc}`HowToBuildWindowsItaniumPrograms`
Notes on assembling a Windows Itanium environment.
- {doc}`HowToCrossCompileBuiltinsOnArm`
Notes on cross-building and testing the compiler-rt builtins for Arm.
- {doc}`BigEndianNEON`
:doc:`BigEndianNEON`
LLVM's support for generating NEON instructions on big endian ARM targets is
somewhat nonintuitive. This document explains the implementation and rationale.
:doc:`AArch64SME`
- {doc}`AArch64SME`
LLVM's support for AArch64 SME ACLE and ABI.
:doc:`CompileCudaWithLLVM`
- {doc}`CompileCudaWithLLVM`
LLVM support for CUDA.
:doc:`NVPTXUsage`
This document describes using the NVPTX backend to compile GPU kernels.
- {doc}`NVPTXUsage`
:doc:`AMDGPUUsage`
This document describes using the AMDGPU backend to compile GPU kernels.
This document describes using the NVPTX backend to compile GPU kernels.
:doc:`AMDGPUAsyncOperations`
Builtins for invoking asynchronous data transfer operations in AMD GPUs.
- {doc}`AMDGPUUsage`
:doc:`AMDGPUMemoryModel`
This document describes *AMDGPU Memory Model* which overrides the :ref:`LLVM
memory model<memmodel>` when a program is compiled for the AMDGPU target.
This document describes using the AMDGPU backend to compile GPU kernels.
:doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging`
This document describes DWARF extensions to support heterogeneous debugging
for targets such as the AMDGPU backend.
- {doc}`AMDGPUAsyncOperations`
:doc:`AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack`
This document describes a DWARF extension to allow location descriptions on
the DWARF expression stack. It is part of
:doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging`.
Builtins for invoking asynchronous data transfer operations in AMD GPUs.
:doc:`AMDGPUExecutionSynchronization`
This document describes how execution of threads can be synchronized on AMD GPUs.
- {doc}`AMDGPUMemoryModel`
:doc:`SPIRVUsage`
This document describes using the SPIR-V target to compile GPU kernels.
This document describes *AMDGPU Memory Model* which overrides the
{ref}`LLVM memory model <memmodel>` when a program is compiled for the
AMDGPU target.
:doc:`DirectXUsage`
This document describes using the DirectX target to compile GPU code for the
DirectX runtime.
- {doc}`AMDGPUDwarfExtensionsForHeterogeneousDebugging`
:doc:`RISCVUsage`
This document describes using the RISC-V target.
This document describes DWARF extensions to support heterogeneous debugging
for targets such as the AMDGPU backend.
:doc:`RISCV/RISCVVectorExtension`
This document describes how the RISC-V Vector extension can be expressed in LLVM IR and how code is generated for it in the backend.
- {doc}`AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack`
:doc:`RISCV/RISCVVCIX`
This document shows how the scheduling information for RISC-V's ``XSfvcp`` extension -- SiFive Vector Coprocessor Interface (VCIX) -- works and how to customize them.
This document describes a DWARF extension to allow location descriptions on
the DWARF expression stack. It is part of
{doc}`AMDGPUDwarfExtensionsForHeterogeneousDebugging`.
:doc:`Sandbox IR <SandboxIR>`
This document describes the design and usage of Sandbox IR, a transactional layer over LLVM IR.
- {doc}`AMDGPUExecutionSynchronization`
:doc:`Telemetry`
This document describes the Telemetry framework in LLVM.
This document describes how execution of threads can be synchronized on AMD GPUs.
:doc:`LFI <LFI>`
This document describes the Lightweight Fault Isolation (LFI) target in LLVM.
- {doc}`SPIRVUsage`
This document describes using the SPIR-V target to compile GPU kernels.
- {doc}`DirectXUsage`
This document describes using the DirectX target to compile GPU code for the
DirectX runtime.
- {doc}`RISCVUsage`
This document describes using the RISC-V target.
- {doc}`RISCV/RISCVVectorExtension`
This document describes how the RISC-V Vector extension can be expressed in LLVM IR and how code is generated for it in the backend.
- {doc}`RISCV/RISCVVCIX`
This document shows how the scheduling information for RISC-V's `XSfvcp` extension -- SiFive Vector Coprocessor Interface (VCIX) -- works and how to customize them.
- {doc}`Sandbox IR <SandboxIR>`
This document describes the design and usage of Sandbox IR, a transactional layer over LLVM IR.
- {doc}`Telemetry`
This document describes the Telemetry framework in LLVM.
- {doc}`LFI <LFI>`
This document describes the Lightweight Fault Isolation (LFI) target in LLVM.

2507
llvm/docs/WritingAnLLVMBackend.md
View file

File diff suppressed because it is too large Load diff

310
llvm/docs/WritingAnLLVMNewPMPass.md
View file

@ -1,19 +1,19 @@
====================
Writing an LLVM Pass
====================
# Writing an LLVM Pass
.. program:: opt
```{program} opt
```
.. contents::
:local:
```{contents}
:local:
```
Introduction --- What is a 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`.
```{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
@ -24,19 +24,18 @@ are, above all, a structuring technique for compiler code.
Unlike passes under the legacy pass manager where the pass interface is
defined via inheritance, passes under the new pass manager rely on
concept-based polymorphism, meaning there is no explicit interface (see
comments in ``PassManager.h`` for more details). All LLVM passes inherit from
the CRTP mix-in ``OptionalPassInfoMixin<PassT>`` or
``RequiredPassInfoMixin<PassT>``. The pass should have a ``run()``
method which returns a ``PreservedAnalyses`` and takes in some unit of IR
comments in `PassManager.h` for more details). All LLVM passes inherit from
the CRTP mix-in `OptionalPassInfoMixin<PassT>` or
`RequiredPassInfoMixin<PassT>`. The pass should have a `run()`
method which returns a `PreservedAnalyses` and takes in some unit of IR
along with an analysis manager. For example, a function pass would have a
``PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM);`` method.
`PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM);` method.
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.
Quick Start --- Writing hello world
===================================
## Quick Start --- Writing hello world
Here we describe how to write the "hello world" of passes. The "HelloWorld"
pass is designed to simply print out the name of non-external functions that
@ -46,247 +45,240 @@ it just inspects it.
The code below already exists; feel free to create a pass with a different
name alongside the HelloWorld source files.
.. _writing-an-llvm-npm-pass-build:
(writing-an-llvm-npm-pass-build)=
Setting up the build
--------------------
### Setting up the build
First, configure and build LLVM as described in :doc:`GettingStarted`.
First, configure and build LLVM as described in {doc}`GettingStarted`.
Next, we will reuse an existing directory (creating a new directory involves
messing around with more CMake files than we want). For this example, we'll use
``llvm/lib/Transforms/Utils/HelloWorld.cpp``, which has already been created.
`llvm/lib/Transforms/Utils/HelloWorld.cpp`, which has already been created.
If you'd like to create your own pass, add a new source file into
``llvm/lib/Transforms/Utils/CMakeLists.txt`` (assuming you want your pass in
the ``Transforms/Utils`` directory.
`llvm/lib/Transforms/Utils/CMakeLists.txt` (assuming you want your pass in
the `Transforms/Utils` directory.
Now that we have the build set up for a new pass, we need to write the code
for the pass itself.
.. _writing-an-llvm-npm-pass-basiccode:
(writing-an-llvm-npm-pass-basiccode)=
Basic code required
-------------------
### Basic code required
Now that the build is setup for a new pass, we just have to write it.
First we need to define the pass in a header file. We'll create
``llvm/include/llvm/Transforms/Utils/HelloWorld.h``. The file should
`llvm/include/llvm/Transforms/Utils/HelloWorld.h`. The file should
contain the following boilerplate:
.. code-block:: c++
```c++
#ifndef LLVM_TRANSFORMS_HELLONEW_HELLOWORLD_H
#define LLVM_TRANSFORMS_HELLONEW_HELLOWORLD_H
#ifndef LLVM_TRANSFORMS_HELLONEW_HELLOWORLD_H
#define LLVM_TRANSFORMS_HELLONEW_HELLOWORLD_H
#include "llvm/IR/PassManager.h"
#include "llvm/IR/PassManager.h"
namespace llvm {
namespace llvm {
class HelloWorldPass : public OptionalPassInfoMixin<HelloWorldPass> {
public:
PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM);
};
class HelloWorldPass : public OptionalPassInfoMixin<HelloWorldPass> {
public:
PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM);
};
} // namespace llvm
} // namespace llvm
#endif // LLVM_TRANSFORMS_HELLONEW_HELLOWORLD_H
```
#endif // LLVM_TRANSFORMS_HELLONEW_HELLOWORLD_H
This creates the class for the pass with a declaration of the ``run()``
This creates the class for the pass with a declaration of the `run()`
method which actually runs the pass. Inheriting from
``OptionalPassInfoMixin<PassT>`` or ``RequiredPassInfoMixin<PassT>`` sets up
`OptionalPassInfoMixin<PassT>` or `RequiredPassInfoMixin<PassT>` sets up
some more boilerplate so that we don't have to write it ourselves.
``RequiredPassInfoMixin`` should be used for passes that cannot be skipped
(e.g. ``AlwaysInlinerPass``), while ``OptionalPassInfoMixin`` should be used
`RequiredPassInfoMixin` should be used for passes that cannot be skipped
(e.g. `AlwaysInlinerPass`), while `OptionalPassInfoMixin` should be used
for passes that can be skipped (e.g. optimization passes).
Our class is in the ``llvm`` namespace so that we don't pollute the global
Our class is in the `llvm` namespace so that we don't pollute the global
namespace.
Next we'll create ``llvm/lib/Transforms/Utils/HelloWorld.cpp``, starting
Next we'll create `llvm/lib/Transforms/Utils/HelloWorld.cpp`, starting
with
.. code-block:: c++
#include "llvm/Transforms/Utils/HelloWorld.h"
```c++
#include "llvm/Transforms/Utils/HelloWorld.h"
```
... to include the header file we just created.
.. code-block:: c++
using namespace llvm;
```c++
using namespace llvm;
```
... is required because the functions from the include files live in the llvm
namespace. This should only be done in non-header files.
Next we have the pass's ``run()`` definition:
Next we have the pass's `run()` definition:
.. code-block:: c++
PreservedAnalyses HelloWorldPass::run(Function &F,
FunctionAnalysisManager &AM) {
errs() << F.getName() << "\n";
return PreservedAnalyses::all();
}
```c++
PreservedAnalyses HelloWorldPass::run(Function &F,
FunctionAnalysisManager &AM) {
errs() << F.getName() << "\n";
return PreservedAnalyses::all();
}
```
... which simply prints out the name of the function to stderr. The pass
manager will ensure that the pass will be run on every function in a module.
The ``PreservedAnalyses`` return value says that all analyses (e.g. dominator
The `PreservedAnalyses` return value says that all analyses (e.g. dominator
tree) are still valid after this pass since we didn't modify any functions.
That's it for the pass itself. Now in order to "register" the pass, we need
to add it to a couple places. Add the following to
``llvm/lib/Passes/PassRegistry.def`` in the ``FUNCTION_PASS`` section
`llvm/lib/Passes/PassRegistry.def` in the `FUNCTION_PASS` section
.. code-block:: c++
FUNCTION_PASS("helloworld", HelloWorldPass())
```c++
FUNCTION_PASS("helloworld", HelloWorldPass())
```
... which adds the pass under the name "helloworld".
``llvm/lib/Passes/PassRegistry.def`` is #include'd into
``llvm/lib/Passes/PassBuilder.cpp`` multiple times for various reasons. Since
`llvm/lib/Passes/PassRegistry.def` is #include'd into
`llvm/lib/Passes/PassBuilder.cpp` multiple times for various reasons. Since
it constructs our pass, we need to also add the proper #include in
``llvm/lib/Passes/PassBuilder.cpp``:
`llvm/lib/Passes/PassBuilder.cpp`:
.. code-block:: c++
#include "llvm/Transforms/Utils/HelloWorld.h"
```c++
#include "llvm/Transforms/Utils/HelloWorld.h"
```
This should be all the code necessary for our pass, now it's time to compile
and run it.
Running a pass with ``opt``
---------------------------
### Running a pass with `opt`
Now that you have a brand new shiny pass, we can build :program:`opt` and use
Now that you have a brand new shiny pass, we can build {program}`opt` and use
it to run some LLVM IR through the pass.
.. code-block:: console
```console
$ ninja -C build/ opt
# or whatever build system/build directory you are using
$ ninja -C build/ opt
# or whatever build system/build directory you are using
$ cat /tmp/a.ll
define i32 @foo() {
%a = add i32 2, 3
ret i32 %a
}
$ cat /tmp/a.ll
define i32 @foo() {
%a = add i32 2, 3
ret i32 %a
}
define void @bar() {
ret void
}
define void @bar() {
ret void
}
$ build/bin/opt -disable-output /tmp/a.ll -passes=helloworld
foo
bar
$ build/bin/opt -disable-output /tmp/a.ll -passes=helloworld
foo
bar
```
Our pass ran and printed the names of functions as expected!
Testing a pass
--------------
### Testing a pass
Testing our pass is important to prevent future regressions. We'll add a lit
test at ``llvm/test/Transforms/Utils/helloworld.ll``. See
:doc:`TestingGuide` for more information on testing.
test at `llvm/test/Transforms/Utils/helloworld.ll`. See
{doc}`TestingGuide` for more information on testing.
.. code-block:: llvm
```llvm
$ cat llvm/test/Transforms/Utils/helloworld.ll
; RUN: opt -disable-output -passes=helloworld %s 2>&1 | FileCheck %s
$ cat llvm/test/Transforms/Utils/helloworld.ll
; RUN: opt -disable-output -passes=helloworld %s 2>&1 | FileCheck %s
; CHECK: {{^}}foo{{$}}
define i32 @foo() {
%a = add i32 2, 3
ret i32 %a
}
; CHECK: {{^}}foo{{$}}
define i32 @foo() {
%a = add i32 2, 3
ret i32 %a
}
; CHECK-NEXT: {{^}}bar{{$}}
define void @bar() {
ret void
}
; CHECK-NEXT: {{^}}bar{{$}}
define void @bar() {
ret void
}
$ ninja -C build check-llvm
# runs our new test alongside all other llvm lit tests
```
$ ninja -C build check-llvm
# runs our new test alongside all other llvm lit tests
## FAQs
FAQs
====
### Required passes
Required passes
---------------
A pass that inherits from `RequiredPassInfoMixin<PassT>` is a required pass. For example:
A pass that inherits from ``RequiredPassInfoMixin<PassT>`` is a required pass. For example:
.. code-block:: c++
class HelloWorldPass : public RequiredPassInfoMixin<HelloWorldPass> {
public:
PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM);
};
```c++
class HelloWorldPass : public RequiredPassInfoMixin<HelloWorldPass> {
public:
PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM);
};
```
A required pass is a pass that may not be skipped. An example of a required
pass is ``AlwaysInlinerPass``, which must always be run to preserve
``alwaysinline`` semantics. Pass managers are required since they may contain
pass is `AlwaysInlinerPass`, which must always be run to preserve
`alwaysinline` semantics. Pass managers are required since they may contain
other required passes.
An example of how a pass can be skipped is the ``optnone`` function
An example of how a pass can be skipped is the `optnone` function
attribute, which specifies that optimizations should not be run on the
function. Required passes will still be run on ``optnone`` functions.
function. Required passes will still be run on `optnone` functions.
For more implementation details, see
``PassInstrumentation::runBeforePass()``.
`PassInstrumentation::runBeforePass()`.
Registering passes as plugins
-----------------------------
### Registering passes as plugins
LLVM provides a mechanism to register pass plugins within various tools like
``clang`` or ``opt``. A pass plugin can add passes to default optimization
pipelines or to be manually run via tools like ``opt``. For more information,
see :doc:`NewPassManager`.
`clang` or `opt`. A pass plugin can add passes to default optimization
pipelines or to be manually run via tools like `opt`. For more information,
see {doc}`NewPassManager`.
Create a CMake project at the root of the repo alongside
other projects. This project must contain the following minimal
``CMakeLists.txt``:
`CMakeLists.txt`:
.. code-block:: cmake
```cmake
add_llvm_pass_plugin(MyPassName source.cpp)
```
add_llvm_pass_plugin(MyPassName source.cpp)
See the definition of ``add_llvm_pass_plugin`` for more CMake details.
See the definition of `add_llvm_pass_plugin` for more CMake details.
The pass must provide at least one of two entry points for the new pass manager,
one for static registration and one for dynamically loaded plugins:
- ``llvm::PassPluginLibraryInfo get##Name##PluginInfo();``
- ``extern "C" ::llvm::PassPluginLibraryInfo llvmGetPassPluginInfo() LLVM_ATTRIBUTE_WEAK;``
- `llvm::PassPluginLibraryInfo get##Name##PluginInfo();`
- `extern "C" ::llvm::PassPluginLibraryInfo llvmGetPassPluginInfo() LLVM_ATTRIBUTE_WEAK;`
Pass plugins are compiled and linked dynamically by default. Setting
``LLVM_${NAME}_LINK_INTO_TOOLS`` to ``ON`` turns the project into a statically
`LLVM_${NAME}_LINK_INTO_TOOLS` to `ON` turns the project into a statically
linked extension.
For an in-tree example, see ``llvm/examples/Bye/``.
For an in-tree example, see `llvm/examples/Bye/`.
To make ``PassBuilder`` aware of statically linked pass plugins:
To make `PassBuilder` aware of statically linked pass plugins:
.. code-block:: c++
```c++
// Declare plugin extension function declarations.
#define HANDLE_EXTENSION(Ext) llvm::PassPluginLibraryInfo get##Ext##PluginInfo();
#include "llvm/Support/Extension.def"
// Declare plugin extension function declarations.
#define HANDLE_EXTENSION(Ext) llvm::PassPluginLibraryInfo get##Ext##PluginInfo();
#include "llvm/Support/Extension.def"
...
...
// Register plugin extensions in PassBuilder.
#define HANDLE_EXTENSION(Ext) get##Ext##PluginInfo().RegisterPassBuilderCallbacks(PB);
#include "llvm/Support/Extension.def"
```
// Register plugin extensions in PassBuilder.
#define HANDLE_EXTENSION(Ext) get##Ext##PluginInfo().RegisterPassBuilderCallbacks(PB);
#include "llvm/Support/Extension.def"
To make `PassBuilder` aware of dynamically linked pass plugins:
To make ``PassBuilder`` aware of dynamically linked pass plugins:
.. code-block:: c++
// Load plugin dynamically.
auto Plugin = PassPlugin::Load(PathToPlugin);
if (!Plugin)
report_error();
// Register plugin extensions in PassBuilder.
Plugin.registerPassBuilderCallbacks(PB);
```c++
// Load plugin dynamically.
auto Plugin = PassPlugin::Load(PathToPlugin);
if (!Plugin)
report_error();
// Register plugin extensions in PassBuilder.
Plugin.registerPassBuilderCallbacks(PB);
```

955
llvm/docs/WritingAnLLVMPass.md
View file

File diff suppressed because it is too large Load diff

9
llvm/docs/conf.py
View file

@ -39,7 +39,14 @@ except ImportError:
if not tags.has("builder-man"):
raise
else:
myst_enable_extensions = ["substitution"]
myst_enable_extensions = ["deflist", "substitution"]
myst_url_schemes = {
"http": None,
"https": None,
"mailto": None,
"ftp": None,
"doxygen": {"url": "/doxygen/{{path}}"},
}
# Automatic anchors for markdown titles
myst_heading_anchors = 6

128
llvm/docs/index.md
View file

@ -1,10 +1,11 @@
About
========
# About
.. warning::
```{warning}
If you are using a released version of LLVM, see [the download page]
to find your documentation.
```
If you are using a released version of LLVM, see `the download page
<https://llvm.org/releases/>`_ to find your documentation.
[the download page]: https://llvm.org/releases/
The LLVM compiler infrastructure supports a wide range of projects, from
industrial strength compilers to specialized JIT applications to small
@ -13,96 +14,91 @@ research projects.
Similarly, documentation is broken down into several high-level groupings
targeted at different audiences:
LLVM Design & Overview
======================
# LLVM Design & Overview
Several introductory papers and presentations.
.. toctree::
:hidden:
```{toctree}
:hidden:
FAQ
Lexicon
FAQ
Lexicon
```
:doc:`FAQ`
Frequently asked questions.
{doc}`FAQ`
: Frequently asked questions.
:doc:`Lexicon`
Glossary.
{doc}`Lexicon`
: Glossary.
`Introduction to the LLVM Compiler`__
Presentation providing a users introduction to LLVM.
[Introduction to the LLVM Compiler]
: Presentation providing a users introduction to LLVM.
.. __: https://llvm.org/pubs/2008-10-04-ACAT-LLVM-Intro.html
`Intro to LLVM`__
A chapter from the book "The Architecture of Open Source Applications" that
[Intro to LLVM]
: A chapter from the book "The Architecture of Open Source Applications" that
describes high-level design decisions that shaped LLVM.
.. __: http://www.aosabook.org/en/llvm.html
[LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation][llvm-lifelong]
: Design overview.
[LLVM: An Infrastructure for Multi-Stage Optimization][llvm-multi-stage]
: More details (quite old now).
`LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation`__
Design overview.
[Introduction to the LLVM Compiler]: https://llvm.org/pubs/2008-10-04-ACAT-LLVM-Intro.html
[Intro to LLVM]: http://www.aosabook.org/en/llvm.html
[llvm-lifelong]: https://llvm.org/pubs/2004-01-30-CGO-LLVM.html
[llvm-multi-stage]: https://llvm.org/pubs/2002-12-LattnerMSThesis.html
.. __: https://llvm.org/pubs/2004-01-30-CGO-LLVM.html
`LLVM: An Infrastructure for Multi-Stage Optimization`__
More details (quite old now).
.. __: https://llvm.org/pubs/2002-12-LattnerMSThesis.html
Documentation
=============
# Documentation
Getting Started, How-tos, Developer Guides, and Tutorials.
.. toctree::
:hidden:
```{toctree}
:hidden:
GettingStartedTutorials
Reference
UserGuides
DiscourseMigrationGuide
GettingStartedTutorials
Reference
UserGuides
DiscourseMigrationGuide
```
:doc:`GettingStartedTutorials`
For those new to the LLVM system.
{doc}`GettingStartedTutorials`
: For those new to the LLVM system.
:doc:`UserGuides`
User guides and How-tos.
{doc}`UserGuides`
: User guides and How-tos.
:doc:`Reference`
LLVM and API reference documentation.
{doc}`Reference`
: LLVM and API reference documentation.
:doc:`DiscourseMigrationGuide`
Guide for users to migrate to Discourse
{doc}`DiscourseMigrationGuide`
: Guide for users to migrate to Discourse
Community
=========
# Community
LLVM welcomes contributions of all kinds. To learn more, see the following articles:
.. toctree::
:hidden:
```{toctree}
:hidden:
GettingInvolved
RFCProcess
ProjectGovernance
GettingInvolved
RFCProcess
ProjectGovernance
```
* :doc:`GettingInvolved`
* :ref:`development-process`
* :doc:`RFCProcess`
* :doc:`ProjectGovernance`
* :ref:`lists-forums`
* :ref:`meetups-social-events`
* :ref:`community-proposals`
* {doc}`GettingInvolved`
* {ref}`development-process`
* {doc}`RFCProcess`
* {doc}`ProjectGovernance`
* {ref}`lists-forums`
* {ref}`meetups-social-events`
* {ref}`community-proposals`
Reporting a security issue
* :ref:`report-security-issue`
* {ref}`report-security-issue`
Indices and tables
==================
# Indices and tables
* :ref:`genindex`
* :ref:`search`
* {ref}`genindex`
* {ref}`search`