84 lines
2.7 KiB
ReStructuredText
84 lines
2.7 KiB
ReStructuredText
###########################################
|
|
Notes on packaging XGBoost's Python package
|
|
###########################################
|
|
|
|
|
|
.. contents:: Contents
|
|
:local:
|
|
|
|
.. _packaging_python_xgboost:
|
|
|
|
***************************************************
|
|
How to build binary wheels and source distributions
|
|
***************************************************
|
|
|
|
Wheels and source distributions (sdist for short) are the two main
|
|
mechanisms for packaging and distributing Python packages.
|
|
|
|
* A **source distribution** (sdist) is a tarball (``.tar.gz`` extension) that
|
|
contains the source code.
|
|
* A **wheel** is a ZIP-compressed archive (with ``.whl`` extension)
|
|
representing a *built* distribution. Unlike an sdist, a wheel can contain
|
|
compiled components. The compiled components are compiled prior to distribution,
|
|
making it more convenient for end-users to install a wheel. Wheels containing
|
|
compiled components are referred to as **binary wheels**.
|
|
|
|
See `Python Packaging User Guide <https://packaging.python.org/en/latest/>`_
|
|
to learn more about how Python packages in general are packaged and
|
|
distributed.
|
|
|
|
For the remainder of this document, we will focus on packaging and
|
|
distributing XGBoost.
|
|
|
|
Building sdists
|
|
===============
|
|
|
|
In the case of XGBoost, an sdist contains both the Python code as well as
|
|
the C++ code, so that the core part of XGBoost can be compiled into the
|
|
shared library ``libxgboost.so`` [#shared_lib_name]_.
|
|
|
|
You can obtain an sdist as follows:
|
|
|
|
.. code-block:: console
|
|
|
|
$ python -m build --sdist .
|
|
|
|
(You'll need to install the ``build`` package first:
|
|
``pip install build`` or ``conda install python-build``.)
|
|
|
|
Running ``pip install`` with an sdist will launch CMake and a C++ compiler
|
|
to compile the bundled C++ code into ``libxgboost.so``:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip install -v xgboost-2.0.0.tar.gz # Add -v to show build progress
|
|
|
|
Building binary wheels
|
|
======================
|
|
|
|
You can also build a wheel as follows:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip wheel --no-deps -v .
|
|
|
|
Notably, the resulting wheel contains a copy of the shared library
|
|
``libxgboost.so`` [#shared_lib_name]_. The wheel is a **binary wheel**,
|
|
since it contains a compiled binary.
|
|
|
|
|
|
Running ``pip install`` with the binary wheel will extract the content of
|
|
the wheel into the current Python environment. Since the wheel already
|
|
contains a pre-built copy of ``libxgboost.so``, it does not have to be
|
|
built at the time of install. So ``pip install`` with the binary wheel
|
|
completes quickly:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip install xgboost-2.0.0-py3-none-linux_x86_64.whl # Completes quickly
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#shared_lib_name] The name of the shared library file will differ
|
|
depending on the operating system in use. See :ref:`build_shared_lib`.
|