openmp/docs/index.md

```{title} Welcome to the documentation of OpenMP in LLVM!
```

:::{note}
This document is a work in progress and most of the expected content is not
yet available. While you can expect changes, we always welcome feedback and
additions. Please post on the [Discourse forums (Runtimes -
OpenMP)](https://discourse.llvm.org/c/runtimes/openmp/35)..
:::

:::{toctree}
:hidden: true
:maxdepth: 1

LLVM/OpenMP Documentation <self>
Building
:::

# Getting Started

Building LLVM/OpenMP is fully documented on the
{doc}`Building` page. For a quick start, we recommend the following template
for building OpenMP with offloading support.

```console
$ git clone https://github.com/llvm/llvm-project.git
$ cd llvm-project
$ mkdir build
$ cd build
$ cmake ../llvm -G Ninja                      \
     -C ../offload/cmake/caches/Offload.cmake \
     -DCMAKE_BUILD_TYPE=Release               \
     -DCMAKE_INSTALL_PREFIX=<PATH>
$ ninja install    # Builds all files and installs files to <PATH>/bin, <PATH>/lib, etc
```

# LLVM/OpenMP Design & Overview

OpenMP impacts various parts of the LLVM project, from the frontends ([Clang](https://clang.llvm.org/docs/OpenMPSupport.html) and Flang), through
middle-end {ref}`optimizations <llvm_openmp_optimizations>`, up to the
multitude of available {ref}`OpenMP runtimes <openmp_runtimes>`.

A high-level overview of OpenMP in LLVM can be found {doc}`here <design/Overview>`.

:::{toctree}
:hidden: true
:maxdepth: 1

design/Overview
:::

# OpenACC Support

{doc}`OpenACC support <openacc/Overview>` is under development for
both Flang and Clang. For this purpose, LLVM's OpenMP runtimes are
being extended to serve as OpenACC runtimes. In some cases, Clang
supports {doc}`OpenMP extensions <openacc/OpenMPExtensions>` to make
the additional functionality also available in OpenMP applications.

:::{toctree}
:hidden: true
:maxdepth: 1

openacc/Overview
:::

# LLVM/OpenMP Optimizations

LLVM, since [version 11](https://releases.llvm.org/download.html#11.0.0) (12 Oct
2020), has an {doc}`OpenMP-Aware optimization pass <optimizations/OpenMPOpt>`
as well as the ability to {doc}`perform "scalar optimizations" across OpenMP region
boundaries <optimizations/OpenMPUnawareOptimizations>`.

In-depth discussion of the topic can be found {doc}`here <optimizations/Overview>`.

:::{toctree}
:hidden: true
:maxdepth: 1

optimizations/Overview
:::

# LLVM/OpenMP Optimization Remarks

LLVM has an elaborate ecosystem around [analysis and optimization remarks](https://llvm.org/docs/Remarks.html) issues during
compilation. The remarks can be enabled from the clang frontend [\[1\]][remarks-1] [\[2\]][remarks-2]
in various formats [\[3\]][remarks-3] [\[4\]][remarks-4] to be used by tools, i.a., {title-reference}`opt-viewer` or
{title-reference}`llvm-opt-report` (dated).

The OpenMP optimizations in LLVM have been developed with remark support as a
priority. For a list of OpenMP specific remarks and more information on them,
please refer to {doc}`remarks/OptimizationRemarks`.

- [\[1\]][remarks-1] <https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports>
- [\[2\]][remarks-2] <https://clang.llvm.org/docs/ClangCommandLineReference.html#diagnostic-flags>
- [\[3\]][remarks-3] <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-foptimization-record-file>
- [\[4\]][remarks-4] <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang1-fsave-optimization-record>

:::{toctree}
:hidden: true
:maxdepth: 1

remarks/OptimizationRemarks
:::

# OpenMP Command-Line Argument Reference

In addition to the
[Clang command-line argument reference](https://clang.llvm.org/docs/ClangCommandLineReference.html)
we also recommend the OpenMP
{doc}`command-line argument reference <CommandLineArgumentReference>`
page that offers a detailed overview of options specific to OpenMP. It also
contains a list of OpenMP offloading related command-line arguments.

:::{toctree}
:hidden: true
:maxdepth: 1

CommandLineArgumentReference
:::

# Support, Getting Involved, and Frequently Asked Questions (FAQ)

Dealing with OpenMP can be complicated. For help with the setup of an OpenMP
(offload) capable compiler toolchain, its usage, and common problems, consult
the {doc}`Support and FAQ <SupportAndFAQ>` page.

We also encourage everyone interested in OpenMP in LLVM to {doc}`get involved
<SupportAndFAQ>`.

:::{toctree}
:hidden: true
:maxdepth: 1

SupportAndFAQ
:::

# Release Notes

The current (in-progress) release notes can be found {doc}`here <ReleaseNotes>` while
release notes for releases, starting with LLVM 12, will be available on [the
Download Page](https://releases.llvm.org/download.html).

:::{toctree}
:hidden: true
:maxdepth: 1

In-Progress ReleaseNotes <ReleaseNotes>
:::

[remarks-1]: https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports
[remarks-2]: https://clang.llvm.org/docs/ClangCommandLineReference.html#diagnostic-flags
[remarks-3]: https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-foptimization-record-file
[remarks-4]: https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang1-fsave-optimization-record