Skip to content

Installation-Guide.rst

Latest commit

 

History

History
1120 lines (695 loc) · 33 KB

Installation-Guide.rst

File metadata and controls

1120 lines (695 loc) · 33 KB

Installation Guide

Versioning

LightGBM releases use a 3-part version number, with this format:

{major}.{minor}.{patch}

This version follows a scheme called Intended Effort Versioning ("Effver" for short). Changes to a component of the version indicate how much effort it will likely take to update code using a previous version.

  • major = updating will require significant effort
  • minor = some effort
  • patch = no or very little effort

This means that new minor versions can contain breaking changes, but these are typically small or limited to less-frequently-used parts of the project.

When built from source on an unreleased commit, this version takes the following form:

{major}.{minor}.{patch}.99

That .99 is added to ensure that a version built from an unreleased commit is considered "newer" than all previous releases, and "older" than all future releases.

To download such artifacts, run the following from the root of this repository.

bash .ci/download-artifacts.sh ${COMMIT_ID}

Where COMMIT_ID is the full commit SHA pointing to a commit on master. The artifacts can then be found in the release-artifacts/ directory.

For more details on why LightGBM uses EffVer instead of other schemes like semantic versioning, see https://jacobtomlinson.dev/effver/.

General Installation Notes

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.

In addition to the debug mode, LightGBM can be built with compiler sanitizers. To enable them add -DUSE_SANITIZER=ON -DENABLED_SANITIZERS="address;leak;undefined" to CMake flags. These values refer to the following supported sanitizers:

  • address - AddressSanitizer (ASan);
  • leak - LeakSanitizer (LSan);
  • undefined - UndefinedBehaviorSanitizer (UBSan);
  • thread - ThreadSanitizer (TSan).

Please note, that ThreadSanitizer cannot be used together with other sanitizers. For more info and additional sanitizers' parameters please refer to the following docs. It is very useful to build C++ unit tests with sanitizers.

Windows

On Windows, LightGBM can be built using

  • Visual Studio;
  • CMake and VS Build Tools;
  • CMake and MinGW.

Visual Studio (or VS Build Tools)

With GUI

  1. Install Visual Studio.

  2. Navigate to one of the releases at https://github.com/lightgbm-org/LightGBM/releases, download LightGBM-complete_source_code_zip.zip, and unzip it.

  3. Go to LightGBM-complete_source_code_zip/windows folder.

  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 Windows SDK Version, go to Project -> Properties -> Configuration Properties -> General and select the SDK installed on your machine.

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 is already installed).

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -A x64
cmake --build build --target ALL_BUILD --config Release

The .exe and .dll files will be in LightGBM/Release folder.

MinGW-w64

  1. Install Git for Windows, CMake and MinGW-w64.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -G "MinGW Makefiles"
cmake --build build -j4

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 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 and Question 8).

Linux

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.

gcc

  1. Install CMake and gcc.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S .
cmake --build build -j4

Clang

  1. Install CMake, Clang and OpenMP.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
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;
  • MacPorts;

or can be built using

  • CMake and Apple Clang;
  • CMake and gcc.

Install Using Homebrew

brew install lightgbm

Refer to https://formulae.brew.sh/formula/lightgbm for more details.

Install Using MacPorts

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.

Build from GitHub

After compilation the executable and .dylib files will be in LightGBM/ folder.

Apple Clang

  1. Install CMake and OpenMP:

    brew install cmake libomp

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S .
cmake --build build -j4

gcc

  1. Install CMake and gcc:

    brew install cmake gcc

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
cmake -B build -S .
cmake --build build -j4

Docker

Refer to Docker folder.

Build Threadless Version (not Recommended)

The default build version of LightGBM is based on OpenMP. You can build LightGBM without OpenMP support but it is strongly not recommended.

Windows

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)

With GUI

  1. Install Visual Studio.

  2. Navigate to one of the releases at https://github.com/lightgbm-org/LightGBM/releases, download LightGBM-complete_source_code_zip.zip, and unzip it.

  3. Go to LightGBM-complete_source_code_zip/windows folder.

  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-).

  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 Windows SDK Version, go to Project -> Properties -> Configuration Properties -> General and select the SDK installed on your machine.

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 is already installed).

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -A x64 -DUSE_OPENMP=OFF
cmake --build build --target ALL_BUILD --config Release

The .exe and .dll files will be in LightGBM/Release folder.

MinGW-w64

  1. Install Git for Windows, CMake and MinGW-w64.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -G "MinGW Makefiles" -DUSE_OPENMP=OFF
cmake --build build -j4

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 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;
  • 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:

    git clone --recursive https://github.com/lightgbm-org/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:

    git clone --recursive https://github.com/lightgbm-org/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;
  • CMake and gcc.

After compilation the executable and .dylib files will be in LightGBM/ folder.

Apple Clang

  1. Install CMake:

    brew install cmake

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_OPENMP=OFF
cmake --build build -j4

gcc

  1. Install CMake and gcc:

    brew install cmake gcc

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
cmake -B build -S . -DUSE_OPENMP=OFF
cmake --build build -j4

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.

If you need to run a distributed learning application with high performance communication, you can build the LightGBM with MPI support.

Windows

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.

  3. Navigate to one of the releases at https://github.com/lightgbm-org/LightGBM/releases, download LightGBM-complete_source_code_zip.zip, and unzip it.

  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).

    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 Windows SDK Version, go to Project -> Properties -> Configuration Properties -> General and select the SDK installed on your machine.

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 is already installed).

  3. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -A x64 -DUSE_MPI=ON
cmake --build build --target ALL_BUILD --config Release

The .exe and .dll files will be in LightGBM/Release folder.

Linux

On Linux, an MPI version of LightGBM can be built using

  • CMake, gcc and Open MPI;
  • CMake, Clang and Open MPI.

After compilation the executable and .so files will be in LightGBM/ folder.

gcc

  1. Install CMake, gcc and Open MPI.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_MPI=ON
cmake --build build -j4

Clang

  1. Install CMake, Clang, OpenMP and Open MPI.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/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

macOS

On macOS, an MPI version of LightGBM can be built using

  • CMake, Open MPI and Apple Clang;
  • CMake, Open MPI and gcc.

After compilation the executable and .dylib files will be in LightGBM/ folder.

Apple Clang

  1. Install CMake, OpenMP and Open MPI:

    brew install cmake libomp open-mpi

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_MPI=ON
cmake --build build -j4

gcc

  1. Install CMake, Open MPI and gcc:

    brew install cmake open-mpi gcc

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
cmake -B build -S . -DUSE_MPI=ON
cmake --build build -j4

Build GPU Version

Windows

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 is installed).

  2. Install OpenCL for Windows. The installation depends on the brand (NVIDIA, AMD, Intel) of your GPU card.

    Further reading and correspondence table: GPU SDK Correspondence and Device Targeting Table.

  3. Install Boost Binaries.

    Note: Match your Visual C++ version:

    Visual Studio 2017 -> msvc-14.1-64.exe,

    Visual Studio 2019 -> msvc-14.2-64.exe,

    Visual Studio 2022 -> msvc-14.3-64.exe.

  4. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
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.3
# 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=ON -DBOOST_ROOT=C:/local/boost_1_63_0 -DBOOST_LIBRARYDIR=C:/local/boost_1_63_0/lib64-msvc-14.3 -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.3 are locations of your Boost binaries (assuming you've downloaded 1.63.0 version for Visual Studio 2022).

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:

    git clone --recursive https://github.com/lightgbm-org/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:

    git clone --recursive https://github.com/lightgbm-org/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

Refer to GPU Docker folder.

Build CUDA Version

The original GPU version of LightGBM (device_type=gpu) is based on OpenCL, and only computes histograms on GPUs, with other parts of training in CPUs.

The CUDA-based version (device_type=cuda) is a separate implementation that runs significantly faster by putting all the training process on GPUs. It also supports multi-GPU, and multi-node multi-GPU training. 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 (device_type=gpu) for GPU acceleration on Windows.

Linux

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.

After compilation the executable and .so files will be in LightGBM/ folder.

gcc

  1. Install CMake, gcc and CUDA.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_CUDA=ON
cmake --build build -j4

Clang

  1. Install CMake, Clang, OpenMP and CUDA.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/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.

Build ROCm Version

The original GPU version of LightGBM (device_type=gpu) is based on OpenCL.

The ROCm-based version (device_type=cuda) is a separate implementation. Yes, the ROCm version reuses the device_type=cuda as a convenience for users. Use this version in Linux environments with an AMD GPU.

Windows

The ROCm version is not supported on Windows. Use the GPU version (device_type=gpu) for GPU acceleration on Windows.

Linux

On Linux, a ROCm version of LightGBM can be built using

  • CMake, gcc and ROCm;
  • CMake, Clang and ROCm.

Please refer to the ROCm docs for ROCm libraries installation.

After compilation the executable and .so files will be in LightGBM/ folder.

gcc

  1. Install CMake, gcc and ROCm.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_ROCM=ON
cmake --build build -j4

Clang

  1. Install CMake, Clang, OpenMP and ROCm.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/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_ROCM=ON
cmake --build build -j4

macOS

The ROCm version is not supported on macOS.

Build Java Wrapper

Using the following instructions you can generate a JAR file containing the LightGBM 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;
  • 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 is already installed).

  2. Install SWIG and Java (also make sure that JAVA_HOME environment variable is set properly).

  3. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -A x64 -DUSE_SWIG=ON
cmake --build build --target ALL_BUILD --config Release

MinGW-w64

  1. Install Git for Windows, CMake and MinGW-w64.

  2. Install SWIG and Java (also make sure that JAVA_HOME environment variable is set properly).

  3. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON
cmake --build build -j4

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 and Question 8).

Linux

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, gcc, SWIG and Java (also make sure that JAVA_HOME environment variable is set properly).

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_SWIG=ON
cmake --build build -j4

Clang

  1. Install CMake, Clang, OpenMP, SWIG and Java (also make sure that JAVA_HOME environment variable is set properly).

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/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

macOS

On macOS, a Java wrapper of LightGBM can be built using

  • CMake, Java, SWIG and Apple Clang;
  • CMake, Java, SWIG and gcc.

Apple Clang

  1. Install CMake, Java (also make sure that JAVA_HOME environment variable is set properly), SWIG and OpenMP:

    brew install cmake openjdk swig libomp
export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -DUSE_SWIG=ON
cmake --build build -j4

gcc

  1. Install CMake, Java (also make sure that JAVA_HOME environment variable is set properly), SWIG and gcc:

    brew install cmake openjdk swig gcc
export JAVA_HOME="$(brew --prefix openjdk)/libexec/openjdk.jdk/Contents/Home/"

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
cmake -B build -S . -DUSE_SWIG=ON
cmake --build build -j4

Build Python-package

Refer to Python-package folder.

Build R-package

Refer to R-package folder.

Build C++ Unit Tests

Windows

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 is already installed).

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
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:

    git clone --recursive https://github.com/lightgbm-org/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;
  • CMake and Clang.

After compilation the executable file will be in LightGBM/ folder.

gcc

  1. Install CMake and gcc.

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
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:

    git clone --recursive https://github.com/lightgbm-org/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;
  • CMake and gcc.

After compilation the executable file will be in LightGBM/ folder.

Apple Clang

  1. Install CMake and OpenMP:

    brew install cmake libomp

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S . -DBUILD_CPP_TEST=ON
cmake --build build --target testlightgbm -j4

gcc

  1. Install CMake and gcc:

    brew install cmake gcc

  2. Run the following commands:

    git clone --recursive https://github.com/lightgbm-org/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
cmake --build build --target testlightgbm -j4