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

4
Here is the guide for the build of LightGBM CLI version.
5

6
7
8
9
All instructions below are aimed to compile 64-bit version of LightGBM.
It is worth to compile 32-bit version only in very rare special cases of environmental limitations.
32-bit version is slow and untested, so use it on your own risk and don't forget to adjust some commands in this guide.

10
11
For the build of Python-package and R-package, please refer to `Python-package`_ and `R-package`_ folders respectively.

12
13
Also you can download artifacts of the latest successful build in master branch: |download artifacts|.

14
15
16
17
.. contents:: **Contents**
    :depth: 1
    :local:
    :backlinks: none
18

19
20
21
Windows
~~~~~~~

22
23
24
25
On Windows LightGBM can be built using

- **Visual Studio**;

26
- **CMake** and **VS Build Tools**;
27
28

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

30
31
Visual Studio (or VS Build Tools)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
32
33
34
35

With GUI
********

36
1. Install `Visual Studio`_ (2015 or newer).
37
38
39
40
41

2. Download `zip archive`_ and unzip it.

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

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

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

46
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release`` folder.
47
48
49
50

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

51
1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
52
53
54
55
56

2. Run the following commands:

   .. code::

57
     git clone --recursive https://github.com/microsoft/LightGBM
58
59
60
     cd LightGBM
     mkdir build
     cd build
61
     cmake -A x64 ..
62
63
     cmake --build . --target ALL_BUILD --config Release

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

66
67
MinGW-w64
^^^^^^^^^
68
69
70
71
72
73
74

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

2. Run the following commands:

   .. code::

75
     git clone --recursive https://github.com/microsoft/LightGBM
76
77
78
79
80
81
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" ..
     mingw32-make.exe -j4

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

84
**Note**: You may need to run the ``cmake -G "MinGW Makefiles" ..`` one more time if you encounter the ``sh.exe was found in your PATH`` error.
85

86
87
It is recommended to use **Visual Studio** for its 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>`__).
88
89

Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.
90

91
92
93
Linux
~~~~~

94
On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**.
95

96
1. Install `CMake`_.
97

98
99
100
101
2. Run the following commands:

   .. code::

102
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
103
104
105
     mkdir build ; cd build
     cmake ..
     make -j4
106
107
108

**Note**: glibc >= 2.14 is required.

109
Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.
110

111
112
macOS
~~~~~
113

114
115
116
117
On macOS LightGBM can be built using **CMake** and **Apple Clang** or **gcc**.

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

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

Nikita Titov's avatar
Nikita Titov committed
121
122
1. Install `CMake`_ (3.12 or higher):

123
   .. code::
Nikita Titov's avatar
Nikita Titov committed
124

125
     brew install cmake
fanliwen's avatar
fanliwen committed
126

127
2. Install **OpenMP**:
fanliwen's avatar
fanliwen committed
128
129
130
131

   .. code::

     brew install libomp
132
133
134
135
136

3. Run the following commands:

   .. code::

137
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
fanliwen's avatar
fanliwen committed
138
     mkdir build ; cd build
139
140
141
142
143
144
145
146
147
148
149

     # For Mojave (10.14)
     cmake \
       -DOpenMP_C_FLAGS="-Xpreprocessor -fopenmp -I$(brew --prefix libomp)/include" \
       -DOpenMP_C_LIB_NAMES="omp" \
       -DOpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp -I$(brew --prefix libomp)/include" \
       -DOpenMP_CXX_LIB_NAMES="omp" \
       -DOpenMP_omp_LIBRARY=$(brew --prefix libomp)/lib/libomp.dylib \
       ..

     # For High Sierra or earlier (<= 10.13)
fanliwen's avatar
fanliwen committed
150
     cmake ..
151

fanliwen's avatar
fanliwen committed
152
153
     make -j4

154
155
gcc
^^^
156

157
1. Install `CMake`_ (3.2 or higher):
158

159
   .. code::
160

161
     brew install cmake
162

163
2. Install **gcc**:
164

165
   .. code::
166

167
168
169
170
171
172
     brew install gcc

3. Run the following commands:

   .. code::

173
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
174
175
176
177
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
     mkdir build ; cd build
     cmake ..
     make -j4
178

179
Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.
180

181
182
183
Docker
~~~~~~

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

186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
Build Threadless Version (not Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default build version of LightGBM is based on OpenMP.
However, you can build the LightGBM without OpenMP support, but it is **strongly not recommended**.

Windows
^^^^^^^

On Windows 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`_ (2015 or newer).

2. Download `zip archive`_ and unzip it.

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.

223
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release`` folder.
224
225
226
227
228
229
230
231
232
233

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

1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).

2. Run the following commands:

   .. code::

234
     git clone --recursive https://github.com/microsoft/LightGBM
235
236
237
     cd LightGBM
     mkdir build
     cd build
238
     cmake -A x64 -DUSE_OPENMP=OFF ..
239
240
     cmake --build . --target ALL_BUILD --config Release

241
The ``.exe`` and ``.dll`` files will be in ``LightGBM/Release`` folder.
242
243
244
245
246
247
248
249
250
251

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

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

2. Run the following commands:

   .. code::

252
     git clone --recursive https://github.com/microsoft/LightGBM
253
254
255
256
257
258
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_OPENMP=OFF ..
     mingw32-make.exe -j4

259
The ``.exe`` and ``.dll`` files will be in ``LightGBM/`` folder.
260
261
262
263
264
265
266
267
268
269
270
271
272
273

**Note**: You may need to run the ``cmake -G "MinGW Makefiles" -DUSE_OPENMP=OFF ..`` one more time if you encounter the ``sh.exe was found in your PATH`` error.

Linux
^^^^^

On Linux version of LightGBM without OpenMP support can be built using **CMake** and **gcc** or **Clang**.

1. Install `CMake`_.

2. Run the following commands:

   .. code::

274
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
     mkdir build ; cd build
     cmake -DUSE_OPENMP=OFF ..
     make -j4

**Note**: glibc >= 2.14 is required.

macOS
^^^^^

On macOS version of LightGBM without OpenMP support can be built using **CMake** and **Apple Clang** or **gcc**.

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

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

1. Install `CMake`_ (3.12 or higher):

   .. code::

     brew install cmake

2. Run the following commands:

   .. code::

301
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
     mkdir build ; cd build
     cmake -DUSE_OPENMP=OFF ..
     make -j4

gcc
***

1. Install `CMake`_ (3.2 or higher):

   .. code::

     brew install cmake

2. Install **gcc**:

   .. code::

     brew install gcc

3. Run the following commands:

   .. code::

325
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
326
327
328
329
330
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
     mkdir build ; cd build
     cmake -DUSE_OPENMP=OFF ..
     make -j4

331
332
333
Build MPI Version
~~~~~~~~~~~~~~~~~

334
335
The default build version of LightGBM is based on socket. LightGBM also supports MPI.
`MPI`_ is a high performance communication approach with `RDMA`_ support.
336
337
338
339
340
341

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

Windows
^^^^^^^

342
343
344
345
On Windows MPI version of LightGBM can be built using

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

346
- **MS MPI**, **CMake** and **VS Build Tools**.
347

348
349
350
With GUI
********

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

353
2. Install `Visual Studio`_ (2015 or newer).
354
355
356
357
358

3. Download `zip archive`_ and unzip it.

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

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

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

363
The ``.exe`` file will be in ``LightGBM-master/windows/x64/Release_mpi`` folder.
364
365
366
367

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

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

370
2. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
371
372
373
374
375

3. Run the following commands:

   .. code::

376
     git clone --recursive https://github.com/microsoft/LightGBM
377
378
379
     cd LightGBM
     mkdir build
     cd build
380
     cmake -A x64 -DUSE_MPI=ON ..
381
382
     cmake --build . --target ALL_BUILD --config Release

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

385
**Note**: Building MPI version by **MinGW** is not supported due to the miss of MPI library in it.
386
387
388
389

Linux
^^^^^

390
On Linux MPI version of LightGBM can be built using **Open MPI**, **CMake** and **gcc** or **Clang**.
391

392
1. Install `Open MPI`_.
393

394
2. Install `CMake`_.
395

396
397
398
399
3. Run the following commands:

   .. code::

400
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
401
402
403
     mkdir build ; cd build
     cmake -DUSE_MPI=ON ..
     make -j4
404
405
406

**Note**: glibc >= 2.14 is required.

407
408
macOS
^^^^^
409

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

412
413
Apple Clang
***********
414

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

417
1. Install `CMake`_ (3.12 or higher):
418

419
   .. code::
420

421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
     brew install cmake

2. Install **OpenMP**:

   .. code::

     brew install libomp

3. Install **Open MPI**:

   .. code::

     brew install open-mpi

4. Run the following commands:

   .. code::

439
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
440
     mkdir build ; cd build
441
442
443
444
445
446
447
448
449
450
451
452

     # For Mojave (10.14)
     cmake \
       -DUSE_MPI=ON \
       -DOpenMP_C_FLAGS="-Xpreprocessor -fopenmp -I$(brew --prefix libomp)/include" \
       -DOpenMP_C_LIB_NAMES="omp" \
       -DOpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp -I$(brew --prefix libomp)/include" \
       -DOpenMP_CXX_LIB_NAMES="omp" \
       -DOpenMP_omp_LIBRARY=$(brew --prefix libomp)/lib/libomp.dylib \
       ..

     # For High Sierra or earlier (<= 10.13)
453
     cmake -DUSE_MPI=ON ..
454

455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
     make -j4

gcc
***

1. Install `CMake`_ (3.2 or higher):

   .. code::

     brew install cmake

2. Install **gcc**:

   .. code::

     brew install gcc

3. Install **Open MPI**:

   .. code::

     brew install open-mpi

4. Run the following commands:

   .. code::

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

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

Linux
^^^^^

494
495
On Linux GPU version of LightGBM can be built using **OpenCL**, **Boost**, **CMake** and **gcc** or **Clang**.

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** 3.2 or later.
509
510
511
512
513

To build LightGBM GPU version, run the following commands:

.. code::

514
  git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
515
516
  mkdir build ; cd build
  cmake -DUSE_GPU=1 ..
517
518
  # if you have installed NVIDIA CUDA to a customized location, you should specify paths to OpenCL headers and library like the following:
  # cmake -DUSE_GPU=1 -DOpenCL_LIBRARY=/usr/local/cuda/lib64/libOpenCL.so -DOpenCL_INCLUDE_DIR=/usr/local/cuda/include/ ..
519
520
521
522
523
  make -j4

Windows
^^^^^^^

524
On Windows GPU version of LightGBM can be built using **OpenCL**, **Boost**, **CMake** and **VS Build Tools** or **MinGW**.
525

526
If you use **MinGW**, the build procedure is similar to the build on Linux. Refer to `GPU Windows Compilation <./GPU-Windows.rst>`__ to get more details.
527

528
529
Following procedure is for the **MSVC** (Microsoft Visual C++) build.

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

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

536
   - For running on AMD, get AMD APP SDK.
537
538
539

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

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

Nikita Titov's avatar
Nikita Titov committed
542
3. Install `Boost Binaries`_.
543

544
   **Note**: Match your Visual C++ version:
545
546
547
   
   Visual Studio 2015 -> ``msvc-14.0-64.exe``,

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

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

4. Run the following commands:

   .. code::

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

565
   **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).
566
567
568
569

Docker
^^^^^^

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

572
573
574
Build HDFS Version
~~~~~~~~~~~~~~~~~~

575
HDFS version of LightGBM was tested on CDH-5.14.4 cluster.
576
577
578
579

Linux
^^^^^

580
On Linux HDFS version of LightGBM can be built using **CMake** and **gcc**.
581

582
1. Install `CMake`_.
fanliwen's avatar
fanliwen committed
583
584
585
586
587

2. Run the following commands:

   .. code::

588
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
fanliwen's avatar
fanliwen committed
589
590
     mkdir build ; cd build
     cmake -DUSE_HDFS=ON ..
591
592
593
594
595
596
     # if you have installed HDFS to a customized location, you should specify paths to HDFS headers (hdfs.h) and library (libhdfs.so) like the following:
     # cmake \
     #   -DUSE_HDFS=ON \
     #   -DHDFS_LIB="/opt/cloudera/parcels/CDH-5.14.4-1.cdh5.14.4.p0.3/lib64/libhdfs.so" \
     #   -DHDFS_INCLUDE_DIR="/opt/cloudera/parcels/CDH-5.14.4-1.cdh5.14.4.p0.3/include/" \
     #   ..
fanliwen's avatar
fanliwen committed
597
598
     make -j4

599
600
601
Build Java Wrapper
~~~~~~~~~~~~~~~~~~

602
603
604
605
606
By the following instructions you can generate a JAR file containing the LightGBM `C API <./Development-Guide.rst#c-api>`__ wrapped by **SWIG**.

Windows
^^^^^^^

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

609
610
VS Build Tools
**************
611

612
1. Install `Git for Windows`_, `CMake`_ (3.8 or higher) and `VS Build Tools`_ (**VS Build Tools** is not needed if **Visual Studio** (2015 or newer) is already installed).
613
614
615
616
617
618
619

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

3. Run the following commands:

   .. code::

620
     git clone --recursive https://github.com/microsoft/LightGBM
621
622
623
     cd LightGBM
     mkdir build
     cd build
624
     cmake -A x64 -DUSE_SWIG=ON ..
625
626
     cmake --build . --target ALL_BUILD --config Release

627
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/Release`` folder.
628
629
630
631
632
633
634
635
636
637
638
639

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:

   .. code::

640
     git clone --recursive https://github.com/microsoft/LightGBM
641
642
643
644
645
646
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_SWIG=ON ..
     mingw32-make.exe -j4

647
The ``.jar`` file will be in ``LightGBM/build`` folder and the ``.dll`` files will be in ``LightGBM/`` folder.
648
649
650

**Note**: You may need to run the ``cmake -G "MinGW Makefiles" -DUSE_SWIG=ON ..`` one more time if you encounter the ``sh.exe was found in your PATH`` error.

651
652
653
It is recommended to use **VS Build Tools (Visual Studio)** for its 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>`__).

654
655
656

Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.

657
658
659
Linux
^^^^^

660
On Linux Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **gcc** or **Clang**.
661

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

664
2. Run the following commands:
665

666
667
   .. code::

668
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
669
670
     mkdir build ; cd build
     cmake -DUSE_SWIG=ON ..
671
     make -j4
672

673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
macOS
^^^^^

On macOS Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMake** and **Apple Clang** or **gcc**.

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.

1. Install `CMake`_ (3.12 or higher):

   .. code::

     brew install cmake

2. Install **OpenMP**:

   .. code::

     brew install libomp

3. Run the following commands:

   .. code::

702
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
     mkdir build ; cd build

     # For Mojave (10.14)
     cmake \
       -DUSE_SWIG=ON \
       -DAPPLE_OUTPUT_DYLIB=ON \
       -DOpenMP_C_FLAGS="-Xpreprocessor -fopenmp -I$(brew --prefix libomp)/include" \
       -DOpenMP_C_LIB_NAMES="omp" \
       -DOpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp -I$(brew --prefix libomp)/include" \
       -DOpenMP_CXX_LIB_NAMES="omp" \
       -DOpenMP_omp_LIBRARY=$(brew --prefix libomp)/lib/libomp.dylib \
       ..

     # For High Sierra or earlier (<= 10.13)
     cmake -DUSE_SWIG=ON -DAPPLE_OUTPUT_DYLIB=ON ..

     make -j4

gcc
***

1. Install `CMake`_ (3.2 or higher):

   .. code::

     brew install cmake

2. Install **gcc**:

   .. code::

     brew install gcc

3. Run the following commands:

   .. code::

740
     git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM
741
742
743
744
745
746
747
748
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
     mkdir build ; cd build
     cmake -DUSE_SWIG=ON -DAPPLE_OUTPUT_DYLIB=ON ..
     make -j4

Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__.


749
750
751
.. |download artifacts| image:: ./_static/images/artifacts-not-available.svg
   :target: https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html

752
.. _Python-package: https://github.com/microsoft/LightGBM/tree/master/python-package
753

754
.. _R-package: https://github.com/microsoft/LightGBM/tree/master/R-package
755

756
.. _zip archive: https://github.com/microsoft/LightGBM/archive/master.zip
757

758
.. _Visual Studio: https://visualstudio.microsoft.com/downloads/
759
760
761
762
763

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

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

764
.. _VS Build Tools: https://visualstudio.microsoft.com/downloads/
765
766
767
768
769
770
771

.. _MinGW-w64: https://mingw-w64.org/doku.php/download

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

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

772
.. _MS MPI: https://www.microsoft.com/en-us/download/details.aspx?id=57467
773
774
775
776
777
778
779

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

Nikita Titov's avatar
Nikita Titov committed
780
.. _Boost Binaries: https://bintray.com/boostorg/release/boost-binaries/_latestVersion#files
781
782

.. _SWIG: http://www.swig.org/download.html