Hendrik/xgboost
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reorganize the installation documents. (#6877)

Browse Source 
* Split up installation and building from source.
* Use consistent section titles.

Co-authored-by: Philip Hyunsu Cho <chohyu01@cs.washington.edu>
This commit is contained in:
Jiaming Yuan 2021-04-22 04:48:32 +08:00 committed by GitHub
parent 74b41637de
commit 896aede340
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 427 additions and 398 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/R-package/index.rst
View File

@ -12,7 +12,7 @@ You have found the XGBoost R Package!
***********
Get Started
***********
* Checkout the :doc:`Installation Guide </build>` contains instructions to install xgboost, and :doc:`Tutorials </tutorials/index>` for examples on how to use XGBoost for various tasks.
* Checkout the :doc:`Installation Guide </install>` contains instructions to install xgboost, and :doc:`Tutorials </tutorials/index>` for examples on how to use XGBoost for various tasks.
* Read the `API documentation <https://cran.r-project.org/web/packages/xgboost/xgboost.pdf>`_.
* Please visit `Walk-through Examples <https://github.com/dmlc/xgboost/tree/master/R-package/demo>`_.

302
doc/build.rst
View File

@ -1,45 +1,22 @@
##################
Installation Guide
##################
####################
Building From Source
####################
.. note:: Pre-built binary wheel for Python: now with GPU support
If you are planning to use Python, consider installing XGBoost from a pre-built binary wheel, to avoid the trouble of building XGBoost from the source. You may download and install it by running
.. code-block:: bash
pip3 install xgboost
* The binary wheel will support the GPU algorithm (``gpu_hist``) on machines with NVIDIA GPUs. Please note that **training with multiple GPUs is only supported for Linux platform**. See :doc:`gpu/index`.
* Currently, we provide binary wheels for 64-bit Linux, macOS and Windows.
* Nightly builds are available. You can go to `this page
<https://s3-us-west-2.amazonaws.com/xgboost-nightly-builds/list.html>`_, find the
wheel with the commit id you want and install it with pip:
.. code-block:: bash
pip install <url to the wheel>
.. note:: (EXPERIMENTAL) Pre-built binary package for R: now with GPU support
If you are planning to use R, consider installing ``{xgboost}`` from a pre-built binary package, to avoid the trouble of building XGBoost from the source. The binary package will let you use the GPU algorithm (``gpu_hist``) out of the box, as long as your machine has NVIDIA GPUs.
Download the binary package from the Releases page. The file name will be of the form ``xgboost_r_gpu_linux_[version].tar.gz``. Then install XGBoost by running:
.. code-block:: bash
# Install dependencies
R -q -e "install.packages(c('data.table', 'magrittr', 'jsonlite', 'remotes'))"
# Install XGBoost
R CMD INSTALL ./xgboost_r_gpu_linux.tar.gz
Currently, we provide the binary package for 64-bit Linux.
This page gives instructions on how to build and install XGBoost from the source code on various
systems. If the instructions do not work for you, please feel free to ask questions at
`the user forum <https://discuss.xgboost.ai>`_.
****************************
Building XGBoost from source
****************************
This page gives instructions on how to build and install XGBoost from scratch on various systems.
.. note:: Pre-built binary is available: now with GPU support
Consider installing XGBoost from a pre-built binary, to avoid the trouble of building XGBoost from the source. Checkout :doc:`Installation Guide </install>`.
.. contents:: Contents
*************************
Obtaining the Source Code
*************************
To obtain the development repository of XGBoost, one needs to use ``git``.
.. note:: Use of Git submodules
@ -56,11 +33,6 @@ For windows users who use github tools, you can open the git shell and type the
git submodule init
git submodule update
Please refer to `Trouble Shooting`_ section first if you have any problem
during installation. If the instructions do not work for you, please feel free
to ask questions at `the user forum <https://discuss.xgboost.ai>`_.
.. contents:: Contents
.. _build_shared_lib:
@ -68,58 +40,40 @@ to ask questions at `the user forum <https://discuss.xgboost.ai>`_.
Building the Shared Library
***************************
Our goal is to build the shared library:
This section describes the procedure to build the shared library and CLI interface
independently. For building language specific package, see corresponding sections in this
document.
- On Linux/OSX the target library is ``libxgboost.so``
- On Linux and other UNIX-like systems, the target library is ``libxgboost.so``
- On MacOS, the target library is ``libxgboost.dylib``
- On Windows the target library is ``xgboost.dll``
This shared library is used by different language bindings (with some additions depending
on the binding you choose). For building language specific package, see corresponding
sections in this document. The minimal building requirement is
on the binding you choose). The minimal building requirement is
- A recent C++ compiler supporting C++11 (g++-5.0 or higher)
- CMake 3.13 or higher.
For a list of CMake options, see ``#-- Options`` in CMakeLists.txt on top level of source tree.
For a list of CMake options like GPU support, see ``#-- Options`` in CMakeLists.txt on top
level of source tree.
Building on Linux distributions
===============================
Building on Linux and other UNIX-like systems
=============================================
On Ubuntu, one builds XGBoost by running CMake:
After obtaining the source code, one builds XGBoost by running CMake:
.. code-block:: bash
git clone --recursive https://github.com/dmlc/xgboost
cd xgboost
mkdir build
cd build
cmake ..
make -j$(nproc)
Building on OSX
===============
Building on MacOS
=================
Install with pip: simple method
--------------------------------
First, obtain the OpenMP library (``libomp``) with Homebrew (https://brew.sh/) to enable multi-threading (i.e. using multiple CPU threads for training):
.. code-block:: bash
brew install libomp
Then install XGBoost with ``pip``:
.. code-block:: bash
pip3 install xgboost
You might need to run the command with ``--user`` flag if you run into permission errors.
Build from the source code - advanced method
--------------------------------------------
Obtain ``libomp`` from Homebrew:
Obtain ``libomp`` from `Homebrew <https://brew.sh/>`_:
.. code-block:: bash
@ -141,7 +95,7 @@ Create the ``build/`` directory and invoke CMake. After invoking CMake, you can
cmake ..
make -j4
You may now continue to `Python Package Installation`_.
You may now continue to :ref:`build_python`.
Building on Windows
===================
@ -153,11 +107,9 @@ We recommend you use `Git for Windows <https://git-for-windows.github.io/>`_, as
git submodule init
git submodule update
XGBoost support compilation with Microsoft Visual Studio and MinGW.
Compile XGBoost with Microsoft Visual Studio
--------------------------------------------
To build with Visual Studio, we will need CMake. Make sure to install a recent version of CMake. Then run the following from the root of the XGBoost directory:
XGBoost support compilation with Microsoft Visual Studio and MinGW. To build with Visual
Studio, we will need CMake. Make sure to install a recent version of CMake. Then run the
following from the root of the XGBoost directory:
.. code-block:: bash
@ -170,13 +122,17 @@ To build with Visual Studio, we will need CMake. Make sure to install a recent v
This specifies an out of source build using the Visual Studio 64 bit generator. (Change the ``-G`` option appropriately if you have a different version of Visual Studio installed.)
After the build process successfully ends, you will find a ``xgboost.dll`` library file inside ``./lib/`` folder.
After the build process successfully ends, you will find a ``xgboost.dll`` library file
inside ``./lib/`` folder. Some notes on using MinGW is added in :ref:`python_mingw`.
.. _build_gpu_support:
Building with GPU support
=========================
XGBoost can be built with GPU support for both Linux and Windows using CMake. GPU support works with the Python package as well as the CLI version. See `Installing R package with GPU support`_ for special instructions for R.
XGBoost can be built with GPU support for both Linux and Windows using CMake. See
`Building R package with GPU support`_ for special instructions for R.
An up-to-date version of the CUDA toolkit is required.
@ -197,7 +153,7 @@ From the command line on Linux starting from the XGBoost directory:
.. note:: Specifying compute capability
To speed up compilation, the compute version specific to your GPU could be passed to cmake as, e.g., ``-DGPU_COMPUTE_VER=50``. A quick explanation and numbers for some architectures can be found `here <https://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/>`_.
To speed up compilation, the compute version specific to your GPU could be passed to cmake as, e.g., ``-DGPU_COMPUTE_VER=50``. A quick explanation and numbers for some architectures can be found `in this page <https://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/>`_.
.. note:: Enabling distributed GPU training
@ -236,17 +192,17 @@ The above cmake configuration run will create an ``xgboost.sln`` solution file i
To speed up compilation, run multiple jobs in parallel by appending option ``-- /MP``.
Makefiles
=========
.. _build_python:
It's only used for creating shorthands for running linters, performing packaging tasks
etc. So the remaining makefiles are legacy.
***********************************
Building Python Package from Source
***********************************
Python Package Installation
===========================
The Python package is located at ``python-package/``.
The Python package is located at ``python-package/``. There are several ways to build and
install the package from source:
Building Python Package with Default Toolchains
===============================================
There are several ways to build and install the package from source:
1. Use Python setuptools directly
@ -262,16 +218,16 @@ The XGBoost Python package supports most of the setuptools commands, here is a l
python setup.py bdist_wheel # Create a binary distribution with wheel format
Running ``python setup.py install`` will compile XGBoost using default CMake flags. For
passing additional compilation options, append the flags to the command. For example, to
enable CUDA acceleration and NCCL (distributed GPU) support:
passing additional compilation options, append the flags to the command. For example,
to enable CUDA acceleration and NCCL (distributed GPU) support:
.. code-block:: bash
python setup.py install --use-cuda --use-nccl
Please refer to ``setup.py`` for a complete list of avaiable options. Some other options
used for development are only available for using CMake directly. See next section on
how to use CMake with setuptools manually.
Please refer to ``setup.py`` for a complete list of avaiable options. Some other
options used for development are only available for using CMake directly. See next
section on how to use CMake with setuptools manually.
You can install the created distribution packages using pip. For example, after running
``sdist`` setuptools command, a tar ball similar to ``xgboost-1.0.0.tar.gz`` will be
@ -287,9 +243,9 @@ command under ``dist`` directory:
For details about these commands, please refer to the official document of `setuptools
<https://setuptools.readthedocs.io/en/latest/>`_, or just Google "how to install Python
package from source". XGBoost Python package follows the general convention. Setuptools
is usually available with your Python distribution, if not you can install it via system
command. For example on Debian or Ubuntu:
package from source". XGBoost Python package follows the general convention.
Setuptools is usually available with your Python distribution, if not you can install it
via system command. For example on Debian or Ubuntu:
.. code-block:: bash
@ -298,9 +254,9 @@ command. For example on Debian or Ubuntu:
For cleaning up the directory after running above commands, ``python setup.py clean`` is
not sufficient. After copying out the build result, simply running ``git clean -xdf``
under ``python-package`` is an efficient way to remove generated cache files. If you find
weird behaviors in Python build or running linter, it might be caused by those cached
files.
under ``python-package`` is an efficient way to remove generated cache files. If you
find weird behaviors in Python build or running linter, it might be caused by those
cached files.
For using develop command (editable installation), see next section.
@ -315,12 +271,12 @@ For using develop command (editable installation), see next section.
This is mostly for C++ developers who don't want to go through the hooks in Python
setuptools. You can build C++ library directly using CMake as described in above
sections. After compilation, a shared object (or called dynamic linked library, jargon
depending on your platform) will appear in XGBoost's source tree under ``lib/`` directory.
On Linux distributions it's ``lib/libxgboost.so``. From there all Python setuptools
commands will reuse that shared object instead of compiling it again. This is especially
convenient if you are using the editable installation, where the installed package is
simply a link to the source tree. We can perform rapid testing during development. Here
is a simple bash script does that:
depending on your platform) will appear in XGBoost's source tree under ``lib/``
directory. On Linux distributions it's ``lib/libxgboost.so``. From there all Python
setuptools commands will reuse that shared object instead of compiling it again. This
is especially convenient if you are using the editable installation, where the installed
package is simply a link to the source tree. We can perform rapid testing during
development. Here is a simple bash script does that:
.. code-block:: bash
@ -334,9 +290,9 @@ is a simple bash script does that:
3. Use ``libxgboost.so`` on system path.
This is for distributing xgboost in a language independent manner, where ``libxgboost.so``
is separately packaged with Python package. Assuming `libxgboost.so` is already presented
in system library path, which can be queried via:
This is for distributing xgboost in a language independent manner, where
``libxgboost.so`` is separately packaged with Python package. Assuming `libxgboost.so`
is already presented in system library path, which can be queried via:
.. code-block:: python
@ -352,10 +308,11 @@ shared object in system path:
cd xgboost/python-package
python setup.py install --use-system-libxgboost
.. _mingw_python:
Building XGBoost library for Python for Windows with MinGW-w64 (Advanced)
-------------------------------------------------------------------------
.. _python_mingw:
Building Python Package for Windows with MinGW-w64 (Advanced)
=============================================================
Windows versions of Python are built with Microsoft Visual Studio. Usually Python binary modules are built with the same compiler the interpreter is built with. However, you may not be able to use Visual Studio, for following reasons:
@ -370,31 +327,15 @@ So you may want to build XGBoost with GCC own your own risk. This presents some
4. Don't use ``-march=native`` gcc flag. Using it causes the Python interpreter to crash if the DLL was actually used.
5. You may need to provide the lib with the runtime libs. If ``mingw32/bin`` is not in ``PATH``, build a wheel (``python setup.py bdist_wheel``), open it with an archiver and put the needed dlls to the directory where ``xgboost.dll`` is situated. Then you can install the wheel with ``pip``.
*******************************
Building R Package From Source.
*******************************
R Package Installation
======================
Installing pre-packaged version
-------------------------------
You can install XGBoost from CRAN just like any other R package:
.. code-block:: R
install.packages("xgboost")
.. note:: Using all CPU cores (threads) on Mac OSX
If you are using Mac OSX, you should first install OpenMP library (``libomp``) by running
.. code-block:: bash
brew install libomp
and then run ``install.packages("xgboost")``. Without OpenMP, XGBoost will only use a single CPU core, leading to suboptimal training speed.
By default, the package installed by running ``install.packages`` is built from source.
Here we list some other options for installing development version.
Installing the development version (Linux / Mac OSX)
----------------------------------------------------
====================================================
Make sure you have installed git and a recent C++ compiler supporting C++11 (See above
sections for requirements of building C++ core).
@ -417,8 +358,8 @@ Thus, one has to run git to check out the code first:
If all fails, try `Building the shared library`_ to see whether a problem is specific to R
package or not. Notice that the R package is installed by CMake directly.
Installing the development version with Visual Studio
-----------------------------------------------------
Installing the development version with Visual Studio (Windows)
===============================================================
On Windows, CMake with Visual C++ Build Tools (or Visual Studio) can be used to build the R package.
@ -450,10 +391,10 @@ Open the Command Prompt and navigate to the XGBoost directory, and then run the
.. _r_gpu_support:
Installing R package with GPU support
-------------------------------------
Building R package with GPU support
===================================
The procedure and requirements are similar as in `Building with GPU support`_, so make sure to read it first.
The procedure and requirements are similar as in :ref:`build_gpu_support`, so make sure to read it first.
On Linux, starting from the XGBoost directory type:
@ -502,20 +443,76 @@ If on Windows you get a "permission denied" error when trying to write to ...Pro
You might find the exact location by running ``.libPaths()`` in R GUI or RStudio.
Trouble Shooting
================
1. Compile failed after ``git pull``
*********************
Building JVM Packages
*********************
Please first update the submodules, clean all and recompile:
Building XGBoost4J using Maven requires Maven 3 or newer, Java 7+ and CMake 3.13+ for compiling Java code as well as the Java Native Interface (JNI) bindings.
Before you install XGBoost4J, you need to define environment variable ``JAVA_HOME`` as your JDK directory to ensure that your compiler can find ``jni.h`` correctly, since XGBoost4J relies on JNI to implement the interaction between the JVM and native libraries.
After your ``JAVA_HOME`` is defined correctly, it is as simple as run ``mvn package`` under jvm-packages directory to install XGBoost4J. You can also skip the tests by running ``mvn -DskipTests=true package``, if you are sure about the correctness of your local setup.
To publish the artifacts to your local maven repository, run
.. code-block:: bash
git submodule update && make clean_all && make -j4
mvn install
Or, if you would like to skip tests, run
Building the Documentation
.. code-block:: bash
mvn -DskipTests install
This command will publish the xgboost binaries, the compiled java classes as well as the java sources to your local repository. Then you can use XGBoost4J in your Java projects by including the following dependency in ``pom.xml``:
.. code-block:: xml
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j</artifactId>
<version>latest_source_version_num</version>
</dependency>
For sbt, please add the repository and dependency in build.sbt as following:
.. code-block:: scala
resolvers += "Local Maven Repository" at "file://"+Path.userHome.absolutePath+"/.m2/repository"
"ml.dmlc" % "xgboost4j" % "latest_source_version_num"
If you want to use XGBoost4J-Spark, replace ``xgboost4j`` with ``xgboost4j-spark``.
.. note:: XGBoost4J-Spark requires Apache Spark 2.3+
XGBoost4J-Spark now requires **Apache Spark 2.3+**. Latest versions of XGBoost4J-Spark uses facilities of `org.apache.spark.ml.param.shared` extensively to provide for a tight integration with Spark MLLIB framework, and these facilities are not fully available on earlier versions of Spark.
Also, make sure to install Spark directly from `Apache website <https://spark.apache.org/>`_. **Upstream XGBoost is not guaranteed to work with third-party distributions of Spark, such as Cloudera Spark.** Consult appropriate third parties to obtain their distribution of XGBoost.
Enabling OpenMP for Mac OS
==========================
If you are on Mac OS and using a compiler that supports OpenMP, you need to go to the file ``xgboost/jvm-packages/create_jni.py`` and comment out the line
.. code-block:: python
CONFIG["USE_OPENMP"] = "OFF"
in order to get the benefit of multi-threading.
Building with GPU support
==========================
If you want to build XGBoost4J that supports distributed GPU training, run
.. code-block:: bash
mvn -Duse.cuda=ON install
**************************
Building the Documentation
**************************
XGBoost uses `Sphinx <https://www.sphinx-doc.org/en/stable/>`_ for documentation. To build it locally, you need a installed XGBoost with all its dependencies along with:
* System dependencies
@ -535,3 +532,10 @@ XGBoost uses `Sphinx <https://www.sphinx-doc.org/en/stable/>`_ for documentation
- matplotlib
Under ``xgboost/doc`` directory, run ``make <format>`` with ``<format>`` replaced by the format you want. For a list of supported formats, run ``make help`` under the same directory.
*********
Makefiles
*********
It's only used for creating shorthands for running linters, performing packaging tasks
etc. So the remaining makefiles are legacy.

2
doc/get_started.rst
View File

@ -8,7 +8,7 @@ on the demo dataset on a binary classification task.
********************************
Links to Other Helpful Resources
********************************
- See :doc:`Installation Guide </build>` on how to install XGBoost.
- See :doc:`Installation Guide </install>` on how to install XGBoost.
- See :doc:`Text Input Format </tutorials/input_format>` on using text format for specifying training/testing data.
- See :doc:`Tutorials </tutorials/index>` for tips and tutorials.
- See `Learning to use XGBoost by Examples <https://github.com/dmlc/xgboost/tree/master/demo>`_ for more code examples.

3
doc/gpu/index.rst
View File

@ -3,7 +3,6 @@ XGBoost GPU Support
###################
This page contains information about GPU algorithms supported in XGBoost.
To install GPU support, checkout the :doc:`/build`.
.. note:: CUDA 10.0, Compute Capability 3.5 required
@ -71,7 +70,7 @@ The device ordinal (which GPU to use if you have many of them) can be selected u
``gpu_id`` parameter, which defaults to 0 (the first device reported by CUDA runtime).
The GPU algorithms currently work with CLI, Python and R packages. See :doc:`/build` for details.
The GPU algorithms currently work with CLI, Python, R, and JVM packages. See :doc:`/install` for details.
.. code-block:: python
:caption: Python example

1
doc/index.rst
View File

@ -15,6 +15,7 @@ Contents
:maxdepth: 2
:titlesonly:
install
build
get_started
tutorials/index

215
doc/install.rst Normal file
View File

@ -0,0 +1,215 @@
##################
Installation Guide
##################
XGBoost provides binary packages for some language bindings. The binary packages support
the GPU algorithm (``gpu_hist``) on machines with NVIDIA GPUs. Please note that **training
with multiple GPUs is only supported for Linux platform**. See :doc:`gpu/index`. Also we
have both stable releases and nightly builds, see below for how to install them. For
building from source, visit :doc:`this page </build>`.
.. contents:: Contents
Stable Release
==============
Python
------
Pre-built binary are uploaded to PyPI (Python Package Index) for each release. Supported platforms are Linux (x86_64, aarch64), Windows (x86_64) and MacOS (x86_64).
.. code-block:: bash
pip install xgboost
You might need to run the command with ``--user`` flag or use ``virtualenv`` if you run
into permission errors. Python pre-built binary capability for each platform:
.. |tick| unicode:: U+2714
.. |cross| unicode:: U+2718
+-------------------+---------+----------------------+
| Platform | GPU | Multi-Node-Multi-GPU |
+===================+=========+======================+
| Linux x86_64 | |tick| | |tick| |
+-------------------+---------+----------------------+
| Linux aarch64 | |cross| | |cross| |
+-------------------+---------+----------------------+
| MacOS | |cross| | |cross| |
+-------------------+---------+----------------------+
| Windows | |tick| | |cross| |
+-------------------+---------+----------------------+
R
-
* From CRAN:
.. code-block:: R
install.packages("xgboost")
.. note:: Using all CPU cores (threads) on Mac OSX
If you are using Mac OSX, you should first install OpenMP library (``libomp``) by running
.. code-block:: bash
brew install libomp
and then run ``install.packages("xgboost")``. Without OpenMP, XGBoost will only use a
single CPU core, leading to suboptimal training speed.
* We also provide **experimental** pre-built binary on Linux x86_64 with GPU support.
Download the binary package from the Releases page. The file name will be of the form
``xgboost_r_gpu_linux_[version].tar.gz``. Then install XGBoost by running:
.. code-block:: bash
# Install dependencies
R -q -e "install.packages(c('data.table', 'magrittr', 'jsonlite'))"
# Install XGBoost
R CMD INSTALL ./xgboost_r_gpu_linux.tar.gz
JVM
---
You can use XGBoost4J in your Java/Scala application by adding XGBoost4J as a dependency:
.. code-block:: xml
:caption: Maven
<properties>
...
<!-- Specify Scala version in package name -->
<scala.binary.version>2.12</scala.binary.version>
</properties>
<dependencies>
...
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j_${scala.binary.version}</artifactId>
<version>latest_version_num</version>
</dependency>
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j-spark_${scala.binary.version}</artifactId>
<version>latest_version_num</version>
</dependency>
</dependencies>
.. code-block:: scala
:caption: sbt
libraryDependencies ++= Seq(
"ml.dmlc" %% "xgboost4j" % "latest_version_num",
"ml.dmlc" %% "xgboost4j-spark" % "latest_version_num"
)
This will check out the latest stable version from the Maven Central.
For the latest release version number, please check `release page <https://github.com/dmlc/xgboost/releases>`_.
To enable the GPU algorithm (``tree_method='gpu_hist'``), use artifacts ``xgboost4j-gpu_2.12`` and ``xgboost4j-spark-gpu_2.12`` instead (note the ``gpu`` suffix).
.. note:: Windows not supported in the JVM package
Currently, XGBoost4J-Spark does not support Windows platform, as the distributed training algorithm is inoperational for Windows. Please use Linux or MacOS.
Nightly Build
=============
Python
------
Nightly builds are available. You can go to `this page <https://s3-us-west-2.amazonaws.com/xgboost-nightly-builds/list.html>`_,
find the wheel with the commit ID you want and install it with pip:
.. code-block:: bash
pip install <url to the wheel>
The capability of Python pre-built wheel is the same as stable release.
R
-
Other than standard CRAN installation, we also provide *experimental* pre-built binary on
Linux x86_64 with GPU support. You can go to `this page
<https://s3-us-west-2.amazonaws.com/xgboost-nightly-builds/list.html>`_, Find the commit
ID you want to install: ``xgboost_r_gpu_linux_[commit].tar.gz``, download it then run:
.. code-block:: bash
# Install dependencies
R -q -e "install.packages(c('data.table', 'magrittr', 'jsonlite', 'remotes'))"
# Install XGBoost
R CMD INSTALL ./xgboost_r_gpu_linux.tar.gz
JVM
---
First add the following Maven repository hosted by the XGBoost project:
.. code-block:: xml
:caption: Maven
<repository>
<id>XGBoost4J Snapshot Repo</id>
<name>XGBoost4J Snapshot Repo</name>
<url>https://s3-us-west-2.amazonaws.com/xgboost-maven-repo/snapshot/</url>
</repository>
.. code-block:: scala
:caption: sbt
resolvers += "XGBoost4J Snapshot Repo" at "https://s3-us-west-2.amazonaws.com/xgboost-maven-repo/snapshot/"
Then add XGBoost4J as a dependency:
.. code-block:: xml
:caption: maven
<properties>
...
<!-- Specify Scala version in package name -->
<scala.binary.version>2.12</scala.binary.version>
</properties>
<dependencies>
...
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j_${scala.binary.version}</artifactId>
<version>latest_version_num-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j-spark_${scala.binary.version}</artifactId>
<version>latest_version_num-SNAPSHOT</version>
</dependency>
</dependencies>
.. code-block:: scala
:caption: sbt
libraryDependencies ++= Seq(
"ml.dmlc" %% "xgboost4j" % "latest_version_num-SNAPSHOT",
"ml.dmlc" %% "xgboost4j-spark" % "latest_version_num-SNAPSHOT"
)
Look up the ``version`` field in `pom.xml <https://github.com/dmlc/xgboost/blob/master/jvm-packages/pom.xml>`_ to get the correct version number.
The SNAPSHOT JARs are hosted by the XGBoost project. Every commit in the ``master`` branch will automatically trigger generation of a new SNAPSHOT JAR. You can control how often Maven should upgrade your SNAPSHOT installation by specifying ``updatePolicy``. See `here <http://maven.apache.org/pom.html#Repositories>`_ for details.
You can browse the file listing of the Maven repository at https://s3-us-west-2.amazonaws.com/xgboost-maven-repo/list.html.
To enable the GPU algorithm (``tree_method='gpu_hist'``), use artifacts ``xgboost4j-gpu_2.12`` and ``xgboost4j-spark-gpu_2.12`` instead (note the ``gpu`` suffix).

194
doc/jvm/index.rst
View File

@ -23,198 +23,8 @@ Installation
:local:
:backlinks: none
Installation from Maven repository
==================================
Access release version
----------------------
You can use XGBoost4J in your Java/Scala application by adding XGBoost4J as a dependency:
.. code-block:: xml
:caption: Maven
<properties>
...
<!-- Specify Scala version in package name -->
<scala.binary.version>2.12</scala.binary.version>
</properties>
<dependencies>
...
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j_${scala.binary.version}</artifactId>
<version>latest_version_num</version>
</dependency>
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j-spark_${scala.binary.version}</artifactId>
<version>latest_version_num</version>
</dependency>
</dependencies>
.. code-block:: scala
:caption: sbt
libraryDependencies ++= Seq(
"ml.dmlc" %% "xgboost4j" % "latest_version_num",
"ml.dmlc" %% "xgboost4j-spark" % "latest_version_num"
)
This will check out the latest stable version from the Maven Central.
For the latest release version number, please check `here <https://github.com/dmlc/xgboost/releases>`_.
To enable the GPU algorithm (``tree_method='gpu_hist'``), use artifacts ``xgboost4j-gpu_2.12`` and ``xgboost4j-spark-gpu_2.12`` instead (note the ``gpu`` suffix).
.. note:: Using Maven repository hosted by the XGBoost project
There may be some delay until a new release becomes available to Maven Central. If you would like to access the latest release immediately, add the Maven repository hosted by the XGBoost project:
.. code-block:: xml
:caption: Maven
<repository>
<id>XGBoost4J Release Repo</id>
<name>XGBoost4J Release Repo</name>
<url>https://s3-us-west-2.amazonaws.com/xgboost-maven-repo/release/</url>
</repository>
.. code-block:: scala
:caption: sbt
resolvers += "XGBoost4J Release Repo" at "https://s3-us-west-2.amazonaws.com/xgboost-maven-repo/release/"
.. note:: Windows not supported in the JVM package
Currently, XGBoost4J-Spark does not support Windows platform, as the distributed training algorithm is inoperational for Windows. Please use Linux or MacOS.
Access SNAPSHOT version
-----------------------
First add the following Maven repository hosted by the XGBoost project:
.. code-block:: xml
:caption: Maven
<repository>
<id>XGBoost4J Snapshot Repo</id>
<name>XGBoost4J Snapshot Repo</name>
<url>https://s3-us-west-2.amazonaws.com/xgboost-maven-repo/snapshot/</url>
</repository>
.. code-block:: scala
:caption: sbt
resolvers += "XGBoost4J Snapshot Repo" at "https://s3-us-west-2.amazonaws.com/xgboost-maven-repo/snapshot/"
Then add XGBoost4J as a dependency:
.. code-block:: xml
:caption: maven
<properties>
...
<!-- Specify Scala version in package name -->
<scala.binary.version>2.12</scala.binary.version>
</properties>
<dependencies>
...
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j_${scala.binary.version}</artifactId>
<version>latest_version_num-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j-spark_${scala.binary.version}</artifactId>
<version>latest_version_num-SNAPSHOT</version>
</dependency>
</dependencies>
.. code-block:: scala
:caption: sbt
libraryDependencies ++= Seq(
"ml.dmlc" %% "xgboost4j" % "latest_version_num-SNAPSHOT",
"ml.dmlc" %% "xgboost4j-spark" % "latest_version_num-SNAPSHOT"
)
Look up the ``version`` field in `pom.xml <https://github.com/dmlc/xgboost/blob/master/jvm-packages/pom.xml>`_ to get the correct version number.
The SNAPSHOT JARs are hosted by the XGBoost project. Every commit in the ``master`` branch will automatically trigger generation of a new SNAPSHOT JAR. You can control how often Maven should upgrade your SNAPSHOT installation by specifying ``updatePolicy``. See `here <http://maven.apache.org/pom.html#Repositories>`_ for details.
You can browse the file listing of the Maven repository at https://s3-us-west-2.amazonaws.com/xgboost-maven-repo/list.html.
To enable the GPU algorithm (``tree_method='gpu_hist'``), use artifacts ``xgboost4j-gpu_2.12`` and ``xgboost4j-spark-gpu_2.12`` instead (note the ``gpu`` suffix).
Installation from source
========================
Building XGBoost4J using Maven requires Maven 3 or newer, Java 7+ and CMake 3.13+ for compiling the JNI bindings.
Before you install XGBoost4J, you need to define environment variable ``JAVA_HOME`` as your JDK directory to ensure that your compiler can find ``jni.h`` correctly, since XGBoost4J relies on JNI to implement the interaction between the JVM and native libraries.
After your ``JAVA_HOME`` is defined correctly, it is as simple as run ``mvn package`` under jvm-packages directory to install XGBoost4J. You can also skip the tests by running ``mvn -DskipTests=true package``, if you are sure about the correctness of your local setup.
To publish the artifacts to your local maven repository, run
.. code-block:: bash
mvn install
Or, if you would like to skip tests, run
.. code-block:: bash
mvn -DskipTests install
This command will publish the xgboost binaries, the compiled java classes as well as the java sources to your local repository. Then you can use XGBoost4J in your Java projects by including the following dependency in ``pom.xml``:
.. code-block:: xml
<dependency>
<groupId>ml.dmlc</groupId>
<artifactId>xgboost4j</artifactId>
<version>latest_source_version_num</version>
</dependency>
For sbt, please add the repository and dependency in build.sbt as following:
.. code-block:: scala
resolvers += "Local Maven Repository" at "file://"+Path.userHome.absolutePath+"/.m2/repository"
"ml.dmlc" % "xgboost4j" % "latest_source_version_num"
If you want to use XGBoost4J-Spark, replace ``xgboost4j`` with ``xgboost4j-spark``.
.. note:: XGBoost4J-Spark requires Apache Spark 2.3+
XGBoost4J-Spark now requires **Apache Spark 2.3+**. Latest versions of XGBoost4J-Spark uses facilities of `org.apache.spark.ml.param.shared` extensively to provide for a tight integration with Spark MLLIB framework, and these facilities are not fully available on earlier versions of Spark.
Also, make sure to install Spark directly from `Apache website <https://spark.apache.org/>`_. **Upstream XGBoost is not guaranteed to work with third-party distributions of Spark, such as Cloudera Spark.** Consult appropriate third parties to obtain their distribution of XGBoost.
Enabling OpenMP for Mac OS
--------------------------
If you are on Mac OS and using a compiler that supports OpenMP, you need to go to the file ``xgboost/jvm-packages/create_jni.py`` and comment out the line
.. code-block:: python
CONFIG["USE_OPENMP"] = "OFF"
in order to get the benefit of multi-threading.
Building with GPU support
-------------------------
If you want to build XGBoost4J that supports distributed GPU training, run
.. code-block:: bash
mvn -Duse.cuda=ON install
Checkout the :doc:`Installation Guide </install>` for how to install jvm package, or
:doc:`Building from Source </build>` on how to build it form source.
********
Contents

2
doc/python/index.rst
View File

@ -2,7 +2,7 @@
XGBoost Python Package
######################
This page contains links to all the python related documents on python package.
To install the package package, checkout :doc:`Installation Guide </build>`.
To install the package, checkout :doc:`Installation Guide </install>`.
********
Contents

2
doc/python/python_intro.rst
View File

@ -10,7 +10,7 @@ This document gives a basic walkthrough of xgboost python package.
Install XGBoost
---------------
To install XGBoost, follow instructions in :doc:`/build`.
To install XGBoost, follow instructions in :doc:`/install`.
To verify your installation, run the following in Python: