Skip to content

GitLab

"docker/vscode:/vscode.git/clone" did not exist on "02a0089fc1c627e9f98776ab64c2aaac5209a56e"
Unverified Commit ea04c66c authored by Nikita Titov's avatar Nikita Titov Committed by GitHub
Browse files

[docs] update installation guide (#6696) 



* Update Installation-Guide.rst

* Update script.js

* replace all Ninja sections with one paragraph

---------
Co-authored-by: default avatarshiyu1994 <shiyu_k1994@qq.com>
parent 784f3841
Show whitespace changes
Inline Side-by-side
Showing with 389 additions and 236 deletions
docs/Installation-Guide.rst
View file @ ea04c66c
Installation Guide
==================
This is a guide for building the LightGBM Command Line Interface (CLI). If you want to build the Python-package or R-package please refer to `Python-package`_ and `R-package`_ folders respectively.
All instructions below are aimed at compiling the 64-bit version of LightGBM.
It is worth compiling the 32-bit version only in very rare special cases involving environmental limitations.
The 32-bit version is slow and untested, so use it at your own risk and don't forget to adjust some of the commands below when installing.
By default, instructions below will use **VS Build Tools** or **make** tool to compile the code.
It it possible to use `Ninja`_ tool instead of make on all platforms, but VS Build Tools cannot be replaced with Ninja.
You can add ``-G Ninja`` to CMake flags to use Ninja.
By default, instructions below will produce a shared library file and an executable file with command-line interface.
You can add ``-DBUILD_CLI=OFF`` to CMake flags to disable the executable compilation.
If you need to build a static library instead of a shared one, you can add ``-DBUILD_STATIC_LIB=ON`` to CMake flags.
By default, instructions below will place header files into system-wide folder.
You can add ``-DINSTALL_HEADERS=OFF`` to CMake flags to disable headers installation.
By default, on macOS, CMake is looking into Homebrew standard folders for finding dependencies (e.g. OpenMP).
You can add ``-DUSE_HOMEBREW_FALLBACK=OFF`` to CMake flags to disable this behaviour.
Users who want to perform benchmarking can make LightGBM output time costs for different internal routines by adding ``-DUSE_TIMETAG=ON`` to CMake flags.
It is possible to build LightGBM in debug mode. In this mode all compiler optimizations are disabled and LightGBM performs more checks internally. To enable debug mode you can add ``-DUSE_DEBUG=ON`` to CMake flags or choose ``Debug_*`` configuration (e.g. ``Debug_DLL``, ``Debug_mpi``) in Visual Studio depending on how you are building LightGBM.
It is possible to build LightGBM in debug mode.
In this mode all compiler optimizations are disabled and LightGBM performs more checks internally.
To enable debug mode you can add ``-DUSE_DEBUG=ON`` to CMake flags or choose ``Debug_*`` configuration (e.g. ``Debug_DLL``, ``Debug_mpi``) in Visual Studio depending on how you are building LightGBM.
.. _sanitizers:
......@@ -30,7 +43,7 @@ It is very useful to build `C++ unit tests <#build-c-unit-tests>`__ with sanitiz
.. _nightly-builds:
You can also download the artifacts of the latest successful build on master branch (nightly builds) here: |download artifacts|.
You can download the artifacts of the latest successful build on master branch (nightly builds) here: |download artifacts|.
.. contents:: **Contents**
:depth: 1
......@@ -40,12 +53,10 @@ You can also download the artifacts of the latest successful build on master bra
Windows
~~~~~~~
On Windows LightGBM can be built using
On Windows, LightGBM can be built using
- **Visual Studio**;
- **CMake** and **VS Build Tools**;
- **CMake** and **MinGW**.
Visual Studio (or VS Build Tools)
......@@ -54,22 +65,23 @@ Visual Studio (or VS Build Tools)
With GUI
********
1. Install `Visual Studio`_ (2015 or newer).
1. Install `Visual Studio`_.
2. Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download ``LightGBM-complete_source_code_zip.zip``, and unzip it.
3. Go to ``LightGBM-master/windows`` folder.
3. Go to ``LightGBM-complete_source_code_zip/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 if you need executable file or ``DLL`` configuration if you need shared library 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.
The ``.exe`` file will be in ``LightGBM-complete_source_code_zip/windows/x64/Release`` folder.
The ``.dll`` file will be in ``LightGBM-complete_source_code_zip/windows/x64/DLL`` folder.
From Command Line
*****************
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
2. Run the following commands:
......@@ -98,7 +110,7 @@ MinGW-w64
The ``.exe`` and ``.dll`` files will be in ``LightGBM/`` folder.
**Note**: You may need to run the ``cmake -B build -S . -G "MinGW Makefiles"`` one more time if you encounter the ``sh.exe was found in your PATH`` error.
**Note**: You may need to run the ``cmake -B build -S . -G "MinGW Makefiles"`` one more time or add ``-DCMAKE_SH=CMAKE_SH-NOTFOUND`` to CMake flags if you encounter the ``sh.exe was found in your PATH`` error.
It is recommended that you use **Visual Studio** since it has better multithreading efficiency in **Windows** for many-core systems
(see `Question 4 <./FAQ.rst#i-am-using-windows-should-i-use-visual-studio-or-mingw-for-compiling-lightgbm>`__ and `Question 8 <./FAQ.rst#cpu-usage-is-low-like-10-in-windows-when-using-lightgbm-on-very-large-datasets-with-many-core-systems>`__).
......@@ -106,9 +118,17 @@ It is recommended that you use **Visual Studio** since it has better multithread
Linux
~~~~~
On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**.
On Linux, LightGBM can be built using
- **CMake** and **gcc**;
- **CMake** and **Clang**.
After compilation the executable and ``.so`` files will be in ``LightGBM/`` folder.
1. Install `CMake`_.
gcc
^^^
1. Install `CMake`_ and **gcc**.
2. Run the following commands:
......@@ -119,53 +139,69 @@ On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**.
cmake -B build -S .
cmake --build build -j4
**Note**: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for ``lib[g|i]omp`` for doing this).
Clang
^^^^^
Using ``Ninja``
^^^^^^^^^^^^^^^
1. Install `CMake`_, **Clang** and **OpenMP**.
On Linux, LightGBM can also be built with `Ninja <https://ninja-build.org/>`__ instead of ``make``.
2. Run the following commands:
.. code:: sh
.. code:: sh
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -G 'Ninja'
cmake --build build -j2
export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine
cmake -B build -S .
cmake --build build -j4
macOS
~~~~~
On macOS LightGBM can be installed using **Homebrew**, or can be built using **CMake** and **Apple Clang** or **gcc**.
On macOS, LightGBM can be installed using
Apple Clang
^^^^^^^^^^^
- **Homebrew**;
- **MacPorts**;
or can be built using
Only **Apple Clang** version 8.1 or higher is supported.
- **CMake** and **Apple Clang**;
- **CMake** and **gcc**.
Install Using ``Homebrew``
**************************
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: sh
brew install lightgbm
Build from GitHub
*****************
Refer to https://formulae.brew.sh/formula/lightgbm for more details.
1. Install `CMake`_ :
Install Using ``MacPorts``
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: sh
.. code:: sh
brew install cmake
sudo port install LightGBM
Refer to https://ports.macports.org/port/LightGBM for more details.
**Note**: Port for LightGBM is not maintained by LightGBM's maintainers.
2. Install **OpenMP**:
Build from GitHub
^^^^^^^^^^^^^^^^^
After compilation the executable and ``.dylib`` files will be in ``LightGBM/`` folder.
Apple Clang
***********
1. Install `CMake`_ and **OpenMP**:
.. code:: sh
brew install libomp
brew install cmake libomp
3. Run the following commands:
2. Run the following commands:
.. code:: sh
......@@ -175,21 +211,15 @@ Build from GitHub
cmake --build build -j4
gcc
^^^
1. Install `CMake`_ :
.. code:: sh
brew install cmake
***
2. Install **gcc**:
1. Install `CMake`_ and **gcc**:
.. code:: sh
brew install gcc
brew install cmake gcc
3. Run the following commands:
2. Run the following commands:
.. code:: sh
......@@ -213,12 +243,10 @@ You can build LightGBM without OpenMP support but it is **strongly not recommend
Windows
^^^^^^^
On Windows a version of LightGBM without OpenMP support can be built using
On Windows, a version of LightGBM without OpenMP support can be built using
- **Visual Studio**;
- **CMake** and **VS Build Tools**;
- **CMake** and **MinGW**.
Visual Studio (or VS Build Tools)
......@@ -227,26 +255,27 @@ Visual Studio (or VS Build Tools)
With GUI
--------
1. Install `Visual Studio`_ (2015 or newer).
1. Install `Visual Studio`_.
2. Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download ``LightGBM-complete_source_code_zip.zip``, and unzip it.
3. Go to ``LightGBM-master/windows`` folder.
3. Go to ``LightGBM-complete_source_code_zip/windows`` folder.
4. Open ``LightGBM.sln`` file with **Visual Studio**.
4. Open ``LightGBM.sln`` file with **Visual Studio**, choose ``Release`` configuration if you need executable file or ``DLL`` configuration if you need shared library.
5. Go to ``PROJECT`` -> ``Properties`` -> ``Configuration Properties`` -> ``C/C++`` -> ``Language`` and change the ``OpenMP Support`` property to ``No (/openmp-)``.
5. Go to ``Project`` -> ``Properties`` -> ``Configuration Properties`` -> ``C/C++`` -> ``Language`` and change the ``OpenMP Support`` property to ``No (/openmp-)``.
6. Get back to the project's main screen, then choose ``Release`` configuration and click ``BUILD`` -> ``Build Solution (Ctrl+Shift+B)``.
6. Get back to the project's main screen 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.
The ``.exe`` file will be in ``LightGBM-complete_source_code_zip/windows/x64/Release`` folder.
The ``.dll`` file will be in ``LightGBM-complete_source_code_zip/windows/x64/DLL`` folder.
From Command Line
-----------------
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
2. Run the following commands:
......@@ -275,14 +304,36 @@ MinGW-w64
The ``.exe`` and ``.dll`` files will be in ``LightGBM/`` folder.
**Note**: You may need to run the ``cmake -B build -S . -G "MinGW Makefiles" -DUSE_OPENMP=OFF`` one more time if you encounter the ``sh.exe was found in your PATH`` error.
**Note**: You may need to run the ``cmake -B build -S . -G "MinGW Makefiles" -DUSE_OPENMP=OFF`` one more time or add ``-DCMAKE_SH=CMAKE_SH-NOTFOUND`` to CMake flags if you encounter the ``sh.exe was found in your PATH`` error.
Linux
^^^^^
On Linux a version of LightGBM without OpenMP support can be built using **CMake** and **gcc** or **Clang**.
On Linux, a version of LightGBM without OpenMP support can be built using
- **CMake** and **gcc**;
- **CMake** and **Clang**.
After compilation the executable and ``.so`` files will be in ``LightGBM/`` folder.
gcc
***
1. Install `CMake`_ and **gcc**.
2. Run the following commands:
.. code:: sh
1. Install `CMake`_.
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_OPENMP=OFF
cmake --build build -j4
Clang
*****
1. Install `CMake`_ and **Clang**.
2. Run the following commands:
......@@ -290,20 +341,24 @@ On Linux a version of LightGBM without OpenMP support can be built using **CMake
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine
cmake -B build -S . -DUSE_OPENMP=OFF
cmake --build build -j4
macOS
^^^^^
On macOS a version of LightGBM without OpenMP support can be built using **CMake** and **Apple Clang** or **gcc**.
On macOS, a version of LightGBM without OpenMP support can be built using
- **CMake** and **Apple Clang**;
- **CMake** and **gcc**.
After compilation the executable and ``.dylib`` files will be in ``LightGBM/`` folder.
Apple Clang
***********
Only **Apple Clang** version 8.1 or higher is supported.
1. Install `CMake`_ :
1. Install `CMake`_:
.. code:: sh
......@@ -321,19 +376,13 @@ Only **Apple Clang** version 8.1 or higher is supported.
gcc
***
1. Install `CMake`_ :
1. Install `CMake`_ and **gcc**:
.. code:: sh
brew install cmake
brew install cmake gcc
2. Install **gcc**:
.. code:: sh
brew install gcc
3. Run the following commands:
2. Run the following commands:
.. code:: sh
......@@ -354,35 +403,36 @@ If you need to run a distributed learning application with high performance comm
Windows
^^^^^^^
On Windows an MPI version of LightGBM can be built using
On Windows, an MPI version of LightGBM can be built using
- **MS MPI** and **Visual Studio**;
- **MS MPI**, **CMake** and **VS Build Tools**.
**Note**: Building MPI version by **MinGW** is not supported due to the miss of MPI library in it.
With GUI
********
1. You need to install `MS MPI`_ first. Both ``msmpisdk.msi`` and ``msmpisetup.exe`` are needed.
2. Install `Visual Studio`_ (2015 or newer).
2. Install `Visual Studio`_.
3. Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download ``LightGBM-complete_source_code_zip.zip``, and unzip it.
4. Go to ``LightGBM-master/windows`` folder.
4. Go to ``LightGBM-complete_source_code_zip/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.
The ``.exe`` file will be in ``LightGBM-complete_source_code_zip/windows/x64/Release_mpi`` folder.
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`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
2. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
3. Run the following commands:
......@@ -395,18 +445,22 @@ From Command Line
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
**Note**: Building MPI version by **MinGW** is not supported due to the miss of MPI library in it.
Linux
^^^^^
On Linux an MPI version of LightGBM can be built using **Open MPI**, **CMake** and **gcc** or **Clang**.
On Linux, an MPI version of LightGBM can be built using
1. Install `Open MPI`_.
- **CMake**, **gcc** and **Open MPI**;
- **CMake**, **Clang** and **Open MPI**.
2. Install `CMake`_.
After compilation the executable and ``.so`` files will be in ``LightGBM/`` folder.
3. Run the following commands:
gcc
***
1. Install `CMake`_, **gcc** and `Open MPI`_.
2. Run the following commands:
.. code:: sh
......@@ -415,37 +469,41 @@ On Linux an MPI version of LightGBM can be built using **Open MPI**, **CMake** a
cmake -B build -S . -DUSE_MPI=ON
cmake --build build -j4
**Note**: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for ``lib[g|i]omp`` for doing this).
macOS
^^^^^
Clang
*****
On macOS an MPI version of LightGBM can be built using **Open MPI**, **CMake** and **Apple Clang** or **gcc**.
1. Install `CMake`_, **Clang**, **OpenMP** and `Open MPI`_.
Apple Clang
***********
2. Run the following commands:
Only **Apple Clang** version 8.1 or higher is supported.
.. code:: sh
1. Install `CMake`_ :
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine
cmake -B build -S . -DUSE_MPI=ON
cmake --build build -j4
.. code:: sh
macOS
^^^^^
brew install cmake
On macOS, an MPI version of LightGBM can be built using
2. Install **OpenMP**:
- **CMake**, **Open MPI** and **Apple Clang**;
- **CMake**, **Open MPI** and **gcc**.
.. code:: sh
After compilation the executable and ``.dylib`` files will be in ``LightGBM/`` folder.
brew install libomp
Apple Clang
***********
3. Install **Open MPI**:
1. Install `CMake`_, **OpenMP** and `Open MPI`_:
.. code:: sh
brew install open-mpi
brew install cmake libomp open-mpi
4. Run the following commands:
2. Run the following commands:
.. code:: sh
......@@ -457,25 +515,13 @@ Only **Apple Clang** version 8.1 or higher is supported.
gcc
***
1. Install `CMake`_ :
.. code:: sh
brew install cmake
2. Install **gcc**:
1. Install `CMake`_, `Open MPI`_ and **gcc**:
.. code:: sh
brew install gcc
brew install cmake open-mpi gcc
3. Install **Open MPI**:
.. code:: sh
brew install open-mpi
4. Run the following commands:
2. Run the following commands:
.. code:: sh
......@@ -488,48 +534,19 @@ gcc
Build GPU Version
~~~~~~~~~~~~~~~~~
Linux
^^^^^
On Linux a GPU version of LightGBM (``device_type=gpu``) 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.
The generic OpenCL ICD packages (for example, Debian package ``ocl-icd-libopencl1`` and ``ocl-icd-opencl-dev``) can also be used.
- **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**
To build LightGBM GPU version, run the following commands:
.. code:: sh
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_GPU=1
# if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following:
# cmake -B build -S . -DUSE_GPU=1 -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/
cmake --build build
**Note**: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for ``lib[g|i]omp`` for doing this).
Windows
^^^^^^^
On Windows a GPU version of LightGBM (``device_type=gpu``) can be built using **OpenCL**, **Boost**, **CMake** and **VS Build Tools** or **MinGW**.
On Windows, a GPU version of LightGBM (``device_type=gpu``) can be built using
- **OpenCL**, **Boost**, **CMake** and **VS Build Tools**;
- **OpenCL**, **Boost**, **CMake** and **MinGW**.
If you use **MinGW**, the build procedure is similar to the build on Linux.
Following procedure is for the **MSVC** (Microsoft Visual C++) build.
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is installed).
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is installed).
2. Install **OpenCL** for Windows. The installation depends on the brand (NVIDIA, AMD, Intel) of your GPU card.
......@@ -559,13 +576,68 @@ Following procedure is for the **MSVC** (Microsoft Visual C++) build.
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -A x64 -DUSE_GPU=1 -DBOOST_ROOT=C:/local/boost_1_63_0 -DBOOST_LIBRARYDIR=C:/local/boost_1_63_0/lib64-msvc-14.0
cmake -B build -S . -A x64 -DUSE_GPU=ON -DBOOST_ROOT=C:/local/boost_1_63_0 -DBOOST_LIBRARYDIR=C:/local/boost_1_63_0/lib64-msvc-14.0
# if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following:
# cmake -B build -S . -A x64 -DUSE_GPU=1 -DBOOST_ROOT=C:/local/boost_1_63_0 -DBOOST_LIBRARYDIR=C:/local/boost_1_63_0/lib64-msvc-14.0 -DOpenCL_LIBRARY="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v10.0/lib/x64/OpenCL.lib" -DOpenCL_INCLUDE_DIR="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v10.0/include"
# cmake -B build -S . -A x64 -DUSE_GPU=ON -DBOOST_ROOT=C:/local/boost_1_63_0 -DBOOST_LIBRARYDIR=C:/local/boost_1_63_0/lib64-msvc-14.0 -DOpenCL_LIBRARY="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v10.0/lib/x64/OpenCL.lib" -DOpenCL_INCLUDE_DIR="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v10.0/include"
cmake --build build --target ALL_BUILD --config Release
**Note**: ``C:/local/boost_1_63_0`` and ``C:/local/boost_1_63_0/lib64-msvc-14.0`` are locations of your **Boost** binaries (assuming you've downloaded 1.63.0 version for Visual Studio 2015).
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
Linux
^^^^^
On Linux, a GPU version of LightGBM (``device_type=gpu``) can be built using
- **CMake**, **OpenCL**, **Boost** and **gcc**;
- **CMake**, **OpenCL**, **Boost** and **Clang**.
**OpenCL** headers and libraries are usually provided by GPU manufacture.
The generic OpenCL ICD packages (for example, Debian packages ``ocl-icd-libopencl1``, ``ocl-icd-opencl-dev``, ``pocl-opencl-icd``) can also be used.
Required **Boost** libraries (Boost.Align, Boost.System, Boost.Filesystem, Boost.Chrono) should be provided by the following Debian packages: ``libboost-dev``, ``libboost-system-dev``, ``libboost-filesystem-dev``, ``libboost-chrono-dev``.
After compilation the executable and ``.so`` files will be in ``LightGBM/`` folder.
gcc
***
1. Install `CMake`_, **gcc**, **OpenCL** and **Boost**.
2. Run the following commands:
.. code:: sh
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_GPU=ON
# if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following:
# cmake -B build -S . -DUSE_GPU=ON -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/
cmake --build build -j4
Clang
*****
1. Install `CMake`_, **Clang**, **OpenMP**, **OpenCL** and **Boost**.
2. Run the following commands:
.. code:: sh
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine
cmake -B build -S . -DUSE_GPU=ON
# if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following:
# cmake -B build -S . -DUSE_GPU=ON -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/
cmake --build build -j4
macOS
^^^^^
The GPU version is not supported on macOS.
Docker
^^^^^^
......@@ -574,60 +646,84 @@ Refer to `GPU Docker folder <https://github.com/microsoft/LightGBM/tree/master/d
Build CUDA Version
~~~~~~~~~~~~~~~~~~
The `original GPU build <#build-gpu-version>`__ of LightGBM (``device_type=gpu``) is based on OpenCL.
The `original GPU version <#build-gpu-version>`__ of LightGBM (``device_type=gpu``) is based on OpenCL.
The CUDA-based build (``device_type=cuda``) is a separate implementation.
The CUDA-based version (``device_type=cuda``) is a separate implementation.
Use this version in Linux environments with an NVIDIA GPU with compute capability 6.0 or higher.
Windows
^^^^^^^
The CUDA version is not supported on Windows.
Use the `GPU version <#build-gpu-version>`__ (``device_type=gpu``) for GPU acceleration on Windows.
Linux
^^^^^
On Linux a CUDA version of LightGBM can be built using **CUDA**, **CMake** and **gcc** or **Clang**.
On Linux, a CUDA version of LightGBM can be built using
- **CMake**, **gcc** and **CUDA**;
- **CMake**, **Clang** and **CUDA**.
Please refer to `this detailed guide`_ for **CUDA** libraries installation.
The following dependencies should be installed before compilation:
After compilation the executable and ``.so`` files will be in ``LightGBM/`` folder.
- **CUDA** 11.0 or later libraries. Please refer to `this detailed guide`_. Pay great attention to the minimum required versions of host compilers listed in the table from that guide and use only recommended versions of compilers.
gcc
***
- **CMake**
1. Install `CMake`_, **gcc** and **CUDA**.
To build LightGBM CUDA version, run the following commands:
2. Run the following commands:
.. code:: sh
.. code:: sh
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_CUDA=1
cmake -B build -S . -DUSE_CUDA=ON
cmake --build build -j4
**Note**: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for ``lib[g|i]omp`` for doing this).
Clang
*****
1. Install `CMake`_, **Clang**, **OpenMP** and **CUDA**.
2. Run the following commands:
.. code:: sh
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine
cmake -B build -S . -DUSE_CUDA=ON
cmake --build build -j4
macOS
^^^^^
The CUDA version is not supported on macOS.
Windows
^^^^^^^
The CUDA version is not supported on Windows.
Use the GPU version (``device_type=gpu``) for GPU acceleration on Windows.
Build Java Wrapper
~~~~~~~~~~~~~~~~~~
Using the following instructions you can generate a JAR file containing the LightGBM `C API <./Development-Guide.rst#c-api>`__ wrapped by **SWIG**.
After compilation the ``.jar`` file will be in ``LightGBM/build`` folder.
Windows
^^^^^^^
On Windows a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **VS Build Tools** or **MinGW**.
On Windows, a Java wrapper of LightGBM can be built using
- **Java**, **SWIG**, **CMake** and **VS Build Tools**;
- **Java**, **SWIG**, **CMake** and **MinGW**.
VS Build Tools
**************
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).
2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
3. Run the following commands:
......@@ -638,14 +734,12 @@ VS Build Tools
cmake -B build -S . -A x64 -DUSE_SWIG=ON
cmake --build build --target ALL_BUILD --config Release
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/Release`` folder.
MinGW-w64
*********
1. Install `Git for Windows`_, `CMake`_ and `MinGW-w64`_.
2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).
2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
3. Run the following commands:
......@@ -656,9 +750,7 @@ MinGW-w64
cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON
cmake --build build -j4
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/`` folder.
**Note**: You may need to run the ``cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON`` one more time if you encounter the ``sh.exe was found in your PATH`` error.
**Note**: You may need to run the ``cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON`` one more time or add ``-DCMAKE_SH=CMAKE_SH-NOTFOUND`` to CMake flags if you encounter the ``sh.exe was found in your PATH`` error.
It is recommended to use **VS Build Tools (Visual Studio)** since it has better multithreading efficiency in **Windows** for many-core systems
(see `Question 4 <./FAQ.rst#i-am-using-windows-should-i-use-visual-studio-or-mingw-for-compiling-lightgbm>`__ and `Question 8 <./FAQ.rst#cpu-usage-is-low-like-10-in-windows-when-using-lightgbm-on-very-large-datasets-with-many-core-systems>`__).
......@@ -666,9 +758,15 @@ It is recommended to use **VS Build Tools (Visual Studio)** since it has better
Linux
^^^^^
On Linux a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **gcc** or **Clang**.
On Linux, a Java wrapper of LightGBM can be built using
- **CMake**, **gcc**, **Java** and **SWIG**;
- **CMake**, **Clang**, **Java** and **SWIG**.
gcc
***
1. Install `CMake`_, `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).
1. Install `CMake`_, **gcc**, `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
2. Run the following commands:
......@@ -679,34 +777,40 @@ On Linux a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMa
cmake -B build -S . -DUSE_SWIG=ON
cmake --build build -j4
**Note**: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for ``lib[g|i]omp`` for doing this).
Clang
*****
macOS
^^^^^
1. Install `CMake`_, **Clang**, **OpenMP**, `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly).
On macOS a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **Apple Clang** or **gcc**.
2. Run the following commands:
First, install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).
Then, either follow the **Apple Clang** or **gcc** installation instructions below.
.. code:: sh
Apple Clang
***********
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine
cmake -B build -S . -DUSE_SWIG=ON
cmake --build build -j4
Only **Apple Clang** version 8.1 or higher is supported.
macOS
^^^^^
1. Install `CMake`_ :
On macOS, a Java wrapper of LightGBM can be built using
.. code:: sh
- **CMake**, **Java**, **SWIG** and **Apple Clang**;
- **CMake**, **Java**, **SWIG** and **gcc**.
brew install cmake
Apple Clang
***********
2. Install **OpenMP**:
1. Install `CMake`_, **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly), `SWIG`_ and **OpenMP**:
.. code:: sh
brew install libomp
brew install cmake openjdk swig libomp
export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
3. Run the following commands:
2. Run the following commands:
.. code:: sh
......@@ -718,19 +822,14 @@ Only **Apple Clang** version 8.1 or higher is supported.
gcc
***
1. Install `CMake`_ :
1. Install `CMake`_, **Java** (also make sure that ``JAVA_HOME`` environment variable is set properly), `SWIG`_ and **gcc**:
.. code:: sh
brew install cmake
2. Install **gcc**:
.. code:: sh
brew install gcc
brew install cmake openjdk swig gcc
export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"
3. Run the following commands:
2. Run the following commands:
.. code:: sh
......@@ -740,15 +839,31 @@ gcc
cmake -B build -S . -DUSE_SWIG=ON
cmake --build build -j4
Build Python-package
~~~~~~~~~~~~~~~~~~~~
Refer to `Python-package folder <https://github.com/microsoft/LightGBM/tree/master/python-package>`__.
Build R-package
~~~~~~~~~~~~~~~
Refer to `R-package folder <https://github.com/microsoft/LightGBM/tree/master/R-package>`__.
Build C++ Unit Tests
~~~~~~~~~~~~~~~~~~~~
Windows
^^^^^^^
On Windows, C++ unit tests of LightGBM can be built using **CMake** and **VS Build Tools**.
On Windows, C++ unit tests of LightGBM can be built using
- **CMake** and **VS Build Tools**;
- **CMake** and **MinGW**.
VS Build Tools
**************
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** is already installed).
2. Run the following commands:
......@@ -756,17 +871,43 @@ On Windows, C++ unit tests of LightGBM can be built using **CMake** and **VS Bui
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -A x64 -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
cmake -B build -S . -A x64 -DBUILD_CPP_TEST=ON
cmake --build build --target testlightgbm --config Debug
The ``.exe`` file will be in ``LightGBM/Debug`` folder.
MinGW-w64
*********
1. Install `Git for Windows`_, `CMake`_ and `MinGW-w64`_.
2. Run the following commands:
.. code:: console
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -G "MinGW Makefiles" -DBUILD_CPP_TEST=ON
cmake --build build --target testlightgbm -j4
The ``.exe`` file will be in ``LightGBM/`` folder.
**Note**: You may need to run the ``cmake -B build -S . -G "MinGW Makefiles" -DBUILD_CPP_TEST=ON`` one more time or add ``-DCMAKE_SH=CMAKE_SH-NOTFOUND`` to CMake flags if you encounter the ``sh.exe was found in your PATH`` error.
Linux
^^^^^
On Linux a C++ unit tests of LightGBM can be built using **CMake** and **gcc** or **Clang**.
On Linux, a C++ unit tests of LightGBM can be built using
- **CMake** and **gcc**;
- **CMake** and **Clang**.
After compilation the executable file will be in ``LightGBM/`` folder.
gcc
***
1. Install `CMake`_.
1. Install `CMake`_ and **gcc**.
2. Run the following commands:
......@@ -774,24 +915,42 @@ On Linux a C++ unit tests of LightGBM can be built using **CMake** and **gcc** o
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
cmake -B build -S . -DBUILD_CPP_TEST=ON
cmake --build build --target testlightgbm -j4
Clang
*****
1. Install `CMake`_, **Clang** and **OpenMP**.
2. Run the following commands:
.. code:: sh
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
export CXX=clang++-14 CC=clang-14 # replace "14" with version of Clang installed on your machine
cmake -B build -S . -DBUILD_CPP_TEST=ON
cmake --build build --target testlightgbm -j4
macOS
^^^^^
On macOS a C++ unit tests of LightGBM can be built using **CMake** and **Apple Clang** or **gcc**.
On macOS, a C++ unit tests of LightGBM can be built using
- **CMake** and **Apple Clang**;
- **CMake** and **gcc**.
After compilation the executable file will be in ``LightGBM/`` folder.
Apple Clang
***********
Only **Apple Clang** version 8.1 or higher is supported.
1. Install `CMake`_ :
1. Install `CMake`_ and **OpenMP**:
.. code:: sh
brew install cmake
brew install cmake libomp
2. Run the following commands:
......@@ -799,42 +958,32 @@ Only **Apple Clang** version 8.1 or higher is supported.
git clone --recursive https://github.com/microsoft/LightGBM
cd LightGBM
cmake -B build -S . -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
cmake -B build -S . -DBUILD_CPP_TEST=ON
cmake --build build --target testlightgbm -j4
gcc
***
1. Install `CMake`_ :
1. Install `CMake`_ and **gcc**:
.. code:: sh
brew install cmake
2. Install **gcc**:
brew install cmake gcc
.. code:: sh
brew install gcc
3. Run the following commands:
2. Run the following commands:
.. code:: sh
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
cmake -B build -S . -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
cmake -B build -S . -DBUILD_CPP_TEST=ON
cmake --build build --target testlightgbm -j4
.. |download artifacts| image:: ./_static/images/artifacts-not-available.svg
:target: https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html
.. _Python-package: https://github.com/microsoft/LightGBM/tree/master/python-package
.. _R-package: https://github.com/microsoft/LightGBM/tree/master/R-package
.. _Visual Studio: https://visualstudio.microsoft.com/downloads/
.. _Git for Windows: https://git-scm.com/download/win
......@@ -864,3 +1013,5 @@ gcc
.. _this detailed guide: https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html
.. _following docs: https://github.com/google/sanitizers/wiki
.. _Ninja: https://ninja-build.org
docs/_static/js/script.js
View file @ ea04c66c
......@@ -15,7 +15,7 @@ $(() => {
/* Collapse specified sections in the installation guide */
if (window.location.pathname.toLocaleLowerCase().indexOf("installation-guide") !== -1) {
$(
'<style>.closed, .opened {cursor: pointer;} .closed:before, .opened:before {font-family: FontAwesome; display: inline-block; padding-right: 6px;} .closed:before {content: "\\f078";} .opened:before {content: "\\f077";}</style>',
'<style>.closed, .opened {cursor: pointer;} .closed:before, .opened:before {font-family: FontAwesome; display: inline-block; padding-right: 6px;} .closed:before {content: "\\f054";} .opened:before {content: "\\f078";}</style>',
).appendTo("body");
const collapsible = [
"#build-threadless-version-not-recommended",
......@@ -23,6 +23,8 @@ $(() => {
"#build-gpu-version",
"#build-cuda-version",
"#build-java-wrapper",
"#build-python-package",
"#build-r-package",
"#build-c-unit-tests",
];
$.each(collapsible, (_, val) => {
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment