Unify build documentation and convert to reStructuredText

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.

Differential Revision: https://reviews.llvm.org/D40920

llvm-svn: 321481

3 files changed, 3 insertions, 231 deletions

diff --git a/openmp/runtime/Build_With_CMake.txt b/openmp/runtime/Build_With_CMake.txt
deleted file mode 100644
index 8522a8eb201..00000000000
--- a/openmp/runtime/Build_With_CMake.txt
+++ /dev/null
@@ -1,227 +0,0 @@
-#
-#//===----------------------------------------------------------------------===//
-#//
-#//                     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.
diff --git a/openmp/runtime/README.txt b/openmp/runtime/README.txt
index 62e01b2560c..ab1963416a7 100644
--- a/openmp/runtime/README.txt
+++ b/openmp/runtime/README.txt
@@ -41,7 +41,7 @@ $ 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
 =======================
diff --git a/openmp/runtime/doc/doxygen/libomp_interface.h b/openmp/runtime/doc/doxygen/libomp_interface.h
index fc92d19f202..7ff28020851 100644
--- a/openmp/runtime/doc/doxygen/libomp_interface.h
+++ b/openmp/runtime/doc/doxygen/libomp_interface.h
@@ -30,8 +30,7 @@ has its own description. (At least, that's the ambition, we may not be there yet
 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
@@ -46,7 +45,7 @@ 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