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

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

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

8
9
10
11
12
13
14
15
16
17
**Contents**

-  `Windows <#windows>`__

-  `Linux <#linux>`__

-  `macOS <#macos>`__

-  `Docker <#docker>`__

18
19
- `Threadless Version (not Recommended) <#build-threadless-version-not-recommended>`__

20
21
22
23
24
25
26
27
-  `MPI Version <#build-mpi-version>`__

-  `GPU Version <#build-gpu-version>`__

-  `HDFS Version <#build-hdfs-version>`__

-  `Java Wrapper <#build-java-wrapper>`__

28
29
30
Windows
~~~~~~~

31
32
33
34
On Windows LightGBM can be built using

- **Visual Studio**;

35
- **CMake** and **VS Build Tools**;
36
37

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

39
40
Visual Studio (or VS Build Tools)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
41
42
43
44

With GUI
********

45
1. Install `Visual Studio`_ (2015 or newer).
46
47
48
49
50

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

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

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

53
   If you have errors about **Platform Toolset**, go to ``PROJECT`` -> ``Properties`` -> ``Configuration Properties`` -> ``General`` and select the toolset installed on your machine.
54
55
56
57
58
59

The exe file will be in ``LightGBM-master/windows/x64/Release`` folder.

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

60
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).
61
62
63
64
65
66
67
68
69
70
71
72
73
74

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..
     cmake --build . --target ALL_BUILD --config Release

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

75
76
MinGW-w64
^^^^^^^^^
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

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

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" ..
     mingw32-make.exe -j4

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

93
**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.
94

95
96
97
It is recommended to use **Visual Studio** for its better multithreading efficiency in **Windows** for many-core systems (see `FAQ <./FAQ.rst#lightgbm>`__ Question 4 and Question 8).

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

99
100
101
Linux
~~~~~

102
On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**.
103

104
1. Install `CMake`_.
105

106
107
108
109
110
111
112
113
2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake ..
     make -j4
114
115
116

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

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

119
120
macOS
~~~~~
121

122
123
124
125
On macOS LightGBM can be built using **CMake** and **Apple Clang** or **gcc**.

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

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

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

131
   .. code::
Nikita Titov's avatar
Nikita Titov committed
132

133
     brew install cmake
fanliwen's avatar
fanliwen committed
134

135
2. Install **OpenMP**:
fanliwen's avatar
fanliwen committed
136
137
138
139

   .. code::

     brew install libomp
140
141
142
143
144

3. Run the following commands:

   .. code::

fanliwen's avatar
fanliwen committed
145
146
147
148
149
     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake ..
     make -j4

150
151
gcc
^^^
152

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

155
   .. code::
156

157
     brew install cmake
158

159
2. Install **gcc**:
160

161
   .. code::
162

163
164
165
166
167
168
169
170
171
172
173
     brew install gcc

3. Run the following commands:

   .. code::

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

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

177
178
179
180
181
Docker
~~~~~~

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

182
183
184
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
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
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
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
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.

The exe file will be in ``LightGBM-master/windows/x64/Release`` folder.

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

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

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_OPENMP=OFF ..
     cmake --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:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_OPENMP=OFF ..
     mingw32-make.exe -j4

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

**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::

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

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

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

327
328
329
Build MPI Version
~~~~~~~~~~~~~~~~~

330
331
The default build version of LightGBM is based on socket. LightGBM also supports MPI.
`MPI`_ is a high performance communication approach with `RDMA`_ support.
332
333
334
335
336
337

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

Windows
^^^^^^^

338
339
340
341
On Windows MPI version of LightGBM can be built using

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

342
- **MS MPI**, **CMake** and **VS Build Tools**.
343

344
345
346
With GUI
********

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

349
2. Install `Visual Studio`_ (2015 or newer).
350
351
352
353
354

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

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

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

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

The exe file will be in ``LightGBM-master/windows/x64/Release_mpi`` folder.

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

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

366
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).
367
368
369
370
371
372
373
374
375
376
377
378
379
380

3. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_MPI=ON ..
     cmake --build . --target ALL_BUILD --config Release

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

381
**Note**: Building MPI version by **MinGW** is not supported due to the miss of MPI library in it.
382
383
384
385

Linux
^^^^^

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

388
1. Install `Open MPI`_.
389

390
2. Install `CMake`_.
391

392
393
394
395
396
397
398
399
3. Run the following commands:

   .. code::

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

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

403
404
macOS
^^^^^
405

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

408
409
Apple Clang
***********
410

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

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

415
   .. code::
416

417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
     brew install cmake

2. Install **OpenMP**:

   .. code::

     brew install libomp

3. Install **Open MPI**:

   .. code::

     brew install open-mpi

4. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake -DUSE_MPI=ON ..
     make -j4

gcc
***

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

   .. code::

     brew install cmake

2. Install **gcc**:

   .. code::

     brew install gcc

3. Install **Open MPI**:

   .. code::

     brew install open-mpi

4. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     export CXX=g++-7 CC=gcc-7  # replace "7" with version of gcc installed on your machine
     mkdir build ; cd build
     cmake -DUSE_MPI=ON ..
     make -j4
470
471
472
473
474
475
476

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

Linux
^^^^^

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

479
480
The following dependencies should be installed before compilation:

481
-  **OpenCL** 1.2 headers and libraries, which is usually provided by GPU manufacture.
482
483
484

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

485
-  **libboost** 1.56 or later (1.61 or later is recommended).
486
487
488
489
490

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

491
-  **CMake** 3.2 or later.
492
493
494
495
496
497
498
499

To build LightGBM GPU version, run the following commands:

.. code::

  git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
  mkdir build ; cd build
  cmake -DUSE_GPU=1 ..
500
501
  # 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/ ..
502
503
504
505
506
  make -j4

Windows
^^^^^^^

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

509
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.
510

511
512
Following procedure is for the **MSVC** (Microsoft Visual C++) build.

513
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).
514
515
516
517
518

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

519
   - For running on AMD, get AMD APP SDK.
520
521
522

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

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

525
526
3. Install `Boost Binary`_.

527
   **Note**: Match your Visual C++ version:
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
   
   Visual Studio 2015 -> ``msvc-14.0-64.exe``,

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

4. Run the following commands:

   .. code::

     Set BOOST_ROOT=C:\local\boost_1_64_0\
     Set BOOST_LIBRARYDIR=C:\local\boost_1_64_0\lib64-msvc-14.0
     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_GPU=1 ..
     cmake --build . --target ALL_BUILD --config Release

546
   **Note**: ``C:\local\boost_1_64_0\`` and ``C:\local\boost_1_64_0\lib64-msvc-14.0`` are locations of your **Boost** binaries. You also can set them to the environment variable to avoid ``Set ...`` commands when build.
547
548
549
550
551
552

Docker
^^^^^^

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

553
554
555
Build HDFS Version
~~~~~~~~~~~~~~~~~~

556
**Note**: Installation process of HDFS version is untested.
557
558
559
560

Linux
^^^^^

561
On Linux HDFS version of LightGBM can be built using **CMake** and **gcc** or **Clang**.
562

563
1. Install `CMake`_.
fanliwen's avatar
fanliwen committed
564
565
566
567
568
569
570
571
572
573

2. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake -DUSE_HDFS=ON ..
     make -j4

574
575
576
Build Java Wrapper
~~~~~~~~~~~~~~~~~~

577
578
579
580
581
By the following instructions you can generate a JAR file containing the LightGBM `C API <./Development-Guide.rst#c-api>`__ wrapped by **SWIG**.

Windows
^^^^^^^

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

584
585
VS Build Tools
**************
586

587
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).
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625

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

3. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DUSE_SWIG=ON ..
     cmake --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).

3. Run the following commands:

   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM
     cd LightGBM
     mkdir build
     cd build
     cmake -G "MinGW Makefiles" -DUSE_SWIG=ON ..
     mingw32-make.exe -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 -G "MinGW Makefiles" -DUSE_SWIG=ON ..`` one more time if you encounter the ``sh.exe was found in your PATH`` error.

626
It is recommended to use **VS Build Tools (Visual Studio)** for its better multithreading efficiency in **Windows** for many-core systems (see `FAQ <./FAQ.rst#lightgbm>`__ Question 4 and Question 8).
627
628
629

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

630
631
632
Linux
^^^^^

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

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

637
2. Run the following commands:
638

639
640
641
642
643
   .. code::

     git clone --recursive https://github.com/Microsoft/LightGBM ; cd LightGBM
     mkdir build ; cd build
     cmake -DUSE_SWIG=ON ..
644
     make -j4
645

646
647
648
649
650
651
.. _Python-package: https://github.com/Microsoft/LightGBM/tree/master/python-package

.. _R-package: https://github.com/Microsoft/LightGBM/tree/master/R-package

.. _zip archive: https://github.com/Microsoft/LightGBM/archive/master.zip

652
.. _Visual Studio: https://visualstudio.microsoft.com/downloads/
653
654
655
656
657

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

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

658
.. _VS Build Tools: https://visualstudio.microsoft.com/downloads/
659
660
661
662
663
664
665

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

666
.. _MS MPI: https://www.microsoft.com/en-us/download/details.aspx?id=57467
667
668
669
670
671
672
673
674

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

.. _Boost Binary: https://sourceforge.net/projects/boost/files/boost-binaries/1.64.0/
675
676

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