Update README.txt files and Build_With_CMake.txt

[jlpeyton]

Summary

Updates documentation to include all possible architecture builds, synchronizes runtime/README.txt and www/README.txt, updates the building-with-CMake documentation. This change also changes references of Intel(R) OpenMP Library to LLVM OpenMP Library.

[hfinkel]

LGTM.

runtime/Build_With_CMake.txt

176

We'll need to change these when we re-name the library; but these are fine for today.

[jlpeyton]

Committed new revision: 237124

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.
 #//
 #//===----------------------------------------------------------------------===//
 #
 
-               Building libiomp5 using CMake
-               =============================
+         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

 ================
 -DCMAKE_C_COMPILER=<C compiler name>
 -DCMAKE_CXX_COMPILER=<C++ compiler name>
 
 -DCMAKE_Fortran_COMPILER=<Fortran compiler name>
 Unix* systems (Optional as compiler is default):
 This option is only needed when -Dcreate_fortran_modules is true
 
--DCMAKE_ASM_COMPILER=<Assembler name>
-This option isn't usually needed for Non-Windows* builds
-
 -DCMAKE_ASM_MASM_COMPILER=[ml | ml64 ]
 This option is Windows* Only
 
 =============
 Build options
 =============
 
 ==========================
 ==== Operating System ====
 ==========================
 -Dos=lin|mac|win
 * Operating system can be lin (Linux*), mac (Mac*), or win (Windows*). 
   If not specified, cmake will try to determine your current operating system.
 
 ======================
 ==== Architecture ====
 ======================
--Darch=32|32e|arm|ppc64|aarch64|mic
+-Darch=32|32e|arm|ppc64|ppc64le|aarch64|mic
 * Architecture can be 32 (IA-32 architecture), 32e (Intel(R) 64 architecture),
-  arm (ARM architecture), aarch64 (ARMv8 architecture) or ppc64 (PPC64 architecture).
-  This option, by default is chosen based on the
-  CMake variable CMAKE_SIZEOF_VOID_P.  If it is 8, then Intel(R) 64 architecture
-  is assumed.  If it is 4, then IA-32 architecture is assumed.  If you want to
-  use a different architecture other than x86 based architecture, you must specify
-  it when calling cmake initially using this -Darch=<arch> option or by changing 
-  the arch value via CMakeCache.txt or the CMake GUI after the initial CMake run.
+  arm (ARM architecture), aarch64 (ARMv8 architecture), ppc64 (PPC64 architecture),
+  or ppc64le (little endian PPC64 architecture).
+* This option, by default 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 ----
 -Dlib_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.
 See below for interaction when -DUSE_BUILDPL_RULES is on.

 This value is ignored if os != mic
   
 -Dcreate_fortran_modules=off|on
 Should the Fortran modules be created (requires Fortran compiler)
 
 -Dstats=off|on
 Should include stats-gathering code?
 
+-Dompt_support=off|on
+Should OMPT support be turned on?
+If ompt_support is off, then both ompt_blame and ompt_trace are ignored.
+
+-Dompt_blame=on|off
+should OMPT blame functionality be turned on?
+
+-Dompt_trace=on|off
+should OMPT trace functionality be turned on?
+
 =====================
 ==== Micro tests ====
 =====================
-After the library has been built, five microtests are performed.
-Some will be skipped based upon the platform.
+After the library has been built, there are five optional microtests that
+can be performed.  Some will be skipped based upon the platform.
 These tests can be turned on (default) or off with the following options:
 -Dtest_touch=on|off     -- Should the touch test be done?
 -Dtest_relo=on|off      -- Should the position independent code test be done?
 -Dtest_execstack=on|off -- Should the stack be checked for executability?
--Dtest_instr=on|off     -- Should the Intel(R) MIC Libraries be checked 
+-Dtest_instr=on|off     -- Should the Intel(R) MIC Libraries be checked
                             for correct instruction set?
 -Dtest_deps=on|off      -- Should libiomp5's dependencies be checked?
 -Dtests=off|on          -- Should any of the above tests be done?
+If -Dtests=on is specified, the user can then call:
+$ make libiomp-micro-tests
+which runs the tests.
 
 ============================================
 ==== How to append flags to compilation ====
 ============================================
 - These flags are *appended*.  They do not 
   overwrite any of the preset flags.
--DUSER_CPP_FLAGS=<space-separated flags>    -- Additional C Preprocessor flags
+-DLIBIOMP_CPPFLAGS=<space-separated flags>    -- Additional C Preprocessor flags
                                                (typically additional -Ddef=val flags)
--DUSER_C_FLAGS=<space-separated flags>      -- Additional C compiler flags
--DUSER_CXX_FLAGS=<space-separated flags>    -- Additional C++ compiler flags
--DUSER_ASM_FLAGS=<space-separated flags>    -- Additional assembly flags
--DUSER_LD_FLAGS=<space-separated flags>     -- Additional linker flags
--DUSER_LD_LIB_FLAGS=<space-separated flags> -- Additional libraries to link 
+-DLIBIOMP_CFLAGS=<space-separated flags>      -- Additional C compiler flags
+-DLIBIOMP_CXXFLAGS=<space-separated flags>    -- Additional C++ compiler flags
+-DLIBIOMP_ASMFLAGS=<space-separated flags>    -- Additional assembly flags
+-DLIBIOMP_LDFLAGS=<space-separated flags>     -- Additional linker flags
+-DLIBIOMP_LIBFLAGS=<space-separated flags> -- Additional libraries to link 
                                                to during link phase
--DUSER_F_FLAGS=<space-separated flags>  -- Additional Fortran compiler flags
+-DLIBIOMP_FFLAGS=<space-separated flags>  -- Additional Fortran compiler flags
 
 ===================================
 ==== Feature Based Compilation ====
 ===================================
 -DUSE_BUILDPL_RULES=false|true
 Should the build imitate build.pl's build process.
 When this is true, the Unix* Release builds will build libiomp5
 with -O2 and -g flags activated (same as RelWithDebInfo). Then,

 Examples 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 32 bit Linux library using GCC*
 cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -Dos=lin -Darch=32 ..
+
+- Build the 32 bit debug Mac library using Clang*
 cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -Dos=mac -Darch=32 -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, enabling the libiomp-micro-tests target and using similar rules that build.pl 
+  would use to build the library.
 cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort -Dtests=on -Dcreate_fortran_modules=on -DUSE_BUILDPL_RULES=on ..
-cmake -DUSER_CFLAGS='Werror' -DUSER_CPP_FLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DUSER_CXX_FLAGS='-Werror -Wsign-compare' ..
 
----- Stubs library ----
+- Have CMake Find the C/C++ compiler, and specify additional flags for the C compiler, preprocessor, and C++ compiler.
+cmake -DLIBIOMP_CFLAGS='Werror' -DLIBIOMP_CPPFLAGS='-DNEW_FEATURE=1 -DOLD_FEATURE=0' -DLIBIOMP_CXXFLAGS='-Werror -Wsign-compare' ..
+
+---- Build the stubs library ----
 cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -Dlib_type=stubs ..
 
 =========
 Footnotes
 =========
 [*] Other names and brands may be claimed as the property of others.

runtime/README.txt

 
-               README for Intel(R) OpenMP* Runtime Library
-               ===========================================
+               README for the LLVM* OpenMP* Runtime Library
+               ============================================
 
 How to Build Documentation
 ==========================
 
 The main documentation is in Doxygen* format, and this distribution
 should come with pre-built PDF documentation in doc/Reference.pdf.  
 However, an HTML version can be built by executing:
 
 % doxygen doc/doxygen/config 
 
-in this directory.
+in the runtime directory.
 
 That will produce HTML documentation in the doc/doxygen/generated
 directory, which can be accessed by pointing a web browser at the
 index.html file there.
 
 If you don't have Doxygen installed, you can download it from
 www.doxygen.org.
 
 
-How to Build the Intel(R) OpenMP* Runtime Library
-=================================================
+How to Build the LLVM* OpenMP* Runtime Library
+==============================================
+
+The library can be built either using Cmake, or using a makefile that
+in turn invokes various Perl scripts. For porting, non X86
+architectures, and for those already familiar with Cmake that may be
+an easier route to take than the one described here.
+
+Building with CMake
+===================
+The runtime/Build_With_CMake.txt file has a description of how to
+build with Cmake.
 
+Building with the Makefile
+==========================
 The Makefile at the top-level will attempt to detect what it needs to
-build the Intel(R) OpenMP* Runtime Library.  To see the default settings, 
+build the LLVM* OpenMP* Runtime Library.  To see the default settings, 
 type:
 
 make info
 
 You can change the Makefile's behavior with the following options:
 
 omp_root:    The path to the top-level directory containing the top-level
        Makefile.  By default, this will take on the value of the 
        current working directory.
 
 omp_os:      Operating system.  By default, the build will attempt to 
-       detect this. Currently supports "linux", "freebsd", "macos", and 
+       detect this. Currently supports "linux", "freebsd", "macos", and
        "windows".
 
 arch:        Architecture. By default, the build will attempt to 
        detect this if not specified by the user. Currently 
        supported values are
                  "32" for IA-32 architecture 
                  "32e" for Intel(R) 64 architecture
                  "mic" for Intel(R) Many Integrated Core Architecture
+                 "arm" for ARM* architecture
+                 "aarch64" for Aarch64 (64-bit ARM) architecture
                  "ppc64" for IBM(R) Power architecture (big endian)
                  "ppc64le" for IBM(R) Power architecture (little endian)
 
              If "mic" is specified then "icc" will be used as the
        compiler, and appropriate k1om binutils will be used. The
        necessary packages must be installed on the build machine
        for this to be possible (but an Intel(R) Xeon Phi(TM)
        coprocessor card is not required to build the library).
jobs:        The number of parallel jobs for the underlying call to make.
          This value is sent as the parameter to the -j flag for make.
          This value defaults to "1", but can be set to any positive integer.
 
 To use any of the options above, simple add <option_name>=<value>.  For 
 example, if you want to build with gcc instead of icc, type:
 
 make compiler=gcc
 
-There is also an experimental CMake build system. This is *not* yet
-supported for production use and resulting binaries have not been checked
-for compatibility.
-
 On OS X* machines, it is possible to build universal (or fat) libraries which
 include both IA-32 architecture and Intel(R) 64 architecture objects in a
 single archive; just build the 32 and 32e libraries separately, then invoke 
 make again with a special argument as follows:
 
 make compiler=clang build_args=fat
 
 Supported RTL Build Configurations
(7) Clang* currently does not offer a software-implemented 128 bit extended
     __kmpc_atomic_float16_*
     __kmpc_atomic_*_fp
 (8) Community contribution provided AS IS, not tested by Intel.
 
 Front-end Compilers that work with this RTL
 ===========================================
 
 The following compilers are known to do compatible code generation for
-this RTL:  icc/icl, gcc.  See the documentation for more detail.
+this RTL: clang (from the OpenMP development branch at
+http://clang-omp.github.io/ ), Intel compilers, GCC.  See the documentation
+for more details.
 
 -----------------------------------------------------------------------
 
 Notices
 =======
 
 *Other names and brands may be claimed as the property of others.

www/README.txt

omp_os:      Operating system.  By default, the build will attempt to
        "windows".
 
 arch:        Architecture. By default, the build will attempt to 
        detect this if not specified by the user. Currently 
        supported values are
                  "32" for IA-32 architecture 
                  "32e" for Intel(R) 64 architecture
                  "mic" for Intel(R) Many Integrated Core Architecture
+                 "arm" for ARM* architecture
+                 "aarch64" for Aarch64 (64-bit ARM) architecture
+                 "ppc64" for IBM(R) Power architecture (big endian)
+                 "ppc64le" for IBM(R) Power architecture (little endian)
 
              If "mic" is specified then "icc" will be used as the
        compiler, and appropriate k1om binutils will be used. The
        necessary packages must be installed on the build machine
        for this to be possible (but an Intel(R) Xeon Phi(TM)
        coprocessor card is not required to build the library).
 
 compiler:    Which compiler to use for the build.  Defaults to "icc" 
        or "icl" depending on the value of omp_os. Also supports 
        some versions of "gcc"* when omp_os is "linux". The selected 
        compiler should be installed and in the user's path. The 
        corresponding Fortran compiler should also be in the path. 
        See "Supported RTL Build Configurations" below for more 
        information on compiler versions.
 
 mode:        Library mode: default is "release".  Also supports "debug".
 
+jobs:        The number of parallel jobs for the underlying call to make.
+         This value is sent as the parameter to the -j flag for make.
+         This value defaults to "1", but can be set to any positive integer.
+
 To use any of the options above, simple add <option_name>=<value>.  For 
 example, if you want to build with gcc instead of icc, type:
 
 make compiler=gcc
 
 On OS X* machines, it is possible to build universal (or fat) libraries which
 include both IA-32 architecture and Intel(R) 64 architecture objects in a
 single archive; just build the 32 and 32e libraries separately, then invoke