1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
###########################################
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`.
|
