Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] update and simplify installation docs #6536

Merged
merged 4 commits into from
Jul 14, 2024
Merged

Conversation

jameslamb
Copy link
Collaborator

@jameslamb jameslamb commented Jul 10, 2024

Proposes the following changes to installation docs:

The overall goals of this PR are:

  • document the CUDA / GPU support in conda-forge packages
  • reduce maintenance burden, complexity, and the risk of outdated information in installation docs

Specific changes:

  • add docs about using the conda-forge package to get CUDA/GPU builds, and remove language about it not being maintained by us
  • remove language about needing to install CMake to build the Python package
    • scikit-build-core does this automatically (code link)
  • stop documenting minimum CMake version
    • it's too easy for this to become out of date as CMake changes are made. We can rely on raising informative errors from
      cmake_minimum_required(VERSION 3.18)
      to inform people about the minimum required version
  • stop documenting a minimum GLIBC version for instructions about building from source
    • GLIBC version only matters when taking something precompiled on one system and running it on another system. I don't think there's anything in LightGBM's code that prevents it from being built from source on a system with older GLIBC.
  • remove language about LightGBM_compilation.log file
  • other minor changes

Notes for Reviewers

ref #5419 (comment)

@jameslamb jameslamb changed the title WIP: [docs] update and simplify installation docs [docs] update and simplify installation docs Jul 10, 2024
@jameslamb jameslamb marked this pull request as ready for review July 10, 2024 23:25
Copy link
Collaborator

@StrikerRUS StrikerRUS left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Found some other places across the repo where CMake version is mentioned.

docs/FAQ.rst Outdated Show resolved Hide resolved
python-package/README.rst Outdated Show resolved Hide resolved
@@ -70,17 +70,15 @@ Build from Sources

pip install --no-binary lightgbm lightgbm

For **Linux** and **macOS** users, installation from sources requires installed `CMake`_.

For **Linux** users, **glibc** >= 2.28 is required. Also, in some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for ``lib[g|i]omp`` for doing this).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove this as well?
For **Linux** users, **glibc** >= 2.14 is required for LightGBM ``<=3.3.3`` and **glibc** >= 2.28 is required for newer versions.

For **Linux** users, **glibc** >= 2.14 is required for LightGBM ``<=3.3.3`` and **glibc** >= 2.28 is required for newer versions. Also, in some rare cases, when you hit ``OSError: libgomp.so.1: cannot open shared object file: No such file or directory`` error during importing LightGBM, you need to install OpenMP runtime library separately (use your package manager and search for ``lib[g|i]omp`` for doing this).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I think that makes sense.

At first I'd intentionally left this one in, because it is true that on systems where you have older versions of GLIBC, pip install lightgbm will return an sdist (that'll have to be compiled) instead of a wheel.

But looking through it again, I do see that the other sections that explicitly talk about sdists (anything about passing --no-binary lightgbm) are nested underneath this "Install from PyPI" heading. And these GLIBC requirements don't affect your ability to build from an sdist.

I've removed this in 8cee2d6.

@@ -294,4 +298,3 @@ To check that a contribution to the package matches its style expectations, run
:target: https://pepy.tech/project/lightgbm
.. |API Docs| image:: https://readthedocs.org/projects/lightgbm/badge/?version=latest
:target: https://lightgbm.readthedocs.io/en/latest/Python-API.html
.. _CMake: https://cmake.org/
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove CMake version from here as well?

You can perform installation either with **Apple Clang** or **gcc**. In case you prefer **Apple Clang**, you should install **OpenMP** (details for installation can be found in [Installation Guide](https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#apple-clang)) first and **CMake** version 3.16 or higher is required. In case you prefer **gcc**, you need to install it (details for installation can be found in [Installation Guide](https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc)) and set some environment variables to tell R to use `gcc` and `g++`. If you install these from Homebrew, your versions of `g++` and `gcc` are most likely in `/usr/local/bin`, as shown below.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes, missed this one! Removed in 8cee2d6

@jameslamb jameslamb requested a review from StrikerRUS July 13, 2024 22:55
Copy link
Collaborator

@StrikerRUS StrikerRUS left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for reducing maintenance burden!

@StrikerRUS StrikerRUS merged commit 830763d into master Jul 14, 2024
41 checks passed
@StrikerRUS StrikerRUS deleted the docs/install-docs branch July 14, 2024 12:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants