From 0d42925526c1291bbaa4537394eeeefbb798b40b Mon Sep 17 00:00:00 2001 From: Pierre Blanchard Date: Thu, 4 Jan 2024 16:17:10 +0000 Subject: [PATCH] Remove duplicate build instructions from website. These can already be visualised in source or on github. --- README.md | 2 +- doc/build-with-cmake.md | 159 +++++++++++++++++++++++++++++++--------- doc/html/compile.xhtml | 156 +-------------------------------------- 3 files changed, 128 insertions(+), 189 deletions(-) diff --git a/README.md b/README.md index c6882e19..feeb238e 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,7 @@ cmake --build build -j --clean-first ctest --test-dir build -j ``` -Refer to our web page for [detailed build instructions][build_info_url]. +For more detailed build instructions please refer to the [dedicated section on CMake](./doc/build-with-cmake.md) or to [our web page][build_info_url]. ## Install SLEEF diff --git a/doc/build-with-cmake.md b/doc/build-with-cmake.md index aa41c2f5..9bb09339 100644 --- a/doc/build-with-cmake.md +++ b/doc/build-with-cmake.md @@ -1,92 +1,113 @@ # Introduction -[Cmake](http://www.cmake.org/) is an open-source and cross-platform building +[CMake](http://www.cmake.org/) is an open-source and cross-platform building tool for software packages that provides easy managing of multiple build systems at a time. It works by allowing the developer to specify build parameters and -rules in a simple text file that cmake then processes to generate project files +rules in a simple text file that CMake then processes to generate project files for the actual native build tools (e.g. UNIX Makefiles, Microsoft Visual Studio, Apple XCode, etc). That means you can easily maintain multiple separate builds for one project and manage cross-platform hardware and software complexity. -If you are not already familiar with cmake, please refer to the [official +If you are not already familiar with CMake, please refer to the [official documentation](https://cmake.org/documentation/) or the [Basic Introductions](https://cmake.org/Wiki/CMake#Basic_Introductions) in the wiki (recommended). Before using CMake you will need to install/build the binaries on your system. -Most systems have cmake already installed or provided by the standard package +Most systems have CMake already installed or provided by the standard package manager. If that is not the case for you, please [download](https://cmake.org/download/) and install now. -For building SLEEF, version 3.18 is the minimum required. + +**For building SLEEF, CMake 3.18 is the minimum required.** # Quick start -1. Make sure cmake is available on the command-line. +1. Make sure CMake is available. The following command line should display a +version number greater than or equal to 3.18. + ``` -$ cmake --version -(should display a version number greater than or equal to 3.18) +cmake --version ``` -2. Download the tar from the -[software repository](http://shibatch.sourceforge.net/) -or checkout out the source code from the -[github repository](https://github.com/shibatch/sleef): +2. Download the tar from [sourceforge][forge_url], +[GitHub releases][release_url], or checkout out the source code from the +[GitHub repository][repo_url]. + ``` -$ git clone https://github.com/shibatch/sleef +git clone https://github.com/shibatch/sleef ``` -3. Make a separate directory to create an out-of-source build. SLEEF does not -allow for in-tree builds. +3. Make separate directories to create out-of-source build and install. SLEEF +does not allow for in-tree builds. + ``` -$ cd sleef-project -$ mkdir my-sleef-build && cd my-sleef-build +cd sleef +mkdir build +mkdir install ``` -4. Run cmake to configure your project and generate the system to build it: +4. Run CMake to configure your project and generate the system to build it. + ``` -$ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo \ - -DCMAKE_INSTALL_PREFIX=../my-sleef-install \ - .. +cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo \ + -DCMAKE_INSTALL_PREFIX=install/ \ + -S . -B build/ ``` -This flag configures an optimised `libsleef` shared library build with basic -debug info. -By default, cmake will autodetect your system platform and configure the build + +By default, CMake will detect your system platform and configure the build using the default parameters. You can control and modify these parameters by -setting variables when running cmake. See the list of +setting variables when running CMake. See the list of [options and variables](#build-customization) for customizing your build. +In the above example: +- `-DCMAKE_BUILD_TYPE=RelWithDebInfo` configures an optimised `libsleef` +shared library build with basic debug info. +- `-DCMAKE_INSTALL_PREFIX=install/` sets SLEEF to be installed in `install/`. + +6. Run make to build the project + +``` +cmake --build build -j --clean-first +``` + > NOTE: On **Windows**, you need to use a specific generator like this: > `cmake -G"Visual Studio 14 2015 Win64" ..` specifying the Visual Studio version > and targeting specifically `Win64` (to support compilation of AVX/AVX2) > Check `cmake -G` to get a full list of supported Visual Studio project generators. > This generator will create a proper solution `SLEEF.sln` under the build -> directory. -> You can still use `cmake --build .` to build without opening Visual Studio. +> directory. +> You can still use `cmake --build build` to build without opening Visual Studio. + +7. Run ctest suite (CMake 3.20+) -5. Now that you have the build files created by cmake, proceed from the top -of the build directory: ``` -$ make sleef +ctest --test-dir build -j ``` -6. Install the library under ../my-sleef/install by running: +or for older CMake versions + ``` -$ make install +cd build/ && ctest -j ``` -7. You can execute the tests by running: +8. Install at path provided earlier or at new path `` + ``` -$ make test +cmake --install build/ [--prefix ] ``` +Refer to our web page for [detailed build instructions][build_info_url]. + # Build customization Variables dictate how the build is generated; options are defined and undefined, -respectively, on the cmake command line like this: +respectively, on the CMake command line like this: + ``` cmake -DVARIABLE= cmake -UVARIABLE ``` + Build configurations allow a project to be built in different ways for debug, optimized, or any other special set of flags. @@ -103,4 +124,72 @@ optimized, or any other special set of flags. Defaults to /usr/local on GNU/Linux and MacOS. Defaults to C:/Program Files on Windows. +- `CMAKE_C_FLAGS_RELEASE` : The optimization options used by the compiler. + ## SLEEF Variables + +### Library + +- `SLEEF_SHOW_CONFIG` : Show relevant CMake variables upon configuring a build +- `SLEEF_SHOW_ERROR_LOG` : Show the content of CMakeError.log + +- `BUILD_SHARED_LIBS` : Static libs are built if set to FALSE +- `BUILD_GNUABI_LIBS` : Avoid building libraries with GNU ABI if set to FALSE +- `BUILD_INLINE_HEADERS` : Generate header files for inlining whole SLEEF functions + +- `DISABLE_OPENMP` : Disable support for OpenMP +- `ENFORCE_OPENMP` : Build fails if OpenMP is not supported by the compiler + +- `ENABLE_LTO` : Enable support for LTO with gcc, or thinLTO with llvm +- `LLVM_AR_COMMAND` : Specify LLVM AR command when you build the library with thinLTO support with clang. +- `SLEEF_ENABLE_LLVM_BITCODE` : Generate LLVM bitcode + +### Tests + +- `BUILD_TESTS` : Avoid building testing tools if set to FALSE +- `ENFORCE_TESTER3` : Build fails if tester3 cannot be built + +### Quad and DFT + +- `BUILD_QUAD` : Build quad-precision libraries if set to TRUE +- `BUILD_DFT` : Build DFT libraries if set to TRUE +- `SLEEFDFT_MAXBUTWIDTH` : This variable specifies the maximum length of combined butterfly block used in the DFT. Setting this value to 7 makes DFT faster but compilation takes more time and the library size will be larger. +- `DISABLE_FFTW` : Disable FFTW-based testing of the DFT library. + +### Vector extensions and instructions + +- `ENABLE_ALTDIV` : Enable alternative division method (aarch64 only) +- `ENABLE_ALTSQRT` : Enable alternative sqrt method (aarch64 only) +- `DISABLE_LONG_DOUBLE` : Disable support for long double data type +- `ENFORCE_LONG_DOUBLE` : Build fails if long double data type is not supported by the compiler +- `DISABLE_FLOAT128` : Disable support for float128 data type +- `ENFORCE_FLOAT128` : Build fails if float128 data type is not supported by the compiler +- `DISABLE_SSE2` : Disable support for x86 SSE2 +- `ENFORCE_SSE2` : Build fails if SSE2 is not supported by the compiler +- `DISABLE_SSE4` : Disable support for x86 SSE4 +- `ENFORCE_SSE4` : Build fails if SSE4 is not supported by the compiler +- `DISABLE_AVX` : Disable support for x86 AVX +- `ENFORCE_AVX` : Build fails if AVX is not supported by the compiler +- `DISABLE_FMA4` : Disable support for x86 FMA4 +- `ENFORCE_FMA4` : Build fails if FMA4 is not supported by the compiler +- `DISABLE_AVX2` : Disable support for x86 AVX2 +- `ENFORCE_AVX2` : Build fails if AVX2 is not supported by the compiler +- `DISABLE_AVX512F` : Disable support for x86 AVX512F +- `ENFORCE_AVX512F` : Build fails if AVX512F is not supported by the compiler +- `DISABLE_SVE` : Disable support for AArch64 SVE +- `ENFORCE_SVE` : Build fails if SVE is not supported by the compiler +- `DISABLE_VSX` : Disable support for PowerPC VSX +- `ENFORCE_VSX` : Build fails if VSX is not supported by the compiler +- `DISABLE_VSX3` : Disable support for PowerPC VSX-3 +- `ENFORCE_VSX3` : Build fails if VSX-3 is not supported by the compiler +- `DISABLE_VXE` : Disable support for System/390 VXE +- `ENFORCE_VXE` : Build fails if System/390 VXE is not supported by the compiler +- `DISABLE_VXE2` : Disable support for System/390 VXE2 +- `ENFORCE_VXE2` : Build fails if System/390 VXE2 is not supported by the compiler + + + +[build_info_url]: https://sleef.org/compile.xhtml +[repo_url]: https://github.com/shibatch/sleef +[release_url]: https://github.com/shibatch/sleef/releases +[forge_url]: https://sourceforge.net/projects/sleef diff --git a/doc/html/compile.xhtml b/doc/html/compile.xhtml index 7a1213eb..dce9b178 100644 --- a/doc/html/compile.xhtml +++ b/doc/html/compile.xhtml @@ -64,159 +64,9 @@ introductions in the wiki.

Quick start

-1. Make sure cmake is available on the command-line. The command below -should display a version number greater than or equal to 3.5.1. -

-
$ cmake --version
- -

-2. Checkout out the source code from our GitHub repository. -

-
$ git clone https://github.com/shibatch/sleef
- -

-3. Make a separate directory to create an out-of-source build. SLEEF does not -allow for in-tree builds. -

-
$ cd sleef
-$ mkdir build && cd build
- -

-4. Run cmake to configure your project and generate the system to build it: -

-
$ cmake ..
- -

-See the list of options and -variables for customizing your build. -

- -

-5. Now that you have the build files created by cmake, proceed from the top -of the build directory: -

-
$ make
- -

-6. You can execute the tests by running: -

-
$ make test
- -

-7. Install the library under ../my-sleef/install by running: -

-
$ make install
- - -

Common CMake variables

- -

-Below is the list of common cmake variables that are used to -configure a build for SLEEF. -

- -
    -
  • CMAKE_BUILD_TYPE: By default, CMake supports the following configuration:
    • -
      -
    • `Release`: Basic optimizations are turned on. This is the default setting.
      • -
    • `Debug`: Basic debug flags are turned on. Optimization is disabled.
      • -
    • `MinSizeRel`: Builds the smallest (but not fastest) object code
      • -
    • `RelWithDebInfo`: Builds optimized code with debug information as well
      • -
    -
  • BUILD_SHARED_LIBS : Static libs are built if set to - FALSE
    • -
  • CMAKE_C_FLAGS_RELEASE : The optimization options used by - the compiler.
    • -
  • CMAKE_INSTALL_PREFIX : The prefix it uses when running - `make install`. Defaults to /usr/local on GNU/Linux and - MacOS. Defaults to C:/Program Files on Windows.
    • -
- -

SLEEF-specific CMake variables

- -

-Below is the list of SLEEF-specific cmake variables. -

- -
    - -
  • SLEEF_SHOW_CONFIG : Show relevant - cmake variables upon configuring a build
    • -
  • SLEEF_SHOW_ERROR_LOG : Show the content of - CMakeError.log
    • -
  • BUILD_TESTS : Avoid building testing - tools if set to FALSE
    • -
  • ENABLE_ALTDIV : Enable alternative division method (aarch64 only)
    • -
  • ENABLE_ALTSQRT : Enable alternative sqrt method (aarch64 only)
    • -
  • DISABLE_LONG_DOUBLE : Disable support for long double data type
    • -
  • ENFORCE_LONG_DOUBLE : Build fails if long double data type is - not supported by the compiler
    • -
  • DISABLE_FLOAT128 : Disable support for float128 data type
    • -
  • ENFORCE_FLOAT128 : Build fails if float128 data type is not - supported by the compiler
    • -
  • DISABLE_OPENMP : Disable support for OpenMP
    • -
  • ENFORCE_OPENMP : Build fails if OpenMP is not - supported by the compiler
    • - - -
  • ENABLE_LTO : Enable support for LTO with gcc, or thinLTO - with llvm
    • -
  • LLVM_AR_COMMAND : Specify LLVM AR command when you build - the library with thinLTO support with clang.
    • -
  • SLEEF_ENABLE_LLVM_BITCODE : Generate LLVM bitcode
    • -
  • BUILD_INLINE_HEADERS : Generate header files for inlining - whole SLEEF functions
    • - - -
  • DISABLE_SSE2 : Disable support for x86 SSE2
    • -
  • ENFORCE_SSE2 : Build fails if SSE2 is not - supported by the compiler
    • -
  • DISABLE_SSE4 : Disable support for x86 SSE4
    • -
  • ENFORCE_SSE4 : Build fails if SSE4 is not - supported by the compiler
    • -
  • DISABLE_AVX : Disable support for x86 AVX
    • -
  • ENFORCE_AVX : Build fails if AVX is not - supported by the compiler
    • -
  • DISABLE_FMA4 : Disable support for x86 FMA4
    • -
  • ENFORCE_FMA4 : Build fails if FMA4 is not - supported by the compiler
    • -
  • DISABLE_AVX2 : Disable support for x86 AVX2
    • -
  • ENFORCE_AVX2 : Build fails if AVX2 is not - supported by the compiler
    • -
  • DISABLE_AVX512F : Disable support for x86 AVX512F
    • -
  • ENFORCE_AVX512F : Build fails if AVX512F is not - supported by the compiler
    • -
  • DISABLE_SVE : Disable support for AArch64 SVE
    • -
  • ENFORCE_SVE : Build fails if SVE is not - supported by the compiler
    • -
  • DISABLE_VSX : Disable support for PowerPC VSX
    • -
  • ENFORCE_VSX : Build fails if VSX is not - supported by the compiler
    • -
  • DISABLE_ZVECTOR2 : Disable support for ZVECTOR2
    • -
  • ENFORCE_ZVECTOR2 : Build fails if ZVECTOR2 is not - supported by the compiler
    • - - -
  • BUILD_GNUABI_LIBS : Avoid building - libraries with GNU ABI if set to FALSE
    • -
  • ENFORCE_TESTER3 : Build fails if - tester3 cannot be built
    • - - -
  • BUILD_DFT : Avoid building DFT - libraries if set to FALSE
    • -
  • SLEEFDFT_MAXBUTWIDTH : This variable - specifies the maximum length of combined butterfly block used in the - DFT. Setting this value to 7 makes DFT faster but compilation takes - more time and the library size will be larger.
    • -
  • DISABLE_FFTW : Disable FFW-based testing of the DFT - library.
    • - - -
  • BUILD_QUAD : An experimental quad-precision - library will be built if set to TRUE
    • -
+You will find quick start instructions in the sources or via GitHub in the +README.md +file.

Compiling and installing the library on Linux