[ci] added tests with Clang/AppleClang compilation at Travis (#1522)

* added clang test

* hotfix

* downgrade required AppleCLang version

* fixed CMakeLists

* prevent case when CMake is downgraded by libomp

* fixed Clang test

* moved MSVC version check to the better place

* compile with Clang at Travis on Linux

* clear .travis.yml

* fixed indents

* added support of MPI test at Travis with macOS

* added FAQ entry about OpenMP library error

* updated installation guide

* moved APPLE_OUTPUT_DYLIB to other options

* fix check-docs test: ignore old url from error message

* added example of symlink command in FAQ

* fixed markdown

* capitalized heading

* updated Python installation guide

* changed mode in message command

* added notes about MinGW efficiency problems

* updated R-package installation guide

* use quotes for gcc version

* removed excess 'Note' phrase

.travis.yml

@@ -5,18 +5,17 @@ dist: trusty
 git:
   submodules: true
 
-compiler:
-  - gcc
-
 os:
   - linux
   - osx
 
 env:
-  global:
+  global:  # default values
+    - COMPILER=gcc
     - PYTHON_VERSION=3.6
   matrix:
     - TASK=regular
+    - TASK=regular COMPILER=clang
     - TASK=mpi PYTHON_VERSION=2.7
     - TASK=pylint
     - TASK=check-docs
@@ -46,6 +45,7 @@ before_install:
   - export LGB_VER=$(head -n 1 VERSION.txt)
   - export AMDAPPSDK=$HOME/AMDAPPSDK
   - export LD_LIBRARY_PATH="$AMDAPPSDK/lib/x86_64:$LD_LIBRARY_PATH"
+  - export LD_LIBRARY_PATH="/usr/local/clang/lib:$LD_LIBRARY_PATH"  # fix error "libomp.so: cannot open shared object file: No such file or directory" on Linux with Clang
   - export OPENCL_VENDOR_PATH=$AMDAPPSDK/etc/OpenCL/vendors
 
 install:

.travis/setup.sh

 #!/bin/bash
 
 if [[ $TRAVIS_OS_NAME == "osx" ]]; then
+    if  [[ $COMPILER == "clang" ]]; then
+        brew install libomp
+        brew reinstall cmake  # CMake >=3.12 is needed to find OpenMP at macOS
+    else
         sudo softwareupdate -i "Command Line Tools (macOS High Sierra version 10.13) for Xcode-9.3"  # fix "fatal error: _stdio.h: No such file or directory"
         rm '/usr/local/include/c++'
 #        brew cask uninstall oclint  #  reserve variant to deal with conflict link
-    if [[ $TASK == "mpi" ]]; then
-        brew install open-mpi
-    else
+        if [[ $TASK != "mpi" ]]; then
             brew install gcc
         fi
 #        brew link --overwrite gcc  # previous variant to deal with conflict link
+    fi
+    if [[ $TASK == "mpi" ]]; then
+        brew install open-mpi
+    fi
     wget -O conda.sh https://repo.continuum.io/miniconda/Miniconda${PYTHON_VERSION:0:1}-latest-MacOSX-x86_64.sh
-else
+else  # Linux
     if [[ $TASK == "mpi" ]]; then
         sudo apt-get install -y libopenmpi-dev openmpi-bin
     fi

.travis/test.sh

 #!/bin/bash
 
-if [[ $TRAVIS_OS_NAME == "osx" ]]; then
+if [[ $TRAVIS_OS_NAME == "osx" ]] && [[ $COMPILER == "gcc" ]]; then
     export CXX=g++-8
     export CC=gcc-8
+elif [[ $TRAVIS_OS_NAME == "linux" ]] && [[ $COMPILER == "clang" ]]; then
+    export CXX=clang++
+    export CC=clang
 fi
 
 conda create -q -n test-env python=$PYTHON_VERSION
@@ -26,7 +29,7 @@ if [[ $TASK == "check-docs" ]]; then
     find ./_build/html/ -type f -name '*.html' -exec \
     sed -i'.bak' -e 's;\(\.\/[^.]*\.\)rst\([^[:space:]]*\);\1html\2;g' {} \;  # emulate js function
 #    html5validator --root ./_build/html/ || exit -1
-    if [[ $TRAVIS_OS_NAME != "osx" ]]; then
+    if [[ $TRAVIS_OS_NAME == "linux" ]]; then
         sudo apt-get install linkchecker
         linkchecker --config=.linkcheckerrc ./_build/html/*.html || exit -1
     fi
@@ -56,6 +59,10 @@ fi
 
 conda install numpy nose scipy scikit-learn pandas matplotlib python-graphviz pytest
 
+if [[ $TRAVIS_OS_NAME == "osx" ]] && [[ $COMPILER == "clang" ]]; then
+    ln -sf `ls -d "$(brew --cellar libomp)"/*/lib`/* $CONDA_PREFIX/lib || exit -1  # fix "OMP: Error #15: Initializing libiomp5.dylib, but found libomp.dylib already initialized." (OpenMP library conflict due to conda's MKL)
+fi
+
 if [[ $TASK == "sdist" ]]; then
     cd $TRAVIS_BUILD_DIR/python-package && python setup.py sdist || exit -1
     pip install $TRAVIS_BUILD_DIR/python-package/dist/lightgbm-$LGB_VER.tar.gz -v || exit -1

CMakeLists.txt

-if(CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
-  cmake_minimum_required(VERSION 3.12)
-elseif(MSVC)
-  cmake_minimum_required(VERSION 3.8)
-elseif(USE_GPU OR APPLE)
+if(USE_GPU OR APPLE)
   cmake_minimum_required(VERSION 3.2)
 else()
   cmake_minimum_required(VERSION 2.8)
@@ -17,6 +13,10 @@ OPTION(USE_SWIG "Enable SWIG to generate Java API" OFF)
 OPTION(USE_HDFS "Enable HDFS support (EXPERIMENTAL)" OFF)
 OPTION(USE_R35 "Set to ON if your R version is not smaller than 3.5" OFF)
 
+if(APPLE)
+    OPTION(APPLE_OUTPUT_DYLIB "Output dylib shared library" OFF)
+endif()
+
 if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
   if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "4.8.2")
     message(FATAL_ERROR "Insufficient gcc version")
@@ -25,10 +25,16 @@ elseif(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
   if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "3.8")
     message(FATAL_ERROR "Insufficient Clang version")
   endif()
-endif()
-
-if(APPLE)
-    OPTION(APPLE_OUTPUT_DYLIB "Output dylib shared library" OFF)
+elseif(CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
+  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "8.1.0")
+    message(FATAL_ERROR "Insufficient AppleClang version")
+  endif()
+  cmake_minimum_required(VERSION 3.12)
+elseif(MSVC)
+  if(MSVC_VERSION LESS 1900)
+    message(FATAL_ERROR "The compiler ${CMAKE_CXX_COMPILER} doesn't support required C++11 features. Please use a newer MSVC.")
+  endif()
+  cmake_minimum_required(VERSION 3.8)
 endif()
 
 if(USE_SWIG)
@@ -86,7 +92,7 @@ if(USE_GPU)
     find_package(Boost 1.56.0 COMPONENTS filesystem system REQUIRED)
     if (WIN32)
         # disable autolinking in boost
-        add_definitions( -DBOOST_ALL_NO_LIB )
+        add_definitions(-DBOOST_ALL_NO_LIB)
     endif()
     include_directories(${Boost_INCLUDE_DIRS})
     ADD_DEFINITIONS(-DUSE_GPU)
@@ -110,10 +116,6 @@ if(WIN32 AND MINGW)
 endif()
 
 if(MSVC)
-    if(MSVC_VERSION LESS 1900)
-        message(STATUS "The compiler ${CMAKE_CXX_COMPILER} has no C++11 support. Please use a newer MSVC.")
-    endif()
-
     SET(variables
         CMAKE_C_FLAGS_DEBUG
         CMAKE_C_FLAGS_MINSIZEREL
@@ -135,10 +137,10 @@ SET(LightGBM_HEADER_DIR ${PROJECT_SOURCE_DIR}/include)
 SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_SOURCE_DIR})
 SET(LIBRARY_OUTPUT_PATH ${PROJECT_SOURCE_DIR})
 
-include_directories (${LightGBM_HEADER_DIR})
+include_directories(${LightGBM_HEADER_DIR})
 
 if(APPLE)
-  if (APPLE_OUTPUT_DYLIB)
+  if(APPLE_OUTPUT_DYLIB)
     SET(CMAKE_SHARED_LIBRARY_SUFFIX ".dylib")
   else()
     SET(CMAKE_SHARED_LIBRARY_SUFFIX ".so")

R-package/README.md

@@ -24,7 +24,7 @@ For users who wants to install online with GPU or want to choose a specific comp
 
 #### macOS Preparation
 
-gcc with OpenMP support must be installed first. Refer to [Installation-Guide](https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#macos) for installing gcc with OpenMP support.
+You can perform installation either with **Apple Clang** or **gcc**. In case you prefer **Apple Clang**, you should install **OpenMP** (details for installation can be found in [Installation Guide](https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#apple-clang)) first and **CMake** version 3.12 or higher is required. In case you prefer **gcc**, you need to install it (details for installation can be found in [Installation Guide](https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc)) and specify compilers by running ``export CXX=g++-7 CC=gcc-7`` (replace "7" with version of **gcc** installed on your machine) first.
 
 ### Install
 
@@ -33,7 +33,7 @@ Install LightGBM R-package with the following command:
 ```sh
 git clone --recursive https://github.com/Microsoft/LightGBM
 cd LightGBM/R-package
-# export CXX=g++-7 CC=gcc-7  # for macOS (replace 7 with version of gcc installed on your machine)
+# export CXX=g++-7 CC=gcc-7  # macOS users, if you decided to compile with gcc, don't forget to specify compilers (replace "7" with version of gcc installed on your machine)
 R CMD INSTALL --build . --no-multiarch
 ```
 
@@ -43,7 +43,7 @@ Or build a self-contained R-package which can be installed afterwards:
 git clone --recursive https://github.com/Microsoft/LightGBM
 cd LightGBM/R-package
 Rscript build_package.R
-# export CXX=g++-7 CC=gcc-7  # for macOS (replace 7 with version of gcc installed on your machine)
+# export CXX=g++-7 CC=gcc-7  # macOS users, if you decided to compile with gcc, don't forget to specify compilers (replace "7" with version of gcc installed on your machine)
 R CMD INSTALL lightgbm_2.1.1.tar.gz --no-multiarch
 ``` 
 

README.md

@@ -52,7 +52,7 @@ News
 More detailed update logs : [Key Events](https://github.com/Microsoft/LightGBM/blob/master/docs/Key-Events.md).
 
 
-External (unofficial) Repositories
+External (Unofficial) Repositories
 ----------------------------------
 
 Julia-package: https://github.com/Allardvm/LightGBM.jl

docs/.linkcheckerrc

@@ -4,7 +4,9 @@ anchors=1
 sslverify=0
 
 [filtering]
-ignore=public.tableau.com
+ignore=
+  public.tableau.com
+  http://www.intel.com/software/products/support
 ignorewarnings=http-robots-denied,https-certificate-error
 
 [output]

docs/FAQ.rst

@@ -123,6 +123,29 @@ LightGBM
 
 --------------
 
+-  **Question 10**: LightGBM crashes randomly with the error like this.
+
+   ::
+
+       OMP: Error #15: Initializing libiomp5.dylib, but found libomp.dylib already initialized.
+       OMP: Hint: This means that multiple copies of the OpenMP runtime have been linked into the program. That is dangerous, since it can degrade performance or cause incorrect results. The best thing to do is to ensure that only a single OpenMP runtime is linked into the process, e.g. by avoiding static linking of the OpenMP runtime in any library. As an unsafe, unsupported, undocumented workaround you can set the environment variable KMP_DUPLICATE_LIB_OK=TRUE to allow the program to continue to execute, but that may cause crashes or silently produce incorrect results. For more information, please see http://www.intel.com/software/products/support/.
+
+-  **Solution 10**: File extensions in the error message may differ depending on the operating system.
+   This error means that you have multiple OpenMP libraries installed on your machine and they conflict with each other.
+
+   If you are using Python distributed by Conda, then it is highly likely that the error is caused by the ``numpy`` package from Conda which includes the ``mkl`` package which in turn conflicts with the system-wide library.
+   In this case you can update the ``numpy`` package in Conda or replace the Conda's OpenMP library instance with system-wide one by creating a symlink to it in Conda environment folder ``$CONDA_PREFIX/lib``.
+
+   Assuming you are using macOS with Homebrew, the command which overwrites OpenMP library files in the current active Conda environment with symlinks to the system-wide library ones installed by Homebrew:
+
+   ::
+
+       ln -sf `ls -d "$(brew --cellar libomp)"/*/lib`/* $CONDA_PREFIX/lib
+
+   If this is not your case, then you should find conflicting OpenMP library installations on your own and leave only one of them.
+
+--------------
+
 R-package
 ~~~~~~~~~
 

docs/Installation-Guide.rst

 Installation Guide
 ==================
 
-Here is the guide for the build of CLI version.
+Here is the guide for the build of LightGBM CLI version.
 
 For the build of Python-package and R-package, please refer to `Python-package`_ and `R-package`_ folders respectively.
 
 Windows
 ~~~~~~~
 
-LightGBM can use Visual Studio, MSBuild with CMake or MinGW to build in Windows.
+On Windows LightGBM can be built using
+
+- **Visual Studio**;
+
+- **CMake** and **MSBuild**;
+
+- **CMake** and **MinGW**.
 
 Visual Studio (or MSBuild)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -22,16 +28,16 @@ With GUI
 
 3. Go to ``LightGBM-master/windows`` folder.
 
-4. Open ``LightGBM.sln`` file with Visual Studio, choose ``Release`` configuration and click ``BUILD``->\ ``Build Solution (Ctrl+Shift+B)``.
+4. Open ``LightGBM.sln`` file with **Visual Studio**, choose ``Release`` configuration and click ``BUILD`` -> ``Build Solution (Ctrl+Shift+B)``.
 
-   If you have errors about **Platform Toolset**, go to ``PROJECT``->\ ``Properties``->\ ``Configuration Properties``->\ ``General`` and select the toolset installed on your machine.
+   If you have errors about **Platform Toolset**, go to ``PROJECT`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
 
 The exe file will be in ``LightGBM-master/windows/x64/Release`` folder.
 
 From Command Line
 *****************
 
-1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `MSBuild`_ (**MSBuild** is not needed if **Visual Studio** (2015 or newer) is installed).
+1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `MSBuild`_ (**MSBuild** is not needed if **Visual Studio** (2015 or newer) is already installed).
 
 2. Run the following commands:
 
@@ -46,8 +52,8 @@ From Command Line
 
 The exe and dll files will be in ``LightGBM/Release`` folder.
 
-MinGW64
-^^^^^^^
+MinGW-w64
+^^^^^^^^^
 
 1. Install `Git for Windows`_, `CMake`_ and `MinGW-w64`_.
 
@@ -66,14 +72,20 @@ The exe and dll files will be in ``LightGBM/`` folder.
 
 **Note**: You may need to run the ``cmake -G "MinGW Makefiles" ..`` one more time if met ``sh.exe was found in your PATH`` error.
 
-Also you may want to read `gcc Tips <./gcc-Tips.rst>`__.
+It is recommended to use **Visual Studio** for its better multithreading efficiency in **Windows** for many-core systems (see `FAQ <./FAQ.rst#lightgbm>`__ Question 4 and Question 8).
+
+Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.
 
 Linux
 ~~~~~
 
-LightGBM uses **CMake** to build. Run the following commands:
+On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**.
 
-.. code::
+1. Install `CMake`_.
+
+2. Run the following commands:
+
+   .. code::
 
      git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
      mkdir build ; cd build
@@ -82,53 +94,65 @@ LightGBM uses **CMake** to build. Run the following commands:
 
 **Note**: glibc >= 2.14 is required.
 
-Also you may want to read `gcc Tips <./gcc-Tips.rst>`__.
+Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.
 
 macOS
 ~~~~~
 
-LightGBM can use Apple Clang (9.0 or higher), or GCC/G++ to build in macOS.
+On macOS LightGBM can be built using **CMake** and **Apple Clang** or **gcc**.
+
+Apple Clang
+^^^^^^^^^^^
 
-Apple Clang (9.0 or higher)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Only **Apple Clang** version 8.1 or higher is supported.
 
 1. Install `CMake`_ (3.12 or higher):
 
    .. code::
 
-     brew install --HEAD cmake
+     brew install cmake
 
-2. Run the following commands:
+2. Install **OpenMP**:
 
    .. code::
 
      brew install libomp
+
+3. Run the following commands:
+
+   .. code::
+
      git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
      mkdir build ; cd build
      cmake ..
      make -j4
 
-GCC/G++
-^^^^^^^
+gcc
+^^^
 
-Please install **gcc/g++** by using the following commands:
+1. Install `CMake`_ (3.2 or higher):
 
-.. code::
+   .. code::
 
      brew install cmake
+
+2. Install **gcc**:
+
+   .. code::
+
      brew install gcc
 
-Then install LightGBM:
+3. Run the following commands:
 
-.. code::
+   .. code::
 
      git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
-  export CXX=g++-7 CC=gcc-7  # replace 7 with version of gcc installed on your machine
+     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
      mkdir build ; cd build
      cmake ..
      make -j4
 
-Also you may want to read `gcc Tips <./gcc-Tips.rst>`__.
+Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.
 
 Docker
 ~~~~~~
@@ -138,14 +162,20 @@ Refer to `Docker folder <https://github.com/Microsoft/LightGBM/tree/master/docke
 Build MPI Version
 ~~~~~~~~~~~~~~~~~
 
-The default build version of LightGBM is based on socket. LightGBM also supports `MPI`_.
-MPI is a high performance communication approach with `RDMA`_ support.
+The default build version of LightGBM is based on socket. LightGBM also supports MPI.
+`MPI`_ is a high performance communication approach with `RDMA`_ support.
 
 If you need to run a parallel learning application with high performance communication, you can build the LightGBM with MPI support.
 
 Windows
 ^^^^^^^
 
+On Windows MPI version of LightGBM can be built using
+
+- **MS MPI** and **Visual Studio**;
+
+- **MS MPI**, **CMake** and **MSBuild**.
+
 With GUI
 ********
 
@@ -157,9 +187,9 @@ With GUI
 
 4. Go to ``LightGBM-master/windows`` folder.
 
-5. Open ``LightGBM.sln`` file with Visual Studio, choose ``Release_mpi`` configuration and click ``BUILD``->\ ``Build Solution (Ctrl+Shift+B)``.
+5. Open ``LightGBM.sln`` file with **Visual Studio**, choose ``Release_mpi`` configuration and click ``BUILD`` -> ``Build Solution (Ctrl+Shift+B)``.
 
-   If you have errors about **Platform Toolset**, go to ``PROJECT``->\ ``Properties``->\ ``Configuration Properties``->\ ``General`` and select the toolset installed on your machine.
+   If you have errors about **Platform Toolset**, go to ``PROJECT`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
 
 The exe file will be in ``LightGBM-master/windows/x64/Release_mpi`` folder.
 
@@ -168,7 +198,7 @@ From Command Line
 
 1. You need to install `MS MPI`_ first. Both ``msmpisdk.msi`` and ``MSMpiSetup.exe`` are needed.
 
-2. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `MSBuild`_ (MSBuild is not needed if **Visual Studio** (2015 or newer) is installed).
+2. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `MSBuild`_ (**MSBuild** is not needed if **Visual Studio** (2015 or newer) is already installed).
 
 3. Run the following commands:
 
@@ -188,11 +218,15 @@ The exe and dll files will be in ``LightGBM/Release`` folder.
 Linux
 ^^^^^
 
-You need to install `Open MPI`_ first.
+On Linux MPI version of LightGBM can be built using **Open MPI**, **CMake** and **gcc** or **Clang**.
 
-Then run the following commands:
+1. Install `Open MPI`_.
 
-.. code::
+2. Install `CMake`_.
+
+3. Run the following commands:
+
+   .. code::
 
      git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
      mkdir build ; cd build
@@ -204,19 +238,67 @@ Then run the following commands:
 macOS
 ^^^^^
 
-Install **Open MPI** first:
+On macOS MPI version of LightGBM can be built using **Open MPI**, **CMake** and **Apple Clang** or **gcc**.
 
-.. code::
+Apple Clang
+***********
+
+Only **Apple Clang** version 8.1 or higher is supported.
+
+1. Install `CMake`_ (3.12 or higher):
+
+   .. code::
+
+     brew install cmake
+
+2. Install **OpenMP**:
+
+   .. code::
+
+     brew install libomp
+
+3. Install **Open MPI**:
+
+   .. code::
 
      brew install open-mpi
+
+4. Run the following commands:
+
+   .. code::
+
+     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
+     mkdir build ; cd build
+     cmake -DUSE_MPI=ON ..
+     make -j4
+
+gcc
+***
+
+1. Install `CMake`_ (3.2 or higher):
+
+   .. code::
+
      brew install cmake
 
-Then run the following commands:
+2. Install **gcc**:
 
-.. code::
+   .. code::
+
+     brew install gcc
+
+3. Install **Open MPI**:
+
+   .. code::
+
+     brew install open-mpi
+
+4. Run the following commands:
+
+   .. code::
 
      git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
-  export CXX=g++-7 CC=gcc-7  # replace 7 with version of gcc installed on your machine
+     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
      mkdir build ; cd build
      cmake -DUSE_MPI=ON ..
      make -j4
@@ -227,19 +309,21 @@ Build GPU Version
 Linux
 ^^^^^
 
+On Linux GPU version of LightGBM can be built using **OpenCL**, **Boost**, **CMake** and **gcc** or **Clang**.
+
 The following dependencies should be installed before compilation:
 
--  OpenCL 1.2 headers and libraries, which is usually provided by GPU manufacture.
+-  **OpenCL** 1.2 headers and libraries, which is usually provided by GPU manufacture.
 
    The generic OpenCL ICD packages (for example, Debian package ``cl-icd-libopencl1`` and ``cl-icd-opencl-dev``) can also be used.
 
--  libboost 1.56 or later (1.61 or later recommended).
+-  **libboost** 1.56 or later (1.61 or later is recommended).
 
    We use Boost.Compute as the interface to GPU, which is part of the Boost library since version 1.61. However, since we include the source code of Boost.Compute as a submodule, we only require the host has Boost 1.56 or later installed. We also use Boost.Align for memory allocation. Boost.Compute requires Boost.System and Boost.Filesystem to store offline kernel cache.
 
    The following Debian packages should provide necessary Boost libraries: ``libboost-dev``, ``libboost-system-dev``, ``libboost-filesystem-dev``.
 
--  CMake 3.2 or later.
+-  **CMake** 3.2 or later.
 
 To build LightGBM GPU version, run the following commands:
 
@@ -255,11 +339,13 @@ To build LightGBM GPU version, run the following commands:
 Windows
 ^^^^^^^
 
-If you use **MinGW**, the build procedure are similar to the build in Linux. Refer to `GPU Windows Compilation <./GPU-Windows.rst>`__ to get more details.
+On Windows GPU version of LightGBM can be built using **OpenCL**, **Boost**, **CMake** and **MSBuild** or **MinGW**.
+
+If you use **MinGW**, the build procedure is similar to the build on Linux. Refer to `GPU Windows Compilation <./GPU-Windows.rst>`__ to get more details.
 
-Following procedure is for the MSVC (Microsoft Visual C++) build.
+Following procedure is for the **MSVC** (Microsoft Visual C++) build.
 
-1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `MSBuild`_ (MSBuild is not needed if **Visual Studio** (2015 or newer) is installed).
+1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `MSBuild`_ (**MSBuild** is not needed if **Visual Studio** (2015 or newer) is installed).
 
 2. Install **OpenCL** for Windows. The installation depends on the brand (NVIDIA, AMD, Intel) of your GPU card.
 
@@ -292,7 +378,7 @@ Following procedure is for the MSVC (Microsoft Visual C++) build.
      cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_GPU=1 ..
      cmake --build . --target ALL_BUILD --config Release
 
-   **Note**: ``C:\local\boost_1_64_0\`` and ``C:\local\boost_1_64_0\lib64-msvc-14.0`` are locations of your Boost binaries. You also can set them to the environment variable to avoid ``Set ...`` commands when build.
+   **Note**: ``C:\local\boost_1_64_0\`` and ``C:\local\boost_1_64_0\lib64-msvc-14.0`` are locations of your **Boost** binaries. You also can set them to the environment variable to avoid ``Set ...`` commands when build.
 
 Docker
 ^^^^^^
@@ -302,89 +388,20 @@ Refer to `GPU Docker folder <https://github.com/Microsoft/LightGBM/tree/master/d
 Build HDFS Version
 ~~~~~~~~~~~~~~~~~~
 
-Windows
-^^^^^^^
-
-Visual Studio (or MSBuild)
-**************************
-
-1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `MSBuild`_ (**MSBuild** is not needed if **Visual Studio** (2015 or newer) is installed).
-
-2. Run the following commands:
-
-   .. code::
-
-     git clone --recursive https://github.com/Microsoft/LightGBM
-     cd LightGBM
-     mkdir build
-     cd build
-     cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_HDFS=ON ..
-     cmake --build . --target ALL_BUILD --config Release
-
-MinGW64
-*******
-
-1. Install `Git for Windows`_, `CMake`_ and `MinGW-w64`_.
-
-2. Run the following commands:
-
-   .. code::
-
-     git clone --recursive https://github.com/Microsoft/LightGBM
-     cd LightGBM
-     mkdir build
-     cd build
-     cmake -G "MinGW Makefiles" -DUSE_HDFS=ON ..
-     mingw32-make.exe -j4
+**Note**: Installation process of HDFS version is untested.
 
 Linux
 ^^^^^
 
-LightGBM uses **CMake** to build. Run the following commands:
-
-.. code::
-
-  git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
-  mkdir build ; cd build
-  cmake -DUSE_HDFS=ON ..
-  make -j4
-
-macOS
-^^^^^
-
-LightGBM can use Apple Clang (9.0 or higher), or GCC/G++ to build in macOS.
+On Linux HDFS version of LightGBM can be built using **CMake** and **gcc** or **Clang**.
 
-Apple Clang (9.0 or higher)
-***************************
-
-1. Install `CMake`_ (3.12 or higher).
+1. Install `CMake`_.
 
 2. Run the following commands:
 
    .. code::
 
-     brew install libomp
-     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
-     mkdir build ; cd build
-     cmake -DUSE_HDFS=ON ..
-     make -j4
-
-GCC/G++
-*******
-
-Please install **gcc/g++** by using the following commands:
-
-.. code::
-
-  brew install cmake
-  brew install gcc
-
-Then install LightGBM:
-
-.. code::
-
      git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
-  export CXX=g++-7 CC=gcc-7  # replace 7 with version of gcc installed on your machine
      mkdir build ; cd build
      cmake -DUSE_HDFS=ON ..
      make -j4
@@ -395,18 +412,20 @@ Build Java Wrapper
 Linux
 ^^^^^
 
-You need to install `SWIG`_ and **Java** first.
+On Linux Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **gcc** or **Clang**.
 
-Then run the following commands:
+1. Install `CMake`_, `SWIG`_ and **Java**.
 
-.. code::
+2. Run the following commands:
+
+   .. code::
 
      git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
      mkdir build ; cd build
      cmake -DUSE_SWIG=ON ..
-  make -j4
+     make _lightgbm_swig -j4
 
-This will generate a JAR file containing the LightGBM `C API <./Development-Guide.rst#c-api>`__ wrapped by SWIG.
+This will generate a JAR file containing the LightGBM `C API <./Development-Guide.rst#c-api>`__ wrapped by **SWIG**.
 
 .. _Python-package: https://github.com/Microsoft/LightGBM/tree/master/python-package
 

python-package/README.rst

@@ -9,18 +9,18 @@ Installation
 Preparation
 '''''''''''
 
-`setuptools <https://pypi.org/project/setuptools>`_ is needed.
-
-For macOS users, gcc with OpenMP support must be installed first. Refer to `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#macos>`__ for installing gcc with OpenMP support.
+32-bit Python is not supported. Please install 64-bit version.
 
-Note: 32-bit Python is not supported. Please install 64-bit version.
+`setuptools <https://pypi.org/project/setuptools>`_ is needed.
 
 Install from `PyPI <https://pypi.org/project/lightgbm>`_ Using ``pip``
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
-For Windows users, `VC runtime <https://go.microsoft.com/fwlink/?LinkId=746572>`_ is needed if Visual Studio (2015 or 2017) is not installed.
+For **Windows** users, `VC runtime <https://go.microsoft.com/fwlink/?LinkId=746572>`_ is needed if **Visual Studio** (2015 or 2017) is not installed.
 
-For macOS users, latest versions of LightGBM are built with **g++-8** and cannot be launched on systems with **g++-7** and earlier. You should update your **g++** compiler if you don't want to build from sources or install LightGBM 2.1.1 which is the last version built with **g++-7**.
+For **macOS** users, **gcc** with **OpenMP** support must be installed first. Refer to `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc>`__ for installation of **gcc** with **OpenMP** support.
+
+For **macOS** users, latest versions of LightGBM are built with **gcc-8** and cannot be launched on systems with **gcc-7** and earlier. You should update your **gcc** compiler if you don't want to build from sources or install LightGBM 2.1.1 which is the last version built with **gcc-7**.
 
 Install `wheel <http://pythonwheels.com>`_ via ``pip install wheel`` first. After that download the wheel file and install from it:
 
@@ -35,11 +35,11 @@ Build from Sources
 
     pip install --no-binary :all: lightgbm
 
-For Linux and macOS users, installation from sources requires installed `CMake <https://cmake.org/>`_.
+For **Linux** and **macOS** users, installation from sources requires installed `CMake`_.
 
-For macOS users, you need to specify compilers by runnig ``export CXX=g++-7 CC=gcc-7`` (replace 7 with version of gcc installed on your machine) first.
+For **macOS** users, you can perform installation either with **Apple Clang** or **gcc**. In case you prefer **Apple Clang**, you should install **OpenMP** (details for installation can be found in `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#apple-clang>`__) first and **CMake** version 3.12 or higher is required. In case you prefer **gcc**, you need to install it (details for installation can be found in `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc>`__) and specify compilers by running ``export CXX=g++-7 CC=gcc-7`` (replace "7" with version of **gcc** installed on your machine) first.
 
-For Windows users, Visual Studio (or `MS Build <https://visualstudio.microsoft.com/downloads/>`_) is needed. If you get any errors during installation, you may need to install `CMake <https://cmake.org/>`_ (version 3.8 or higher).
+For **Windows** users, **Visual Studio** (or `MS Build <https://visualstudio.microsoft.com/downloads/>`_) is needed. If you get any errors during installation, you may need to install `CMake`_ (version 3.8 or higher).
 
 Build MPI Version
 ~~~~~~~~~~~~~~~~~
@@ -48,9 +48,11 @@ Build MPI Version
 
     pip install lightgbm --install-option=--mpi
 
-For Windows users, compilation with MinGW-w64 is not supported and `CMake <https://cmake.org/>`_ (version 3.8 or higher) is strongly required in this case.
+All remarks from `Build from Sources section <#build-from-sources>`__ are actual in this case.
+
+For **Windows** users, compilation with **MinGW-w64** is not supported and `CMake`_ (version 3.8 or higher) is strongly required.
 
-Note: MPI libraries are needed: details for installation can be found in `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-mpi-version>`__.
+**MPI** libraries are needed: details for installation can be found in `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-mpi-version>`__.
 
 Build GPU Version
 ~~~~~~~~~~~~~~~~~
@@ -59,11 +61,11 @@ Build GPU Version
 
     pip install lightgbm --install-option=--gpu
 
-For Windows users, `CMake <https://cmake.org/>`_ (version 3.8 or higher) is strongly required in this case.
+All remarks from `Build from Sources section <#build-from-sources>`__ are actual in this case.
 
-Note: Boost and OpenCL are needed: details for installation can be found in `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-gpu-version>`__. You need to add ``OpenCL_INCLUDE_DIR`` to the environmental variable **'PATH'** and export ``BOOST_ROOT`` before installation.
+For **Windows** users, `CMake`_ (version 3.8 or higher) is strongly required.
 
-Also you may pass options to CMake via pip options, like
+**Boost** and **OpenCL** are needed: details for installation can be found in `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-gpu-version>`__. You need to add ``OpenCL_INCLUDE_DIR`` to the environmental variable **'PATH'** and export ``BOOST_ROOT`` before installation. Alternatively, you may pass options to **CMake** via ``pip`` options, like
 
 .. code:: sh
 
@@ -92,7 +94,7 @@ Build HDFS Version
 
     pip install lightgbm --install-option=--hdfs
 
-For Windows users, `CMake <https://cmake.org/>`_ (version 3.8 or higher) is strongly required in this case.
+Note that the installation process of HDFS version is **untested**.
 
 Build with MinGW-w64 on Windows
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -101,38 +103,35 @@ Build with MinGW-w64 on Windows
 
     pip install lightgbm --install-option=--mingw
 
-Note: `CMake <https://cmake.org/>`_ and `MinGW-w64 <https://mingw-w64.org/>`_ should be installed first.
+`CMake`_ and `MinGW-w64 <https://mingw-w64.org/>`_ should be installed first.
+
+It is recommended to use **Visual Studio** for its better multithreading efficiency in **Windows** for many-core systems (see `FAQ <https://github.com/Microsoft/LightGBM/blob/master/docs/FAQ.rst#lightgbm>`__ Question 4 and Question 8).
 
 Install from GitHub
 '''''''''''''''''''
 
-For Linux and macOS users, installation from GitHub requires installed `CMake <https://cmake.org/>`_.
+All remarks from `Build from Sources section <#build-from-sources>`__ are actual in this case.
 
-For Windows users, Visual Studio (or `MS Build <https://visualstudio.microsoft.com/downloads/>`_) is needed. If you get any errors during installation and there is the warning ``WARNING:LightGBM:Compilation with MSBuild from existing solution file failed.`` in the log, you should install `CMake <https://cmake.org/>`_ (version 3.8 or higher).
+For **Windows** users, if you get any errors during installation and there is the warning ``WARNING:LightGBM:Compilation with MSBuild from existing solution file failed.`` in the log, you should install `CMake`_ (version 3.8 or higher).
 
 .. code:: sh
 
     git clone --recursive https://github.com/Microsoft/LightGBM.git
     cd LightGBM/python-package
-    # export CXX=g++-7 CC=gcc-7  # for macOS users only (replace 7 with version of gcc installed on your machine)
+    # export CXX=g++-7 CC=gcc-7  # macOS users, if you decided to compile with gcc, don't forget to specify compilers (replace "7" with version of gcc installed on your machine)
     python setup.py install
 
-Note: ``sudo`` (or administrator rights in Windows) may be needed to perform the command.
-
-Run ``python setup.py install --mpi`` to enable MPI support. For Windows users, compilation with MinGW-w64 is not supported and `CMake <https://cmake.org/>`_ (version 3.8 or higher) is strongly required in this case. MPI libraries are needed: details for installation can be found in `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-mpi-version>`__.
+Note: ``sudo`` (or administrator rights in **Windows**) may be needed to perform the command.
 
-Run ``python setup.py install --mingw`` if you want to use MinGW-w64 on Windows instead of Visual Studio. `CMake <https://cmake.org/>`_ and `MinGW-w64 <https://mingw-w64.org/>`_ should be installed first.
+Run ``python setup.py install --mpi`` to enable **MPI** support. All remarks from `Build MPI Version section <#build-mpi-version>`__ are actual in this case.
 
-Run ``python setup.py install --gpu`` to enable GPU support. For Windows users, `CMake <https://cmake.org/>`_ (version 3.8 or higher) is strongly required in this case. Boost and OpenCL are needed: details for installation can be found in `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-gpu-version>`__. You can pass additional options to CMake: ``python setup.py install --gpu --opencl-include-dir=/usr/local/cuda/include/``, see `Build GPU Version <#build-gpu-version>`__ for complete list of them.
+Run ``python setup.py install --mingw``, if you want to use **MinGW-w64** on **Windows** instead of **Visual Studio**. All remarks from `Build with MinGW-w64 on Windows section <#build-with-mingw-w64-on-windows>`__ are actual in this case.
 
-Run ``python setup.py install --hdfs`` to enable HDFS support. For Windows users, `CMake <https://cmake.org/>`_ (version 3.8 or higher) is strongly required in this case.
+Run ``python setup.py install --gpu`` to enable GPU support. All remarks from `Build GPU Version section <#build-gpu-version>`__ are actual in this case. To pass additional options to **CMake** use the following syntax: ``python setup.py install --gpu --opencl-include-dir=/usr/local/cuda/include/``, see `Build GPU Version section <#build-gpu-version>`__ for the complete list of them.
 
-If you get any errors during installation or due to any other reason, you may want to build dynamic library from sources by any method you prefer (see `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst>`__) and then run ``python setup.py install --precompile``.
+Run ``python setup.py install --hdfs`` to enable HDFS support. All remarks from `Build HDFS Version section <#build-hdfs-version>`__ are actual in this case.
 
-Examples
---------
-
-Refer to the walk through examples in `Python guide folder <https://github.com/Microsoft/LightGBM/tree/master/examples/python-guide>`_.
+If you get any errors during installation or due to any other reasons, you may want to build dynamic library from sources by any method you prefer (see `Installation Guide <https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst>`__) and then just run ``python setup.py install --precompile``.
 
 Troubleshooting
 ---------------
@@ -141,6 +140,11 @@ In case you are facing any errors during the installation process, you can exami
 
 Refer to `FAQ <https://github.com/Microsoft/LightGBM/tree/master/docs/FAQ.rst>`_.
 
+Examples
+--------
+
+Refer to the walk through examples in `Python guide folder <https://github.com/Microsoft/LightGBM/tree/master/examples/python-guide>`_.
+
 Developments
 ------------
 
@@ -162,3 +166,5 @@ E501 (line too long) and W503 (line break occurred before a binary operator) can
    :target: https://pypi.org/project/lightgbm
 .. |PyPI Version| image:: https://img.shields.io/pypi/v/lightgbm.svg
    :target: https://pypi.org/project/lightgbm
+
+.. _CMake: https://cmake.org/