Clarifying the example in readme

[tikuma-lsuhsc]

To a CMake novice (or someone who has not used it in years like me) the example presented in the readme feels a bit under-explained.

An example CMakeLists.txt:

cmake_minimum_required(VERSION 3.15...3.30)
project(${SKBUILD_PROJECT_NAME} LANGUAGES C)

find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)

Python_add_library(_module MODULE src/module.c WITH_SOABI)
install(TARGETS _module DESTINATION ${SKBUILD_PROJECT_NAME})

It would be helpful if more context is given to the example, specifically where the built package will be installed when pip install'ed. Something along the line of "the install command instructs CMake to install the C module to .site_packages/scikit_build_simplest/_module.pyd when you run pip install scikit_build_simplest."

Also, since this module is not accessible without scikit_build_simplest/__init__.py, it may be even better to include another line to CMakeLists.txt:

install(FILES src/__init__.py DESTINATION ${SKBUILD_PROJECT_NAME}/)

Thanks!

[LecrisUT]

Hmm, I think there is some value of having the example be extremely minimal in order to showcase "hey, look, this is how simple it can be". What about having an expandable element that would say "what is going on under the hood?"?

There are also quite a few resources that should be displayed somewhere regarding CMake and scikit-build-core. Here is my last attempt at summarizing the sources and their scope and we could add to it:

• Example projects: scikit-build/scikit-build-sample-projects, pybind/scikit_build_example, they're quite scattered
• Cookie-cutter project: scientific-python/cookie

For the specific documentation you have in mind, I think it would be best served within this repo's guide, and we should try out to see where and how it best fits. And I think it would be best to mention the resources above in such a PR as well.

[henryiii]

Also, since this module is not accessible without scikit_build_simplest/__init__.py, it may be even better to include another line to CMakeLists.txt:

Scikit-build-core installs your package directory automatically if it can find it (and even works in editable mode). Generally it's best to try to avoid installing .py files via CMake so you can fully take advantage of editable installs.

instructs CMake to install the C module to .site_packages/scikit_build_simplest/_module.pyd

It's a bit more complex than that, as it actually always "installs" it to the wheel, which is then unzipped into that location. The main effect being that you can't use absolute paths or react to the contents of site packaegs. That's why there's a whole page on this procedure at https://scikit-build-core.readthedocs.io/en/latest/build.html

[tikuma-lsuhsc]

Thank you for the responses. Maybe I'm expecting too much from a readme document. 😅 I guess all I'm asking here is that a bit more context and not full details. Maybe even just some hypothetical distro structure which yields a functional distro package?

Aside from readme, an analogue to this setuptools doc page would be super helpful. (I'd be happy to take a crack at it when I have a bit more free time in a couple months.)

Meanwhile, there may be a bug, which triggered me to post this issue. Please see Issue #935 that I just posted. Thanks!