Installation-Guide.rst 25.3 KB
Newer Older
1
2
3
Installation Guide
==================

4
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.
5

6
7
8
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.
9

10
11
If you need to build a static library instead of a shared one, you can add ``-DBUILD_STATIC_LIB=ON`` to CMake flags.

12
Users who want to perform benchmarking can make LightGBM output time costs for different internal routines by adding ``-DUSE_TIMETAG=ON`` to CMake flags.
Guolin Ke's avatar
Guolin Ke committed
13

14
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.
Guolin Ke's avatar
Guolin Ke committed
15

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
.. _sanitizers:

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 <#build-c-unit-tests>`__ with sanitizers.

31
32
.. _nightly-builds:

33
You can also download the artifacts of the latest successful build on master branch (nightly builds) here: |download artifacts|.
34

35
36
37
38
.. contents:: **Contents**
    :depth: 1
    :local:
    :backlinks: none
39

40
41
42
Windows
~~~~~~~

43
44
45
46
On Windows LightGBM can be built using

- **Visual Studio**;

47
- **CMake** and **VS Build Tools**;
48
49

- **CMake** and **MinGW**.
50

51
52
Visual Studio (or VS Build Tools)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
53
54
55
56

With GUI
********

57
1. Install `Visual Studio`_ (2015 or newer).
58

59
2. Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download ``LightGBM-complete_source_code_zip.zip``, and unzip it.
60
61
62

3. Go to ``LightGBM-master/windows`` folder.

63
4. Open ``LightGBM.sln`` file with **Visual Studio**, choose ``Release`` configuration and click ``BUILD`` -> ``Build Solution (Ctrl+Shift+B)``.
64

65
   If you have errors about **Platform Toolset**, go to ``PROJECT`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
66

67
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release`` folder.
68
69
70
71

From Command Line
*****************

72
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).
73
74
75

2. Run the following commands:

76
   .. code:: console
77

78
     git clone --recursive https://github.com/microsoft/LightGBM
79
     cd LightGBM
80
81
     cmake -B build -S . -A x64
     cmake --build build --target ALL_BUILD --config Release
82

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

85
86
MinGW-w64
^^^^^^^^^
87
88
89
90
91

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

2. Run the following commands:

92
   .. code:: console
93

94
     git clone --recursive https://github.com/microsoft/LightGBM
95
     cd LightGBM
96
97
     cmake -B build -S . -G "MinGW Makefiles"
     cmake --build build -j4
98

99
The ``.exe`` and ``.dll`` files will be in ``LightGBM/`` folder.
100

101
**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.
102

103
It is recommended that you use **Visual Studio** since it has better multithreading efficiency in **Windows** for many-core systems
104
(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>`__).
105

106
107
108
Linux
~~~~~

109
On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**.
110

111
1. Install `CMake`_.
112

113
114
2. Run the following commands:

115
   .. code:: sh
116

117
118
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
119
120
     cmake -B build -S .
     cmake --build build -j4
121

122
123
**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).

124
125
126
127
128
129
130
131
132
Using ``Ninja``
^^^^^^^^^^^^^^^

On Linux, LightGBM can also be built with `Ninja <https://ninja-build.org/>`__ instead of ``make``.

.. code:: sh

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
133
134
     cmake -B build -S . -G 'Ninja'
     cmake --build build -j2
135

136
137
macOS
~~~~~
138

139
On macOS LightGBM can be installed using **Homebrew**, or can be built using **CMake** and **Apple Clang** or **gcc**.
140
141
142

Apple Clang
^^^^^^^^^^^
fanliwen's avatar
fanliwen committed
143

144
Only **Apple Clang** version 8.1 or higher is supported.
fanliwen's avatar
fanliwen committed
145

146
147
148
Install Using ``Homebrew``
**************************

149
.. code:: sh
150
151
152
153
154
155

  brew install lightgbm

Build from GitHub
*****************

156
1. Install `CMake`_ :
Nikita Titov's avatar
Nikita Titov committed
157

158
   .. code:: sh
Nikita Titov's avatar
Nikita Titov committed
159

160
     brew install cmake
fanliwen's avatar
fanliwen committed
161

162
2. Install **OpenMP**:
fanliwen's avatar
fanliwen committed
163

164
   .. code:: sh
fanliwen's avatar
fanliwen committed
165
166

     brew install libomp
167
168
169

3. Run the following commands:

170
   .. code:: sh
171

172
173
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
174
175
     cmake -B build -S .
     cmake --build build -j4
fanliwen's avatar
fanliwen committed
176

177
178
gcc
^^^
179

180
1. Install `CMake`_ :
181

182
   .. code:: sh
183

184
     brew install cmake
185

186
2. Install **gcc**:
187

188
   .. code:: sh
189

190
191
192
193
     brew install gcc

3. Run the following commands:

194
   .. code:: sh
195

196
197
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
198
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
199
200
     cmake -B build -S .
     cmake --build build -j4
201
202
203
204

Docker
~~~~~~

205
Refer to `Docker folder <https://github.com/microsoft/LightGBM/tree/master/docker>`__.
206

207
208
209
210
Build Threadless Version (not Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default build version of LightGBM is based on OpenMP.
211
You can build LightGBM without OpenMP support but it is **strongly not recommended**.
212
213
214
215

Windows
^^^^^^^

216
On Windows a version of LightGBM without OpenMP support can be built using
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231

- **Visual Studio**;

- **CMake** and **VS Build Tools**;

- **CMake** and **MinGW**.

Visual Studio (or VS Build Tools)
*********************************

With GUI
--------

1. Install `Visual Studio`_ (2015 or newer).

232
2. Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download ``LightGBM-complete_source_code_zip.zip``, and unzip it.
233
234
235
236
237
238
239
240
241
242
243

3. Go to ``LightGBM-master/windows`` folder.

4. Open ``LightGBM.sln`` file with **Visual Studio**.

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

   If you have errors about **Platform Toolset**, go to ``PROJECT`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.

244
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release`` folder.
245
246
247
248

From Command Line
-----------------

249
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).
250
251
252

2. Run the following commands:

253
   .. code:: console
254

255
     git clone --recursive https://github.com/microsoft/LightGBM
256
     cd LightGBM
257
258
     cmake -B build -S . -A x64 -DUSE_OPENMP=OFF
     cmake --build build --target ALL_BUILD --config Release
259

260
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
261
262
263
264
265
266
267
268

MinGW-w64
*********

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

2. Run the following commands:

269
   .. code:: console
270

271
     git clone --recursive https://github.com/microsoft/LightGBM
272
     cd LightGBM
273
274
     cmake -B build -S . -G "MinGW Makefiles" -DUSE_OPENMP=OFF
     cmake --build build -j4
275

276
The ``.exe`` and ``.dll`` files will be in ``LightGBM/`` folder.
277

278
**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.
279
280
281
282

Linux
^^^^^

283
On Linux a version of LightGBM without OpenMP support can be built using **CMake** and **gcc** or **Clang**.
284
285
286
287
288

1. Install `CMake`_.

2. Run the following commands:

289
   .. code:: sh
290

291
292
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
293
294
     cmake -B build -S . -DUSE_OPENMP=OFF
     cmake --build build -j4
295
296
297
298

macOS
^^^^^

299
On macOS a version of LightGBM without OpenMP support can be built using **CMake** and **Apple Clang** or **gcc**.
300
301
302
303
304
305

Apple Clang
***********

Only **Apple Clang** version 8.1 or higher is supported.

306
1. Install `CMake`_ :
307

308
   .. code:: sh
309
310
311
312
313

     brew install cmake

2. Run the following commands:

314
   .. code:: sh
315

316
317
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
318
319
     cmake -B build -S . -DUSE_OPENMP=OFF
     cmake --build build -j4
320
321
322
323

gcc
***

324
1. Install `CMake`_ :
325

326
   .. code:: sh
327
328
329
330
331

     brew install cmake

2. Install **gcc**:

332
   .. code:: sh
333
334
335
336
337

     brew install gcc

3. Run the following commands:

338
   .. code:: sh
339

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

346
347
348
Build MPI Version
~~~~~~~~~~~~~~~~~

349
350
The default build version of LightGBM is based on socket. LightGBM also supports MPI.
`MPI`_ is a high performance communication approach with `RDMA`_ support.
351

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

Windows
^^^^^^^

357
On Windows an MPI version of LightGBM can be built using
358
359
360

- **MS MPI** and **Visual Studio**;

361
- **MS MPI**, **CMake** and **VS Build Tools**.
362

363
364
365
With GUI
********

366
1. You need to install `MS MPI`_ first. Both ``msmpisdk.msi`` and ``msmpisetup.exe`` are needed.
367

368
2. Install `Visual Studio`_ (2015 or newer).
369

370
3. Navigate to one of the releases at https://github.com/microsoft/LightGBM/releases, download ``LightGBM-complete_source_code_zip.zip``, and unzip it.
371
372
373

4. Go to ``LightGBM-master/windows`` folder.

374
5. Open ``LightGBM.sln`` file with **Visual Studio**, choose ``Release_mpi`` configuration and click ``BUILD`` -> ``Build Solution (Ctrl+Shift+B)``.
375

376
   If you have errors about **Platform Toolset**, go to ``PROJECT`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
377

378
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release_mpi`` folder.
379
380
381
382

From Command Line
*****************

383
1. You need to install `MS MPI`_ first. Both ``msmpisdk.msi`` and ``msmpisetup.exe`` are needed.
384

385
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).
386
387
388

3. Run the following commands:

389
   .. code:: console
390

391
     git clone --recursive https://github.com/microsoft/LightGBM
392
     cd LightGBM
393
394
     cmake -B build -S . -A x64 -DUSE_MPI=ON
     cmake --build build --target ALL_BUILD --config Release
395

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

398
**Note**: Building MPI version by **MinGW** is not supported due to the miss of MPI library in it.
399
400
401
402

Linux
^^^^^

403
On Linux an MPI version of LightGBM can be built using **Open MPI**, **CMake** and **gcc** or **Clang**.
404

405
1. Install `Open MPI`_.
406

407
2. Install `CMake`_.
408

409
410
3. Run the following commands:

411
   .. code:: sh
412

413
414
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
415
416
     cmake -B build -S . -DUSE_MPI=ON
     cmake --build build -j4
417

418
419
**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).

420
421
macOS
^^^^^
422

423
On macOS an MPI version of LightGBM can be built using **Open MPI**, **CMake** and **Apple Clang** or **gcc**.
424

425
426
Apple Clang
***********
427

428
Only **Apple Clang** version 8.1 or higher is supported.
429

430
1. Install `CMake`_ :
431

432
   .. code:: sh
433

434
435
436
437
     brew install cmake

2. Install **OpenMP**:

438
   .. code:: sh
439
440
441
442
443

     brew install libomp

3. Install **Open MPI**:

444
   .. code:: sh
445
446
447
448
449

     brew install open-mpi

4. Run the following commands:

450
   .. code:: sh
451

452
453
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
454
455
     cmake -B build -S . -DUSE_MPI=ON
     cmake --build build -j4
456
457
458
459

gcc
***

460
1. Install `CMake`_ :
461

462
   .. code:: sh
463
464
465
466
467

     brew install cmake

2. Install **gcc**:

468
   .. code:: sh
469
470
471
472
473

     brew install gcc

3. Install **Open MPI**:

474
   .. code:: sh
475
476
477
478
479

     brew install open-mpi

4. Run the following commands:

480
   .. code:: sh
481

482
483
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
484
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
485
486
     cmake -B build -S . -DUSE_MPI=ON
     cmake --build build -j4
487
488
489
490
491
492
493

Build GPU Version
~~~~~~~~~~~~~~~~~

Linux
^^^^^

494
On Linux a GPU version of LightGBM (``device_type=gpu``) can be built using **OpenCL**, **Boost**, **CMake** and **gcc** or **Clang**.
495

496
497
The following dependencies should be installed before compilation:

498
-  **OpenCL** 1.2 headers and libraries, which is usually provided by GPU manufacture.
499

500
   The generic OpenCL ICD packages (for example, Debian package ``ocl-icd-libopencl1`` and ``ocl-icd-opencl-dev``) can also be used.
501

502
-  **libboost** 1.56 or later (1.61 or later is recommended).
503
504
505
506
507

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

508
-  **CMake**
509
510
511

To build LightGBM GPU version, run the following commands:

512
.. code:: sh
513

514
515
  git clone --recursive https://github.com/microsoft/LightGBM
  cd LightGBM
516
  cmake -B build -S . -DUSE_GPU=1
517
  # if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following:
518
519
  # 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
520

521
522
**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).

523
524
525
Windows
^^^^^^^

526
On Windows a GPU version of LightGBM (``device_type=gpu``) can be built using **OpenCL**, **Boost**, **CMake** and **VS Build Tools** or **MinGW**.
527

528
If you use **MinGW**, the build procedure is similar to the build on Linux.
529

530
531
Following procedure is for the **MSVC** (Microsoft Visual C++) build.

532
1. Install `Git for Windows`_, `CMake`_ and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is installed).
533
534
535
536
537

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

   - For running on Intel, get `Intel SDK for OpenCL`_.

538
   - For running on AMD, get AMD APP SDK.
539
540
541

   - For running on NVIDIA, get `CUDA Toolkit`_.

542
543
   Further reading and correspondence table: `GPU SDK Correspondence and Device Targeting Table <./GPU-Targets.rst>`__.

Nikita Titov's avatar
Nikita Titov committed
544
3. Install `Boost Binaries`_.
545

546
   **Note**: Match your Visual C++ version:
547

548
549
   Visual Studio 2015 -> ``msvc-14.0-64.exe``,

550
551
   Visual Studio 2017 -> ``msvc-14.1-64.exe``,

552
553
554
   Visual Studio 2019 -> ``msvc-14.2-64.exe``,

   Visual Studio 2022 -> ``msvc-14.3-64.exe``.
555
556
557

4. Run the following commands:

558
   .. code:: console
559

560
     git clone --recursive https://github.com/microsoft/LightGBM
561
     cd LightGBM
562
     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
563
     # if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following:
564
565
     # 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 --build build --target ALL_BUILD --config Release
566

567
   **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).
568
569
570
571

Docker
^^^^^^

572
Refer to `GPU Docker folder <https://github.com/microsoft/LightGBM/tree/master/docker/gpu>`__.
573

574
575
Build CUDA Version
~~~~~~~~~~~~~~~~~~
576

577
The `original GPU build <#build-gpu-version>`__ of LightGBM (``device_type=gpu``) is based on OpenCL.
578

579
580
The CUDA-based build (``device_type=cuda``) is a separate implementation.
Use this version in Linux environments with an NVIDIA GPU with compute capability 6.0 or higher.
581
582
583
584

Linux
^^^^^

585
On Linux a CUDA version of LightGBM can be built using **CUDA**, **CMake** and **gcc** or **Clang**.
586
587
588

The following dependencies should be installed before compilation:

589
-  **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.
590

591
-  **CMake**
592
593
594

To build LightGBM CUDA version, run the following commands:

595
.. code:: sh
596

597
598
  git clone --recursive https://github.com/microsoft/LightGBM
  cd LightGBM
599
600
  cmake -B build -S . -DUSE_CUDA=1
  cmake --build build -j4
601

602
603
**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).

604
605
606
607
608
609
610
611
612
613
614
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.

615
616
617
Build Java Wrapper
~~~~~~~~~~~~~~~~~~

618
Using the following instructions you can generate a JAR file containing the LightGBM `C API <./Development-Guide.rst#c-api>`__ wrapped by **SWIG**.
619
620
621
622

Windows
^^^^^^^

623
On Windows a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **VS Build Tools** or **MinGW**.
624

625
626
VS Build Tools
**************
627

628
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).
629
630
631
632
633

2. Install `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).

3. Run the following commands:

634
   .. code:: console
635

636
     git clone --recursive https://github.com/microsoft/LightGBM
637
     cd LightGBM
638
639
     cmake -B build -S . -A x64 -DUSE_SWIG=ON
     cmake --build build --target ALL_BUILD --config Release
640

641
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/Release`` folder.
642
643
644
645
646
647
648
649
650
651

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

3. Run the following commands:

652
   .. code:: console
653

654
     git clone --recursive https://github.com/microsoft/LightGBM
655
     cd LightGBM
656
657
     cmake -B build -S . -G "MinGW Makefiles" -DUSE_SWIG=ON
     cmake --build build -j4
658

659
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/`` folder.
660

661
**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.
662

663
It is recommended to use **VS Build Tools (Visual Studio)** since it has better multithreading efficiency in **Windows** for many-core systems
664
665
(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
667
668
Linux
^^^^^

669
On Linux a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **gcc** or **Clang**.
670

671
1. Install `CMake`_, `SWIG`_ and **Java** (also make sure that ``JAVA_HOME`` is set properly).
672

673
2. Run the following commands:
674

675
   .. code:: sh
676

677
678
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
679
680
     cmake -B build -S . -DUSE_SWIG=ON
     cmake --build build -j4
681

682
683
**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).

684
685
686
macOS
^^^^^

687
On macOS a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **Apple Clang** or **gcc**.
688
689
690
691
692
693
694
695
696

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.

Apple Clang
***********

Only **Apple Clang** version 8.1 or higher is supported.

697
1. Install `CMake`_ :
698

699
   .. code:: sh
700
701
702
703
704

     brew install cmake

2. Install **OpenMP**:

705
   .. code:: sh
706
707
708
709
710

     brew install libomp

3. Run the following commands:

711
   .. code:: sh
712

713
714
     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
715
     cmake -B build -S . -DUSE_SWIG=ON
716
     cmake --build build -j4
717
718
719
720

gcc
***

721
1. Install `CMake`_ :
722

723
   .. code:: sh
724
725
726
727
728

     brew install cmake

2. Install **gcc**:

729
   .. code:: sh
730
731
732
733
734

     brew install gcc

3. Run the following commands:

735
   .. code:: sh
736

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

743
744
745
746
747
748
749
750
Build C++ Unit Tests
~~~~~~~~~~~~~~~~~~~~

Windows
^^^^^^^

On Windows, C++ unit tests of LightGBM can be built using **CMake** and **VS Build Tools**.

751
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).
752
753
754

2. Run the following commands:

755
   .. code:: console
756
757
758

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
759
760
     cmake -B build -S . -A x64 -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
     cmake --build build --target testlightgbm --config Debug
761
762
763
764
765
766
767
768
769
770
771
772

The ``.exe`` file will be in ``LightGBM/Debug`` folder.

Linux
^^^^^

On Linux a C++ unit tests of LightGBM can be built using **CMake** and **gcc** or **Clang**.

1. Install `CMake`_.

2. Run the following commands:

773
   .. code:: sh
774
775
776

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
777
778
     cmake -B build -S . -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
     cmake --build build --target testlightgbm -j4
779
780
781
782
783
784
785
786
787
788
789

macOS
^^^^^

On macOS a C++ unit tests of LightGBM can be built using **CMake** and **Apple Clang** or **gcc**.

Apple Clang
***********

Only **Apple Clang** version 8.1 or higher is supported.

790
1. Install `CMake`_ :
791

792
   .. code:: sh
793
794
795
796
797

     brew install cmake

2. Run the following commands:

798
   .. code:: sh
799
800
801

     git clone --recursive https://github.com/microsoft/LightGBM
     cd LightGBM
802
803
     cmake -B build -S . -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
     cmake --build build --target testlightgbm -j4
804
805
806
807

gcc
***

808
1. Install `CMake`_ :
809

810
   .. code:: sh
811
812
813
814
815

     brew install cmake

2. Install **gcc**:

816
   .. code:: sh
817
818
819
820
821

     brew install gcc

3. Run the following commands:

822
   .. code:: sh
823
824
825
826

     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
827
828
     cmake -B build -S . -DBUILD_CPP_TEST=ON -DUSE_OPENMP=OFF
     cmake --build build --target testlightgbm -j4
829

830

831
832
833
.. |download artifacts| image:: ./_static/images/artifacts-not-available.svg
   :target: https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html

834
.. _Python-package: https://github.com/microsoft/LightGBM/tree/master/python-package
835

836
.. _R-package: https://github.com/microsoft/LightGBM/tree/master/R-package
837

838
.. _Visual Studio: https://visualstudio.microsoft.com/downloads/
839
840
841
842
843

.. _Git for Windows: https://git-scm.com/download/win

.. _CMake: https://cmake.org/

844
.. _VS Build Tools: https://visualstudio.microsoft.com/downloads/
845

846
.. _MinGW-w64: https://www.mingw-w64.org/downloads/
847
848
849
850
851

.. _MPI: https://en.wikipedia.org/wiki/Message_Passing_Interface

.. _RDMA: https://en.wikipedia.org/wiki/Remote_direct_memory_access

852
.. _MS MPI: https://learn.microsoft.com/en-us/message-passing-interface/microsoft-mpi-release-notes
853
854
855
856
857
858
859

.. _Open MPI: https://www.open-mpi.org/

.. _Intel SDK for OpenCL: https://software.intel.com/en-us/articles/opencl-drivers

.. _CUDA Toolkit: https://developer.nvidia.com/cuda-downloads

860
.. _Boost Binaries: https://sourceforge.net/projects/boost/files/boost-binaries/
861

James Lamb's avatar
James Lamb committed
862
.. _SWIG: https://www.swig.org/download.html
863
864

.. _this detailed guide: https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html
865
866

.. _following docs: https://github.com/google/sanitizers/wiki