Unify build documentation and convert to reStructuredText

[Hahnfeld]

Summary

We now have several options that apply for both libraries and they
shouldn't be documented in multiple files. When already merging
the two Build_With_CMake.txt documents, convert them to
reStructuredText which is used for all of LLVM's documentation.

[Hahnfeld]

This is a first version, I will do another pass tomorrow. Proof-reading would be much appreciated :-)

[grokos]

README.rst

41

all values (remove "the")

187

What is that question mark?

232

assembly --> assembler?

257–259

We had an internal discussion about it. Do we have consensus that we'll support bclib?

282

I think we should we also include something like:

**LIBOMPTARGET_NVPTX_DEBUG**
Enable printing of debug messages from the nvptx runtime.

Following you comments on the nvptx patch, I added this entry in my local branch and I was planning to include it in the next diff. You can add it in this patch instead. However, there are no ON or OFF options, the symbol is either defined or not defined.

318–319

Remove commas before "and" (2 places).

[grokos]

README.rst

278

The default is still sm_30, let's patch clang first to use sm_35. Also, given that the nvptx runtime cannot be built with sm<35, should we add to the description that sm_35 is the minimum required?

[Hahnfeld]

Improvements based on review comments and extensions to some paragraphs.

README.rst

257–259

For now, I've only copied what has been in libomptarget/Build_With_CMake.txt. To be honest I think we should remove this paragraph entirely because the NVPTX runtime hasn't been committed yet so that we don't confuse the users.

318–319

Some of the comas are intentional to be consistent with the rest of LLVM's documentation: https://en.wikipedia.org/wiki/Serial_comma

[Hahnfeld]

Removed documentation about the NVPTX runtime for now which isn't committed yet.

[Hahnfeld]

Ping. Is this ok to land before the 6.0 branch?

[omalyshe]

README.rst

141

The correct name is "Intel® Many Integrated Core Architecture (Intel® MIC Architecture)".

153

Linux*

154

Windows*
macOS*

168

macOS*
and the same in the next line OS X* ->macOS*

195

Probably it's worth to add "Include support for the OpenMP Tools Interface (OMPT)"

[Hahnfeld]

Address review comments and pay attention to protected names.

[omalyshe]

LGTM.

CMakeLists.txt

if (OPENMP_STANDALONE_BUILD OR "${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_CURRENT_SOURCE_DIR}")
   if (NOT CMAKE_BUILD_TYPE)
     set(CMAKE_BUILD_TYPE Release)
   endif()
 
   # Group common settings.
   set(OPENMP_ENABLE_WERROR FALSE CACHE BOOL
     "Enable -Werror flags to turn warnings into errors for supporting compilers.")
   set(OPENMP_LIBDIR_SUFFIX "" CACHE STRING
-    "suffix of lib installation directory, e.g. 64 => lib64")
+    "Suffix of lib installation directory, e.g. 64 => lib64")
 
   # Group test settings.
   set(OPENMP_TEST_C_COMPILER ${CMAKE_C_COMPILER} CACHE STRING
     "C compiler to use for testing OpenMP runtime libraries.")
   set(OPENMP_TEST_CXX_COMPILER ${CMAKE_CXX_COMPILER} CACHE STRING
     "C++ compiler to use for testing OpenMP runtime libraries.")
   set(OPENMP_LLVM_TOOLS_DIR "" CACHE PATH "Path to LLVM tools for testing.")
 else()

README.rst

+========================================
+How to Build the LLVM* OpenMP* Libraries
+========================================
+This repository requires `CMake <http://www.cmake.org/>`_ v2.8.0 or later.  LLVM
+and Clang need a more recent version which also applies for in-tree builds.  For
+more information than available in this document please see
+`LLVM's CMake documentation <http://llvm.org/docs/CMake.html>`_ and the
+`official documentation <https://cmake.org/cmake/help/v2.8.0/cmake.html>`_.
+
+.. contents::
+   :local:
+
+How to Call CMake Initially, then Repeatedly
+============================================
+- When calling CMake for the first time, all needed compiler options must be
+  specified on the command line.  After this initial call to CMake, the compiler
+  definitions must not be included for further calls to CMake.  Other options
+  can be specified on the command line multiple times including all definitions
+  in the build options section below.
+- Example of configuring, building, reconfiguring, rebuilding:
+
+  .. code-block:: console
+
+    $ mkdir build
+    $ cd build
+    $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..  # Initial configuration
+    $ make
+    ...
+    $ make clean
+    $ cmake -DCMAKE_BUILD_TYPE=Debug ..                               # Second configuration
+    $ make
+    ...
+    $ rm -rf *
+    $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..        # Third configuration
+    $ make
+
+- Notice in the example how the compiler definitions are only specified for an
+  empty build directory, but other build options are used at any time.
+- The file ``CMakeCache.txt`` which is created after the first call to CMake is
+  a configuration file which holds all values for the build options.  These
+  values can be changed using a text editor to modify ``CMakeCache.txt`` as
+  opposed to using definitions on the command line.
+- To have CMake create a particular type of build generator file simply include
+  the ``-G <Generator name>`` option:
+
+  .. code-block:: console
+
+    $ cmake -G "Unix Makefiles" ...
+
+  You can see a list of generators CMake supports by executing the cmake command
+  with no arguments.
+
+Instructions to Build
+=====================
+.. code-block:: console
+
+ $ cd openmp_top_level/ [ this directory with libomptarget/, runtime/, etc. ]
+ $ mkdir build
+ $ cd build
+
+ [ Unix* Libraries ]
+ $ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> ..
+
+ [ Windows Libraries ]
+ $ cmake -G <Generator Type> -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> -DCMAKE_ASM_MASM_COMPILER=[ml | ml64] -DCMAKE_BUILD_TYPE=Release ..
+
+ $ make
+ $ make install
+
+CMake Options
+=============
+Builds with CMake can be customized by means of options as already seen above.
+One possibility is to pass them via the command line:
+
+.. code-block:: console
+
+  $ cmake -DOPTION=<value> path/to/source
+
+.. note:: The first value listed is the respective default for that option.
+
+Generic Options
+---------------
+For full documentation consult the CMake manual or execute
+``cmake --help-variable VARIABLE_NAME`` to get information about a specific
+variable.
+
+**CMAKE_BUILD_TYPE** = ``Release|Debug|RelWithDebInfo``
+  Build type can be ``Release``, ``Debug``, or ``RelWithDebInfo`` which chooses
+  the optimization level and presence of debugging symbols.
+
+**CMAKE_C_COMPILER** = <C compiler name>
+  Specify the C compiler.
+
+**CMAKE_CXX_COMPILER** = <C++ compiler name>
+  Specify the C++ compiler.
+
+**CMAKE_Fortran_COMPILER** = <Fortran compiler name>
+  Specify the Fortran compiler. This option is only needed when
+  **LIBOMP_FORTRAN_MODULES** is ``ON`` (see below).  So typically, a Fortran
+  compiler is not needed during the build.
+
+**CMAKE_ASM_MASM_COMPILER** = ``ml|ml64``
+  This option is only relevant for Windows*.
+
+Options for all Libraries
+-------------------------
+
+**OPENMP_ENABLE_WERROR** = ``OFF|ON``
+  Treat warnings as errors and fail, if a compiler warning is triggered.
+
+**OPENMP_LIBDIR_SUFFIX** = ``""``
+  Extra suffix to append to the directory where libraries are to be installed.
+
+**OPENMP_TEST_C_COMPILER** = ``${CMAKE_C_COMPILER}``
+  Compiler to use for testing. Defaults to the compiler that was also used for
+  building.
+
+**OPENMP_TEST_CXX_COMPILER** = ``${CMAKE_CXX_COMPILER}``
+  Compiler to use for testing. Defaults to the compiler that was also used for
+  building.
+
+**OPENMP_LLVM_TOOLS_DIR** = ``/path/to/built/llvm/tools``
+  Additional path to search for LLVM tools needed by tests.
+
+**OPENMP_LLVM_LIT_EXECUTABLE** = ``/path/to/llvm-lit``
+  Specify full path to ``llvm-lit`` executable for running tests.  The default
+  is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**.
+
+**OPENMP_FILECHECK_EXECUTABLE** = ``/path/to/FileCheck``
+  Specify full path to ``FileCheck`` executable for running tests.  The default
+  is to search the ``PATH`` and the directory in **OPENMP_LLVM_TOOLS_DIR**.
+
+Options for ``libomp``
+----------------------
+
+**LIBOMP_ARCH** = ``aarch64|arm|i386|mic|mips|mips64|ppc64|ppc64le|x86_64``
+  The default value for this option is chosen based on probing the compiler for
+  architecture macros (e.g., is ``__x86_64__`` predefined by compiler?).
+
+**LIBOMP_MIC_ARCH** = ``knc|knf``
+  Intel(R) MIC architecture to build for.  This value is ignored if
+  **LIBOMP_ARCH** does not equal ``mic``.
+
+**LIBOMP_OMP_VERSION** = ``50|45|40|30``
+  OpenMP version to build for.  Older versions will disable certain
+  functionality and entry points.
+
+**LIBOMP_LIB_TYPE** = ``normal|profile|stubs``
+  Library type can be ``normal``, ``profile``, or ``stubs``.
+
+**LIBOMP_USE_VERSION_SYMBOLS** = ``ON|OFF``
+  Use versioned symbols for building the library.  This option only makes sense
+  for ELF based libraries where version symbols are supported (Linux, some BSD*
+  variants).  It is ``OFF`` by default for Windows and Mac, but ``ON`` for other
+  Unix based operating systems.
+
+**LIBOMP_ENABLE_SHARED** = ``ON|OFF``
+  Build a shared library.  If this option is ``OFF``, static OpenMP libraries
+  will be built instead of dynamic ones.
+
+  .. note::
+
+    Static libraries are not supported on Windows.
+
+**LIBOMP_FORTRAN_MODULES** = ``OFF|ON``
+  Create the Fortran modules (requires Fortran compiler).
+
+Mac* Fat Libraries
+""""""""""""""""""
+On OS X* machines, it is possible to build universal (or fat) libraries which
+include both i386 and x86_64 architecture objects in a single archive.
+
+.. code-block:: console
+
+  $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_OSX_ARCHITECTURES='i386;x86_64' ..
+  $ make
+
+There is also an option **LIBOMP_OSX_ARCHITECTURES** which can be set in case
+this is an LLVM source tree build. It will only apply for the ``libomp`` library
+avoids having the entire LLVM/Clang build produce universal binaries.
+
+Optional Features
+"""""""""""""""""
+
+**LIBOMP_USE_ADAPTIVE_LOCKS** = ``ON|OFF``
+  Include adaptive locks, based on Intel(R) Transactional Synchronization
+  Extensions (Intel(R) TSX).  This feature is x86 specific and turned ``ON``
+  by default for IA-32 architecture and Intel(R) 64 architecture.
+
+**LIBOMP_USE_INTERNODE_ALIGNMENT** = ``OFF|ON``
+  Align certain data structures on 4096-byte.  This option is useful on
+  multi-node systems where a small ``CACHE_LINE`` setting leads to false sharing.
+
+**LIBOMP_OMPT_SUPPORT** = ``OFF|ON``
+  Include support for the OpenMP Tools Interface.
+
+**LIBOMP_OMPT_OPTIONAL** = ``ON|OFF``
+  Include support for optional OMPT functionality.  This option is ignored if
+  **LIBOMP_OMPT_SUPPORT** is ``OFF``.
+
+**LIBOMP_STATS** = ``OFF|ON``
+  Include stats-gathering code.
+
+**LIBOMP_USE_DEBUGGER** = ``OFF|ON``
+  Include the friendly debugger interface.
+
+**LIBOMP_USE_HWLOC** = ``OFF|ON``
+  Use `OpenMPI's hwloc library <https://www.open-mpi.org/projects/hwloc/>`_ for
+  topology detection and affinity.
+
+**LIBOMP_HWLOC_INSTALL_DIR** = ``/path/to/hwloc/install/dir``
+  Specify install location of hwloc.  The configuration system will look for
+  ``hwloc.h`` in ``${LIBOMP_HWLOC_INSTALL_DIR}/include`` and the library in
+  ``${LIBOMP_HWLOC_INSTALL_DIR}/lib``.  The default is ``/usr/local``.
+  This option is only used if **LIBOMP_USE_HWLOC** is ``ON``.
+
+Additional Compiler Flags
+"""""""""""""""""""""""""
+
+These flags are **appended**, they do not overwrite any of the preset flags.
+
+**LIBOMP_CPPFLAGS** = <space-separated flags>
+  Additional C preprocessor flags.
+
+**LIBOMP_CFLAGS** = <space-separated flags>
+  Additional C compiler flags.
+
+**LIBOMP_CXXFLAGS** = <space-separated flags>
+  Additional C++ compiler flags.
+
+**LIBOMP_ASMFLAGS** = <space-separated flags>
+  Additional assembler flags.
+
+**LIBOMP_LDFLAGS** = <space-separated flags>
+  Additional linker flags.
+
+**LIBOMP_LIBFLAGS** = <space-separated flags>
+  Additional libraries to link.
+
+**LIBOMP_FFLAGS** = <space-separated flags>
+  Additional Fortran compiler flags.
+
+Options for ``libomptarget``
+----------------------------
+
+**LIBOMPTARGET_OPENMP_HEADER_FOLDER** = ``""``
+  Path of the folder that contains ``omp.h``.  This is required for testing
+  out-of-tree builds.
+
+**LIBOMPTARGET_OPENMP_HOST_RTL_FOLDER** = ``""``
+  Path of the folder that contains ``libomp.so``.  This is required for testing
+  out-of-tree builds.
+
+Example Usages of CMake
+=======================
+
+Typical Invocations
+-------------------
+
+.. code-block:: console
+
+  $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..
+  $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..
+  $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc ..
+
+Advanced Builds with Various Options
+------------------------------------
+
+- Build the i386 Linux library using GCC*
+
+  .. code-block:: console
+
+    $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=i386 ..
+
+- Build the x86_64 debug Mac library using Clang*
+
+  .. code-block:: console
+
+    $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLIBOMP_ARCH=x86_64 -DCMAKE_BUILD_TYPE=Debug ..
+
+- Build the library (architecture determined by probing compiler) using the
+  Intel(R) C Compiler and the Intel(R) C++ Compiler.  Also, create Fortran
+  modules with the Intel(R) Fortran Compiler.
+
+  .. code-block:: console
+
+    $ cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort -DLIBOMP_FORTRAN_MODULES=on ..
+
+- Have CMake find the C/C++ compiler and specify additional flags for the C
+  compiler, preprocessor, and C++ compiler.
+
+  .. code-blocks:: console
+
+    $ cmake -DLIBOMP_CFLAGS='-specific-flag' -DLIBOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBOMP_CXXFLAGS='--one-specific-flag --two-specific-flag' ..
+
+- Build the stubs library
+
+  .. code-blocks:: console
+
+    $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_LIB_TYPE=stubs ..
+
+**Footnotes**
+
+.. [*] Other names and brands may be claimed as the property of others.

libomptarget/Build_With_CMake.txt

-#
-#//===----------------------------------------------------------------------===//
-#//
-#//                     The LLVM Compiler Infrastructure
-#//
-#// This file is dual licensed under the MIT and the University of Illinois Open
-#// Source Licenses. See LICENSE.txt for details.
-#//
-#//===----------------------------------------------------------------------===//
-#
-
-=====================================================================
-How to Build the LLVM* OpenMP* Offloading Runtime Library using CMake
-=====================================================================
-
-==== Version of CMake required: v2.8.0 or above ====
- 
-============================================
-How to call cmake initially, then repeatedly
-============================================
-- When calling cmake for the first time, all needed compiler options
-  must be specified on the command line.  After this initial call to
-  cmake, the compiler definitions must not be included for further calls
-  to cmake.  Other options can be specified on the command line multiple
-  times including all definitions in the Build options section below.
-- Example of configuring, building, reconfiguring, rebuilding:
-  $ mkdir build
-  $ cd build
-  $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..  # Initial configuration
-  $ make
-  ...
-  $ make clean
-  $ cmake -DCMAKE_BUILD_TYPE=Debug ..                         # Second configuration
-  $ make
-  ...
-  $ rm -rf *
-  $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..  # Third configuration
-  $ make
-- Notice in the example how the compiler definitions are only specified
-  for an empty build directory, but other Build options are used at any time.
-- The file CMakeCache.txt which is created after the first call to cmake
-  is a configuration file which holds all the values for the Build options.
-  These configuration values can be changed using a text editor to modify 
-  CMakeCache.txt as opposed to using definitions on the command line.
-- To have cmake create a particular type of build generator file simply 
-  inlude the -G <Generator name> option:
-  $ cmake -G "Unix Makefiles" ...
-  You can see a list of generators cmake supports by executing cmake with
-  no arguments and a list will be printed.
-
-=====================
-Instructions to Build
-=====================
- $ cd openmp_top_level/ [ directory with runtime/, libomptarget/, etc. ]
- $ mkdir build
- $ cd build
-
- [ Unix* Libraries ]
- $ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> ..
-
- $ make
- $ make install
-
-===========
-Tests
-===========
-After the library has been built, there are optional tests that can be 
-performed.  Some will be skipped based upon the platform.
-To run the tests,
-$ make check-libomptarget
-
-=============
-CMake options
-=============
--DCMAKE_C_COMPILER=<C compiler name>
-Specify the C compiler
-
--DCMAKE_CXX_COMPILER=<C++ compiler name>
-Specify the C++ compiler
-
-==== First values listed are the default value ====
--DCMAKE_BUILD_TYPE=Release|Debug|RelWithDebInfo
-Build type can be Release, Debug, or RelWithDebInfo.
-
--DOPENMP_ENABLE_WERROR=true|false
-Should consider warnings as errors.
-
--DOPENMP_LLVM_LIT_EXECUTABLE=""
-Full path to the llvm-lit tool. Required for testing in out-of-tree builds.
-
--DOPENMP_FILECHECK_EXECUTABLE=""
-Full path to the FileCheck tool. Required for testing in out-of-tree builds.
-
--DLIBOMPTARGET_OPENMP_HEADER_FOLDER=""
-Path of the folder that contains omp.h. This is required for testing 
-out-of-tree builds.
-
--DLIBOMPTARGET_OPENMP_HOST_RTL_FOLDER=""
-Path of the folder that contains libomp.so. This is required for testing 
-out-of-tree builds.
-
-==== NVPTX device RTL specific ====
--DLIBOMPTARGET_NVPTX_ENABLE_BCLIB=false|true
-Enable CUDA LLVM bitcode offloading device RTL. This is used for
-link time optimization of the omp runtime and application code.
-
--DLIBOMPTARGET_NVPTX_CUDA_COMPILER=<CUDA compiler name>
-Location of a CUDA compiler capable of emitting LLVM bitcode.
-Currently only the Clang compiler is supported. This is only used
-when building the CUDA LLVM bitcode offloading device RTL. If
-unspecified, the default paths are inspected.
-
--DLIBOMPTARGET_NVPTX_BC_LINKER=<LLVM bitcode linker>
-Location of a linker capable of linking LLVM bitcode objects.
-This is only used when building the CUDA LLVM bitcode offloading
-device RTL. If unspecified, the default paths are inspected.
-
--DLIBOMPTARGET_NVPTX_ALTERNATE_HOST_COMPILER=""
-Host compiler to use with NVCC. This compiler is not going to be used to produce
-any binary. Instead, this is used to overcome the input compiler checks done by
-NVCC. E.g. if using a default host compiler that is not compatible with NVCC,
-this option can be use to pass to NVCC a valid compiler to avoid the error. 
-
--DLIBOMPTARGET_NVPTX_COMPUTE_CAPABILITY="35"
-Comma-separated list of CUDA compute capabilities that should be supported by
-the NVPTX device RTL. E.g. for compute capabilities 3.0 and 3.5, the option 
-"30,35" should be used.
-
-=======================
-Example usages of CMake
-=======================
----- Typical usage ----
-cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..
-cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..
-
----- Request an NVPTX runtime library that supports compute capability 5.0 ----
-cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLIBOMPTARGET_NVPTX_COMPUTE_CAPABILITY="50"
-
-=========
-Footnotes
-=========
-[*] Other names and brands may be claimed as the property of others.

libomptarget/README.txt

 
 $ cd where-you-want-to-live
 Check out openmp (libomptarget lives under ./libomptarget)
 $ cd where-you-want-to-live/openmp/libomptarget
 $ mkdir build && cd build
 $ cmake path/to/openmp -DCMAKE_C_COMPILER=<C compiler> -DCMAKE_CXX_COMPILER=<C++ compiler>
 $ make
 
-For details about building, please look at Build_With_CMake.txt
+For details about building, please look at README.rst in the parent directory.
 
 Architectures Supported
 =======================
-The current library has been only tested in Linux operating system and the 
-following host architectures: 
+The current library has been only tested in Linux operating system and the
+following host architectures:
 * Intel(R) 64 architecture
 * IBM(R) Power architecture (big endian)
 * IBM(R) Power architecture (little endian)
 * ARM(R) AArch64 architecture (little endian)
 
 The currently supported offloading device architectures are:
 * Intel(R) 64 architecture (generic 64-bit plugin - mostly for testing purposes)
 * IBM(R) Power architecture (big endian) (generic 64-bit plugin - mostly for testing purposes)

 (1) gcc version 4.8.2 or later is supported.
 (2) clang version 3.7 or later is supported.
 
 
 Front-end Compilers that work with this RTL
 ===========================================
 
 The following compilers are known to do compatible code generation for
-this RTL: 
+this RTL:
   - clang (from https://github.com/clang-ykt )
-  - clang (development branch at http://clang.llvm.org - several features still 
+  - clang (development branch at http://clang.llvm.org - several features still
     under development)
 
 -----------------------------------------------------------------------
 
 Notices
 =======
-This library and related compiler support is still under development, so the 
+This library and related compiler support is still under development, so the
 employed interface is likely to change in the future.
 
 *Other names and brands may be claimed as the property of others.
-

runtime/Build_With_CMake.txt

-#
-#//===----------------------------------------------------------------------===//
-#//
-#//                     The LLVM Compiler Infrastructure
-#//
-#// This file is dual licensed under the MIT and the University of Illinois Open
-#// Source Licenses. See LICENSE.txt for details.
-#//
-#//===----------------------------------------------------------------------===//
-#
-
-==========================================================
-How to Build the LLVM* OpenMP* Runtime Library using CMake
-==========================================================
-
-==== Version of CMake required: v2.8.0 or above ====
-
-============================================
-How to call cmake initially, then repeatedly
-============================================
-- When calling cmake for the first time, all needed compiler options
-  must be specified on the command line.  After this initial call to
-  cmake, the compiler definitions must not be included for further calls
-  to cmake.  Other options can be specified on the command line multiple
-  times including all definitions in the Build options section below.
-- Example of configuring, building, reconfiguring, rebuilding:
-  $ mkdir build
-  $ cd build
-  $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=i386 ..  # Initial configuration
-  $ make
-  ...
-  $ make clean
-  $ cmake -DLIBOMP_ARCH=x86_64 -DCMAKE_BUILD_TYPE=Debug ..                       # Second configuration
-  $ make
-  ...
-  $ rm -rf *
-  $ cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=x86_64 .. # Third configuration
-  $ make
-- Notice in the example how the compiler definitions are only specified
-  for an empty build directory, but other Build options are used at any time.
-- The file CMakeCache.txt which is created after the first call to cmake
-  is a configuration file which holds all the values for the Build options.
-  These configuration values can be changed using a text editor to modify
-  CMakeCache.txt as opposed to using definitions on the command line.
-- To have cmake create a particular type of build generator file simply
-  inlude the -G <Generator name> option:
-  $ cmake -G "Unix Makefiles" ...
-  You can see a list of generators cmake supports by executing cmake with
-  no arguments and a list will be printed.
-
-=====================
-Instructions to Build
-=====================
- $ cd openmp_top_level/ [ directory with runtime/, etc. ]
- $ mkdir build
- $ cd build
-
- [ Unix* Libraries ]
- $ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> ..
-
- [ Intel(R) Many Integrated Core Library (Intel(R) MIC Library) ]
- $ cmake -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> -DLIBOMP_ARCH=mic ..
-
- [ Windows Libraries ]
- $ cmake -G <Generator Type> -DCMAKE_C_COMPILER=<C Compiler> -DCMAKE_CXX_COMPILER=<C++ Compiler> -DCMAKE_ASM_MASM_COMPILER=[ml | ml64] -DCMAKE_BUILD_TYPE=Release ..
-
- $ make
- $ make install
-
-==================
-Mac* Fat Libraries
-==================
-On OS X* machines, it is possible to build universal (or fat) libraries which
-include both i386 and x86_64 architecture objects in a
-single archive.
- $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_OSX_ARCHITECTURES='i386;x86_64' ..
- $ make
-There is also an option -DLIBOMP_OSX_ARCHITECTURES which can be set in case
-this is an LLVM source tree build which will only set the libomp library
-to a universal fat library and prevent having the entire llvm/clang build
-produce universal binaries.
-
-===========
-Micro tests
-===========
-After the library has been built, there are five optional microtests that
-can be performed.  Some will be skipped based upon the platform.
-To run the tests,
-$ make libomp-micro-tests
-
-=============
-CMake options
-=============
--DCMAKE_C_COMPILER=<C compiler name>
-Specify the C compiler
-
--DCMAKE_CXX_COMPILER=<C++ compiler name>
-Specify the C++ compiler
-
--DCMAKE_Fortran_COMPILER=<Fortran compiler name>
-This option is only needed when -DLIBOMP_FORTRAN_MODULES is on.
-So typically, a Fortran compiler is not needed during the build.
-Specify the Fortran compiler
-
--DCMAKE_ASM_MASM_COMPILER=[ml | ml64 ]
-This option is Windows* Only
-
--DLIBOMP_ARCH=i386|x86_64|arm|ppc64|ppc64le|aarch64|mic
-The default for the option is chosen based on the probing the compiler for
-architecture macros (e.g., is __x86_64__ predefined by compiler?).
-
-==== First values listed are the default value ====
--DLIBOMP_LIB_TYPE=normal|profile|stubs
-Library type can be normal, profile, or stubs.
-
--DCMAKE_BUILD_TYPE=Release|Debug|RelWithDebInfo
-Build type can be Release, Debug, or RelWithDebInfo.
-
--DLIBOMP_OMP_VERSION=50|45|40|30
-OpenMP version can be either 50, 45, 40 or 30.
-
--DLIBOMP_MIC_ARCH=knc|knf
-This value is ignored if LIBOMP_ARCH != mic
-Intel(R) MIC Architecture, can be knf or knc.
-
--DLIBOMP_FORTRAN_MODULES=off|on
-Should the Fortran modules be created (requires Fortran compiler)
-
--DLIBOMP_USE_ADAPTIVE_LOCKS=on|off
-Should adaptive (Intel(R) Transactional Synchronization Extensions
-(Intel(R) TSX) based) locks be included?  These are x86 specific.
-This feature is turned on by default for IA-32 architecture and
-Intel(R) 64 architecture.  Otherwise, it is turned off.
-
--DLIBOMP_USE_INTERNODE_ALIGNMENT=off|on
-Should 4096-byte alignment be used for certain data structures?
-This option is useful on multinode systems where a small CACHE_LINE
-setting leads to false sharing.  This option is off by default.
-
--DLIBOMP_USE_VERSION_SYMBOLS=on|off
-Should versioned symbols be used for building the library?
-This option only makes sense for ELF based libraries where version
-symbols are supported (Linux, some BSD* variants).  It is off
-by default for Windows and Mac, but on for other Unix based operating
-systems.
-
--DLIBOMP_ENABLE_SHARED=on|off
-Shared library instead of static library? (Note: static libraries are not
-supported on Windows). If LIBOMP_ENABLE_SHARED is off, then static OpenMP
-libraries will be built instead of dynamic ones.
-
--DLIBOMP_OMPT_SUPPORT=off|on
-Should OMPT support be included in the build?
-
--DLIBOMP_OMPT_OPTIONAL=on|off
-Should optional OMPT functionality be included in the build?
-Will be ignored if LIBOMP_OMPT_SUPPORT is off.
-
--DLIBOMP_STATS=off|on
-Should include stats-gathering code be included in the build?
-
--DLIBOMP_USE_DEBUGGER=off|on
-Should the friendly debugger interface be included in the build?
-
--DLIBOMP_USE_HWLOC=off|on
-Should the Hwloc library be used for affinity?
-This option is not supported on Windows.
-http://www.open-mpi.org/projects/hwloc
-
--DLIBOMP_HWLOC_INSTALL_DIR=/path/to/hwloc/install/dir
-Default: /usr/local
-This option is only used if LIBOMP_USE_HWLOC is on.
-Specifies install location of Hwloc. The configuration system will look for
-hwloc.h in ${LIBOMP_HWLOC_INSTALL_DIR}/include and the library in
-${LIBOMP_HWLOC_INSTALL_DIR}/lib.
-
--DOPENMP_LLVM_LIT_EXECUTABLE=/path/to/llvm-lit
-Default: search in PATH
-Specifiy full path to llvm-lit executable for running tests.
-
--DOPENMP_LLVM_TOOLS_DIR=/path/to/built/llvm/tools
-Default: search for tools in path
-Additional path to search for LLVM tools needed by tests.
-
-================================
-How to append flags to the build
-================================
-- These flags are *appended*.  They do not
-  overwrite any of the preset flags.
--DLIBOMP_CPPFLAGS=<space-separated flags> -- Additional C preprocessor flags
--DLIBOMP_CFLAGS=<space-separated flags>   -- Additional C compiler flags
--DLIBOMP_CXXFLAGS=<space-separated flags> -- Additional C++ compiler flags
--DLIBOMP_ASMFLAGS=<space-separated flags> -- Additional assembly flags
--DLIBOMP_LDFLAGS=<space-separated flags>  -- Additional linker flags
--DLIBOMP_LIBFLAGS=<space-separated flags> -- Additional libraries to link
--DLIBOMP_FFLAGS=<space-separated flags>   -- Additional Fortran compiler flags
-
-=======================
-Example usages of CMake
-=======================
----- Typical usage ----
-cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc ..
-cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..
-cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..
-
----- With Various Options ----
-- Build the i386 Linux library using GCC*
-cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_ARCH=i386 ..
-
-- Build the x86_64 debug Mac library using Clang*
-cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLIBOMP_ARCH=x86_64 -DCMAKE_BUILD_TYPE=Debug ..
-
-- Build the library (architecture determined by probing compiler) using the
-  Intel(R) C Compiler and the Intel(R) C++ Compiler. Also, create the fortran modules using
-  the Intel(R) Fortran Compiler.
-cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort -DLIBOMP_FORTRAN_MODULES=on ..
-
-- Have CMake Find the C/C++ compiler, and specify additional flags for the C compiler, preprocessor, and C++ compiler.
-cmake -DLIBOMP_CFLAGS='-specific-flag' -DLIBOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBOMP_CXXFLAGS='--one-specific-flag --two-specific-flag' ..
-
----- Build the stubs library ----
-cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLIBOMP_LIB_TYPE=stubs ..
-
-=========
-Footnotes
-=========
-[*] Other names and brands may be claimed as the property of others.

runtime/README.txt

 
 $ cd where-you-want-to-live
 Check out openmp
 $ cd where-you-want-to-live/openmp/runtime
 $ mkdir build && cd build
 $ cmake path/to/openmp -DCMAKE_C_COMPILER=<C compiler> -DCMAKE_CXX_COMPILER=<C++ compiler>
 $ make
 
-For details about building, please look at Build_With_CMake.txt
+For details about building, please look at README.rst in the parent directory.
 
 Architectures Supported
 =======================
 * IA-32 architecture
 * Intel(R) 64 architecture
 * Intel(R) Many Integrated Core Architecture
 * ARM* architecture
 * Aarch64 (64-bit ARM) architecture

runtime/doc/doxygen/libomp_interface.h

 
 The overall design is described, and each function in the interface
 has its own description. (At least, that's the ambition, we may not be there yet).
 
 @section sec_building Quickly Building the Runtime
 For the impatient, we cover building the runtime as the first topic here.
 
 CMake is used to build the OpenMP runtime.  For details and a full list of options for the CMake build system,
-see <tt>Build_With_CMake.txt</tt> inside the <tt>runtime/</tt> subdirectory.  These
-instructions will provide the most typical build.
+see <tt>README.rst</tt> in the source code repository.  These instructions will provide the most typical build.
 
 In-LLVM-tree build:.
 @code
 $ cd where-you-want-to-live
 Check out openmp into llvm/projects
 $ cd where-you-want-to-build
 $ mkdir build && cd build
 $ cmake path/to/llvm -DCMAKE_C_COMPILER=<C compiler> -DCMAKE_CXX_COMPILER=<C++ compiler>
 $ make omp
 @endcode
 Out-of-LLVM-tree build:
 @code
 $ cd where-you-want-to-live
 Check out openmp
-$ cd where-you-want-to-live/openmp/runtime
+$ cd where-you-want-to-live/openmp
 $ mkdir build && cd build
 $ cmake path/to/openmp -DCMAKE_C_COMPILER=<C compiler> -DCMAKE_CXX_COMPILER=<C++ compiler>
 $ make
 @endcode
 
 @section sec_supported Supported RTL Build Configurations
 
 The architectures supported are IA-32 architecture, Intel&reg;&nbsp; 64, and

www/README.txt

 
 $ cd where-you-want-to-live
 Check out openmp
 $ cd where-you-want-to-live/openmp
 $ mkdir build && cd build
 $ cmake path/to/openmp -DCMAKE_C_COMPILER=<C compiler> -DCMAKE_CXX_COMPILER=<C++ compiler>
 $ make
 
-For details about building, please look at Build_With_CMake.txt
+For details about building, please look at README.rst.
 
 Architectures Supported
 =======================
 * IA-32 architecture
 * Intel(R) 64 architecture
 * Intel(R) Many Integrated Core Architecture
 * ARM* architecture
 * Aarch64 (64-bit ARM) architecture

www/index.html

<ul>
     <li>Check out openmp</li>
     <li><code>cd where-you-want-to-live/openmp</code></li>
     <li><code>mkdir build &amp;&amp; cd build</code></li>
     <li><code>cmake path/to/openmp -DCMAKE_C_COMPILER=&lt;C compiler&gt; -DCMAKE_CXX_COMPILER=&lt;C++ compiler&gt;</code></li>
     <li><code>make</code></li>
   </ul>
 
   <p>Full details of how to build are in the
-    <a href="README.txt">README.txt</a> and Build_With_CMake.txt (inside the runtime/ subdirectory)
+    <a href="README.txt">README.txt</a> and README.rst in the source code repository.
   </p>
 
   <!--=====================================================================-->
   <h3>Notes</h3>
   <!--=====================================================================-->
 
 <p>