Merge pull request #560 from Blosc/restructure_install

Implement PEP recommendations

Author: lshaw8317

CMakeLists.txt

@@ -58,11 +58,8 @@ set(MINIEXPR_BUILD_BENCH OFF CACHE BOOL "Build miniexpr benchmarks" FORCE)
 
 FetchContent_Declare(miniexpr
     GIT_REPOSITORY https://github.com/Blosc/miniexpr.git
-    # GIT_TAG 979573da618e0443c3984bad8db3ed5d9ce72f75  # latest commit in main
-    GIT_TAG main
-    GIT_SHALLOW TRUE  # fetch only the latest commit (only works with a branch in GIT_TAG)
-    # In case you want to use a local copy of miniexpr for development, uncomment the line below
-    # SOURCE_DIR "/Users/faltet/blosc/miniexpr"
+    GIT_TAG main  # latest commit in main
+    GIT_SHALLOW True
 )
 FetchContent_MakeAvailable(miniexpr)
 
@@ -111,7 +108,11 @@ else()
         set(DEACTIVATE_OPENZL ON CACHE BOOL "Do not include support for the OpenZL library.")
     endif()
     set(CMAKE_POSITION_INDEPENDENT_CODE ON)
-    # we want the binaries of the C-Blosc2 library to go into the wheels
+    set(CMAKE_INSTALL_INCLUDEDIR ${SKBUILD_PLATLIB_DIR}/blosc2/include) # directory for include files
+    set(CMAKE_INSTALL_LIBDIR ${SKBUILD_PLATLIB_DIR}/blosc2/lib) # directory for libblosc2 and pkgconfig
+    set(Blosc2_INSTALL_CMAKEDIR ${CMAKE_INSTALL_LIBDIR}/cmake/blosc2) # directory for cmake files
+    set(CMAKE_INSTALL_BINDIR ${SKBUILD_PLATLIB_DIR}/blosc2/lib) # directory for libblosc2.dll on windows
+    # we will put the binaries of the C-Blosc2 library into the wheels according to PEP
     set(BLOSC_INSTALL ON)
     include(FetchContent)
     FetchContent_Declare(blosc2
@@ -126,9 +127,25 @@ else()
     target_link_libraries(blosc2_ext PRIVATE blosc2_static)
 endif()
 
-add_custom_command(
-    TARGET blosc2_ext POST_BUILD
-    COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_FILE:blosc2_ext> ${CMAKE_SOURCE_DIR}/blosc2
-)
+# TODO
+# CHECK THIS
+if(UNIX)
+  set_target_properties(blosc2_ext PROPERTIES
+    BUILD_WITH_INSTALL_RPATH TRUE
+    INSTALL_RPATH "$<IF:$<PLATFORM_ID:Darwin>,@loader_path/lib,\$ORIGIN/lib>"
+  )
+endif()
 
-install(TARGETS blosc2_ext LIBRARY DESTINATION blosc2)
+if(WIN32)
+  add_custom_command(TARGET blosc2_ext POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+            $<TARGET_FILE:blosc2_shared>
+            $<TARGET_FILE_DIR:blosc2_ext>
+  )
+endif()
+
+# Python extension -> site-packages/blosc2
+install(
+  TARGETS blosc2_ext
+  LIBRARY DESTINATION ${SKBUILD_PLATLIB_DIR}/blosc2
+)

README_DEVELOPERS.md

@@ -115,3 +115,70 @@ and run pytest from the `array-api-tests` source dir like this:
 ``` bash
 ARRAY_API_TESTS_MODULE=blosc2 pytest array_api_tests --xfails-file ${BLOSC2_DIR}/tests/array-api-xfails.txt -xs
 ```
+
+# Using the C-library
+Since C-blosc2 is shipped as a compiled binary with python-blosc2, one can compile and run C code using C-blosc2 functions. As of python-blosc2 version 4.0, one can find the location of the ``include`` files and binaries as follows. Run the following command in the terminal, which will give as output the path to the ``__init__.py`` file within the blosc2 folder.
+```bash
+python -c "import blosc2; print(blosc2.__file__)"
+path/to/blosc2/__init__.py
+```
+## Using CMake
+One may then access the include files via ``path/to/blosc2/include`` and the binaries via ``path/to/blosc2/lib``. Thus one may link a C-app via a ``CMakelists.txt`` file with the following snippet
+```
+# Add directory to search list for find_package
+set(CMAKE_PREFIX_PATH "$(python - <<EOF
+import blosc2, pathlib
+print(pathlib.Path(blosc2.__file__).parent)
+EOF)")
+
+find_package(Blosc2 CONFIG REQUIRED)
+
+target_link_libraries(myapp PRIVATE Blosc2::blosc2_shared)
+```
+
+## Using pkg-config
+If one prefers to avoid using CMake, one can also use the pkg-config that is shipped with the wheel by running the following sequence of commands
+
+First
+```
+BLOSC2_PREFIX=$(python - <<'EOF'
+import blosc2, pathlib
+print(pathlib.Path(blosc2.__file__).parent)
+EOF
+)\
+export PKG_CONFIG_PATH="$BLOSC2_PREFIX/lib/pkgconfig"
+```
+
+We can check that the .pc file has the required info and has been found via
+``bash
+pkg-config --modversion blosc2
+``
+
+Then define a test program
+```bash
+cat > test.c <<'EOF'
+#include <stdio.h>
+#include <blosc2.h>
+
+int main(void) {
+    printf(blosc2_get_version_string());
+    return 0;
+}
+EOF
+```
+and compile it to an executable
+```bash
+gcc test.c \
+  $(pkg-config --cflags --libs blosc2) \
+  -Wl,--enable-new-dtags \
+  -Wl,-rpath,"\$ORIGIN" \
+  -o test_blosc2
+```
+The executable has to have access to the C library, so we copy the shared library to the executable directory
+```bash
+cp "$BLOSC2_PREFIX/lib/"libblosc2.so .
+```
+and run the executable
+```bash
+./test_blosc2
+```