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.

Sign up for GitHub

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

Add installation troubleshooting #379

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add installation troubleshooting #379

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
"sphinx.ext.viewcode",
"sphinxcontrib.contentui",
"sphinx_copybutton",
"sphinx_collapse",
]

numpydoc_validation_checks = {"all", "EX01", "SA01", "ES01"}
Expand Down
39 changes: 39 additions & 0 deletions docs/source/user_guide/troubleshooting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,45 @@
Troubleshooting
===============

Installation
------------

When installing ``janus-core``, CMake errors can occur when building ``phonopy``, such as:

.. collapse:: Example CMake error

.. code-block:: bash

CMake Error at /tmp/pip-build-env-j2jx9pp5/overlay/lib/python3.11/site-packages/nanobind/cmake/nanobind-config.cmake:243 (target_compile_features):
target_compile_features The compiler feature "cxx_std_17" is not known to
CXX compiler

"GNU"

version 4.8.5.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Are we really concerned about trying to compile with a 10 year old release of GCC? This is not our failure and should probably be on phonopy's docs, not ours.

Copy link
Member Author

Choose a reason for hiding this comment

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

As I say in the issue, I agree to a large extent it is an issue for phonopy, but it occurs when running pip install janus-core, and for the user who encountered this, it wasn't obvious how to resolve it, so I don't think it hurts to have this.

The solution is generally very simple, but if you're not used to cmake/compilation, which I imagine is true for a lot of Python users, it may not be immediately obvious, as it's not something you often need to worry about.

Also just to note, there are two similar issues, which I've tried to cover together, although maybe I shouldn't:

  1. Old GCC etc. In this case, it was the default for the user on their HPC system, which I don't think will be uncommon, unfortunately.
  2. CXX being unset. This happened to me at one point when I changed environments, and it took me a minute to understand why installing had stopped working, when it had been fine up to then

Copy link
Collaborator

Choose a reason for hiding this comment

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

What's the scope of PR-ing this into phonopy's docs on their "installing phonopy" page and just linking it/directing them there.

I have no idea how responsive phonopy are to PRs, but this seems a fairly simple thing.

https://phonopy.github.io/phonopy/install.html#building-using-pip-install

Copy link
Member

Choose a reason for hiding this comment

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

in general are responsive

Copy link
Member Author

Choose a reason for hiding this comment

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

What's the scope of PR-ing this into phonopy's docs on their "installing phonopy" page and just linking it/directing them there.

I have no idea how responsive phonopy are to PRs, but this seems a fairly simple thing.

https://phonopy.github.io/phonopy/install.html#building-using-pip-install

I did wonder that. I think part of my concern is that a user doesn't necessarily immediately assume phonopy is at fault - I don't think the user who encountered the error did.

It's obvious in retrospect, but if you're somewhat used to battling dependency issues etc, your first thought may well be to blame us.

I'd also argue that we want to be relatively clear what requirements there are for installing janus-core, without needing to dive into the details of every sub-dependency. Clearly there are limits, but for a slightly unusual issue with a relatively simple solution, I'm not entirely convinced it's out of scope.

I'll open an issue with phonopy too either way.

Copy link
Member Author

Choose a reason for hiding this comment

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

It is a known thing: phonopy/phonopy#439

Maybe a different way to look at the problem is that the CMake error does more or less describe what you need to do in either case (update your compiler or make sure it's set). If you're installing phonopy directly, this sort of error is relatively expected, since they describe the need for a compiler, and so in that context, I'm not sure they need to elaborate much on the issue.

When installing janus-core, on the other hand, it's not something a user naturally expects in the same way, and without that context I don't think the solution is as clear.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Failed to build phonopy
ERROR: ERROR: Failed to build installable wheels for some pyproject.toml based projects (phonopy)

Seems fairly indicative if you're aware of phonopy it's not our problem. Then again, I'm not 100% sure people know what is happening when they pip install.

I'm fine with it going in in principle, but I do wonder whether we (instead of explaining it) link against that issue? Maybe that's worse. I trust your judgement.

Call Stack (most recent call first):
/tmp/pip-build-env-j2jx9pp5/overlay/lib/python3.11/site-packages/nanobind/cmake/nanobind-config.cmake:358 (nanobind_build_library)
CMakeLists.txt:108 (nanobind_add_module)


-- Configuring incomplete, errors occurred!

*** CMake configuration failed
[end of output]

note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed building wheel for phonopy
Building wheel for python-hostlist (setup.py) ... done
Created wheel for python-hostlist: filename=python_hostlist-2.2.1-py3-none-any.whl size=39604 sha256=44f9f27a42895e61a521cf9129a6a3ad03e633b201390da5ef76d5f59db3b94f
Stored in directory: ...
Successfully built janus-core python-hostlist
Failed to build phonopy
ERROR: ERROR: Failed to build installable wheels for some pyproject.toml based projects (phonopy)


This can typically be resolved by ensuring your C++ compiler is updated, and that the `CXX <https://cmake.org/cmake/help/latest/envvar/CXX.html>`_ environment variable is set.


Carbon tracking
---------------

Expand Down
1 change: 1 addition & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ docs = [
"sphinxcontrib-contentui<1.0.0,>=0.2.5",
"sphinxcontrib-details-directive<1.0,>=0.1",
"sphinx-copybutton<1.0.0,>=0.5.2",
"sphinx-collapse>=0.1.3",
]

pre-commit = [
Expand Down
Loading