From 77bebd1866c56dd0e3f50a7afd3f92483c834f13 Mon Sep 17 00:00:00 2001 From: Marco Barbone Date: Thu, 1 Aug 2024 12:21:54 -0400 Subject: [PATCH] added sphinx to cmake --- CHANGELOG | 2 ++ CMakeLists.txt | 15 ++++++++------- cmake/setupSphinx.cmake | 21 +++++++++++++++++++++ docs/devnotes.rst | 9 +++++---- docs/install.rst | 31 +++++++++++++++++++------------ 5 files changed, 55 insertions(+), 23 deletions(-) create mode 100644 cmake/setupSphinx.cmake diff --git a/CHANGELOG b/CHANGELOG index ad01f7c9c..c882f716f 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -52,6 +52,8 @@ V 2.3.0beta (7/24/24) Added support for Windows (llvm, msvc), Linux (llvm, gcc) and MacOS (llvm, gcc). * cmake support for both ducc0 and fftw * cmake adding nvcc and msvc optimization flags +* cmake supports sphinx +* updated install docs V 2.2.0 (12/12/23) diff --git a/CMakeLists.txt b/CMakeLists.txt index b20322519..7007395d8 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -105,10 +105,6 @@ if(FINUFFT_ARCH_FLAGS STREQUAL "native") endif() endif() -if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME) - include(CTest) -endif() - # Set default build type to Release if(NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE @@ -140,20 +136,25 @@ function(enable_asan target) endif() endfunction() +set(CPM_DOWNLOAD_VERSION 0.40.0) +include(cmake/setupCPM.cmake) + +if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME) + include(CTest) + include(cmake/setupSphinx.cmake) +endif() + if(FINUFFT_USE_CPU) # make apple with gnu use old linker, new linker breaks, see issue #360 if((APPLE) AND (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")) add_link_options("-ld_classic") endif() - - set(CPM_DOWNLOAD_VERSION 0.40.0) set(FFTW_VERSION 3.3.10) set(XTL_VERSION 0.7.7) set(XSIMD_VERSION 13.0.0) # using latest ducc0 version for now as it fixes MacOS GCC build set(DUCC0_VERSION b0beb85e03982344a31ebb119758d7aa3ef5d362) set(FINUFFT_FFTW_LIBRARIES) - include(cmake/setupCPM.cmake) include(cmake/setupXSIMD.cmake) if(FINUFFT_USE_DUCC0) include(cmake/setupDUCC.cmake) diff --git a/cmake/setupSphinx.cmake b/cmake/setupSphinx.cmake new file mode 100644 index 000000000..996419b5c --- /dev/null +++ b/cmake/setupSphinx.cmake @@ -0,0 +1,21 @@ +cpmaddpackage( + NAME + sphinx_cmake + GIT_REPOSITORY + https://github.com/k0ekk0ek/cmake-sphinx.git + GIT_TAG + e13c40a + DOWNLOAD_ONLY + YES) + +list(APPEND CMAKE_MODULE_PATH ${sphinx_cmake_SOURCE_DIR}/cmake/Modules) + +# requires pip install sphinx texext +find_package(Sphinx) +if(SPHINX_FOUND) + message(STATUS "Sphinx found") + sphinx_add_docs(finufft_sphinx BUILDER html SOURCE_DIRECTORY + ${FINUFFT_SOURCE_DIR}/docs) +else() + message(STATUS "Sphinx not found docs will not be generated") +endif() diff --git a/docs/devnotes.rst b/docs/devnotes.rst index 11dca3e95..1fde88820 100644 --- a/docs/devnotes.rst +++ b/docs/devnotes.rst @@ -4,7 +4,8 @@ Developer notes =============== * Developers needing to update/regenerate documentation in general, including our readthedocs website, see ``docs/README``. Developers changing MATLAB/octave interfaces or docs, also see ``matlab/README``. Please also see ``contributing.md`` for code style and git hook guidelines. - +* cmake supports sphinx generation one can do by ``cmake --build . --target finufft_sphinx``. This will crete a folder called finufft_sphinx in your build directory, opening ``index.html`` will preview the updated documentation. +* cmake sphinx requires shpinx and texext to be installed in python * To update the version number, this needs to be done by hand in the following places: - ``CMakeLists.txt`` for cmake @@ -27,11 +28,11 @@ Developer notes * The kernel function in spreadinterp is evaluated via piecewise-polynomial approximation (Horner's rule). The code for this is auto-generated in MATLAB, for all upsampling factors. There are two versions supported: - 2018--2024 vintage: no explicit SIMD vectorization, C code is generated code for the Horner evaluation loop, by running from MATLAB `gen_all_horner_C_code.m` - + - post-2024 vintage: explicit SIMD and many other acceleration tricks, and the generated code is a static C++ array of coefficients, and their sizes (`nc` or number of coefficients) for each width `w`. Run from MATLAB `gen_ker_horner_loop_cpp_code.m` See `devel/README` for more details. The ES kernel coefficient and poly approx degree for both of the above are defined in a single location, `devel/get_degree_and_beta.m`, which must match the C++ `setup_spreader()` function. - + * Continuous Integration (CI). See files for this in ``.github/workflows/``. It currently tests the default ``makefile`` settings in linux, and three other ``make.inc.*`` files covering OSX and Windows (MinGW). CI does not test build the variant OMP=OFF. The dev should test these locally. Likewise, the Julia wrapper is separate and thus not tested in CI. We have added ``JenkinsFile`` for the GPU CI via python wrappers. * **Installing MWrap**. This is needed only for experts to rebuild the matlab/octave interfaces. @@ -43,7 +44,7 @@ Developer notes Make sure to override the location of MWrap by adding a line such as:: MWRAP = your-path-to-mwrap-executable - + to your ``make.inc``, and then you can use the ``make mex`` task. * The cufinufft Python wheels are generated using Docker based on the manylinux2014 image. For instructions, see ``tools/cufinufft/distribution_helper.sh``. These are binary wheels that are built using CUDA 11 (or optionally CUDA 12, but these are not distributed on PyPI) and bundled with the necessary libraries. diff --git a/docs/install.rst b/docs/install.rst index a30bea36c..8575f1298 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -12,19 +12,19 @@ a precompiled binary for your platform under Assets for various `releases `_. Please post an `Issue `_ to document your installation problem. +When using CMake, finufft requires no external dependencies except (c/c++ compilers supporting OpenMP). +However GNU ``makefile`` assumes that FFTW (single/double) are installed. -.. warning:: - - finufft builds with no issues on Linux using any compiler, in our experience GCC-13 gives best performance. - On MacOS both GCC and clang are fine. - On Windows MSVC works fine. The llvm toolchain included in Visual Studio does not seem to have OpenMP. - The official LLVM distribution builds finufft but debug builds using sanitizers break. +.. note:: + finufft builds with no issues on Linux and MacOS using any compiler, in our experience GCC-13 gives best performance. + On Windows MSVC works fine. The llvm toolchain included in Visual Studio does not seem to have OpenMP, it is possible to build single-threaded FINUFFT. + The official windows LLVM distribution builds finufft with no issues but debug builds using sanitizers break. .. note:: On windows finufft built with MSVC requires ``VCOMP140D.DLL`` which is part of the `Microsoft Visual C++ Redistributable `_. + It is likely to be already installed in your system. If the library is built with LLVM it requires ``libomp140.x86.64.dll``, more information `here `_. - Python-only users can simply install via ``pip install finufft`` which downloads a generic binary from PyPI. Only if you prefer a custom compilation, see :ref:`below`. CMake CPM Based Installation @@ -39,10 +39,14 @@ Then add the following to your ``CMakeLists.txt``: .. code-block:: cmake + # short version + CPMAddPackage("gh:flatironinstitute/finufft@2.3") + + # alternative in case custom options are needed CPMAddPackage( NAME Finufft GIT_REPOSITORY https://github.com/flatironinstitute/finufft.git - GIT_TAG master + GIT_TAG 2.3 GIT_SHALLOW Yes GIT_PROGRESS Yes EXCLUDE_FROM_ALL Yes @@ -61,6 +65,7 @@ which is provided directly by cmake. To do so add the following to your ``CMakeLists.txt``: .. code-block:: cmake + include(FetchContent) # Define the finufft library @@ -76,6 +81,8 @@ To do so add the following to your ``CMakeLists.txt``: # Optionally, link the finufft library to your target target_link_libraries(your_executable [PUBLIC|PRIVATE|INTERFACE] finufft) +Then cmake will automatically download the library and link it to your executable. + CMake Based Installation ------------------------ @@ -96,7 +103,7 @@ The basic quick download, building, and test is then: If you don't supply `--install-prefix`, it will default to ``/usr/local`` on most systems. If you don't have root access, you must supply a prefix you can write to such as ``$HOME/local``. -In ``build``, this creates ``libfinufft_static.a`` and ``libfinufft.so``, and runs a test that should take a +In ``build``, this creates ``libfinufft.a`` or ``libfinufft.so``, and runs a test that should take a few seconds and report ``100% tests passed, 0 tests failed out of 17``. To use the library, link against either the static or dynamic library in ``build`` or your installed version (i.e. ``/path/to/install/lib64/libfinufft.so`` or ``/path/to/install/lib/libfinufft.so``). If you install @@ -164,7 +171,7 @@ If there is an error in testing on what you consider a standard set-up, please file a detailed bug report as a New Issue at https://github.com/flatironinstitute/finufft/issues -Quick linux install instructions +Quick linux GNU MAKE install instructions -------------------------------- Make sure you have packages ``fftw3`` and ``fftw3-dev`` (or their @@ -240,7 +247,7 @@ This compiles the main libraries then runs double- and single-precision tests, e .. note:: GCC versions on linux: long-term linux distros ship old GCC versions - that may not be C++14 compatible. We recommend that you + that may not be C++17 compatible. We recommend that you compile with a recent GCC, at least GCC 7.3 (which we used for benchmarks in 2018 in our SISC paper), or GCC 9+. We do not recommend GCC versions prior to 7. We also **do not recommend GCC8** since @@ -445,7 +452,7 @@ section of ``mexopts.sh``. -3) Windows: tips for compiling +3) Windows GNU MAKE: tips for compiling ------------------------------- We have users who have adjusted the makefile to work - at least to some extent - on Windows 10. If you are only interested in calling from Octave (which already comes with MinGW-w64 and FFTW), then we have been told this can be done very simply: from within Octave, go to the ``finufft`` directory and do ``system('make octave')``. You may have to tweak ``OCTAVE`` in your ``make.inc`` in a similar fashion to below.