Skip to content

Commit

Permalink
Remove duplicate build instructions from website.
Browse files Browse the repository at this point in the history 
These can already be visualised in source or on github.
  • Loading branch information
@blapie
blapie committed Jan 15, 2024
1 parent 94ecd7b commit 0d42925
Show file tree
Hide file tree
Showing 3 changed files with 128 additions and 189 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
159 changes: 124 additions & 35 deletions doc/build-with-cmake.md
View file
Original file line number Diff line number Diff line change
@@ -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 `<prefix>`

```
$ make test
cmake --install build/ [--prefix <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=<value> <cmake-build-dir>
cmake -UVARIABLE <cmake-build-dir>
```

Build configurations allow a project to be built in different ways for debug,
optimized, or any other special set of flags.

Expand All @@ -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

<!-- Repository links -->

[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
156 changes: 3 additions & 153 deletions doc/html/compile.xhtml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,159 +64,9 @@ introductions in the wiki</a>.
<h3>Quick start</h3>

<p class="noindent">
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.
</p>
<pre class="command">$ cmake --version</pre>

<p class="noindent">
2. Checkout out the source code from our <a class="underlined"
href="https://github.com/shibatch/sleef">GitHub repository</a>.
</p>
<pre class="command">$ git clone https://github.com/shibatch/sleef</pre>

<p class="noindent">
3. Make a separate directory to create an out-of-source build. SLEEF does not
allow for in-tree builds.
</p>
<pre class="command">$ cd sleef
$ mkdir build &amp;&amp; cd build</pre>

<p class="noindent">
4. Run cmake to configure your project and generate the system to build it:
</p>
<pre class="command">$ cmake ..</pre>

<p class="noindent">
See the list of <a class="underlined" href="#cmakevars">options and
variables</a> for customizing your build.
</p>

<p class="noindent" style="margin-top: 1em;">
5. Now that you have the build files created by cmake, proceed from the top
of the build directory:
</p>
<pre class="command">$ make</pre>

<p class="noindent">
6. You can execute the tests by running:
</p>
<pre class="command">$ make test</pre>

<p class="noindent">
7. Install the library under ../my-sleef/install by running:
</p>
<pre class="command">$ make install</pre>


<h4 id="cmakevars">Common CMake variables</h4>

<p>
Below is the list of common cmake variables that are used to
configure a build for SLEEF.
</p>

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

<h4>SLEEF-specific CMake variables</h4>

<p>
Below is the list of SLEEF-specific cmake variables.
</p>

<ul style="margin-top: 1em; margin-bottom: 1em;">
<!-- Options for building the entire library -->
<li><b>SLEEF_SHOW_CONFIG</b> : Show relevant
cmake variables upon configuring a build</li>
<li><b>SLEEF_SHOW_ERROR_LOG</b> : Show the content of
CMakeError.log</li>
<li><b>BUILD_TESTS</b> : Avoid building testing
tools if set to FALSE</li>
<li><b>ENABLE_ALTDIV</b> : Enable alternative division method (aarch64 only)</li>
<li><b>ENABLE_ALTSQRT</b> : Enable alternative sqrt method (aarch64 only)</li>
<li><b>DISABLE_LONG_DOUBLE</b> : Disable support for long double data type</li>
<li><b>ENFORCE_LONG_DOUBLE</b> : Build fails if long double data type is
not supported by the compiler</li>
<li><b>DISABLE_FLOAT128</b> : Disable support for float128 data type</li>
<li><b>ENFORCE_FLOAT128</b> : Build fails if float128 data type is not
supported by the compiler</li>
<li><b>DISABLE_OPENMP</b> : Disable support for OpenMP</li>
<li><b>ENFORCE_OPENMP</b> : Build fails if OpenMP is not
supported by the compiler</li>

<!-- Options for LTO -->
<li><b>ENABLE_LTO</b> : Enable support for LTO with gcc, or thinLTO
with llvm</li>
<li><b>LLVM_AR_COMMAND</b> : Specify LLVM AR command when you build
the library with thinLTO support with clang.</li>
<li><b>SLEEF_ENABLE_LLVM_BITCODE</b> : Generate LLVM bitcode</li>
<li><b>BUILD_INLINE_HEADERS</b> : Generate header files for inlining
whole SLEEF functions</li>

<!-- Options regarding to vector extensions -->
<li style="margin-top: 1em;"><b>DISABLE_SSE2</b> : Disable support for x86 SSE2</li>
<li><b>ENFORCE_SSE2</b> : Build fails if SSE2 is not
supported by the compiler</li>
<li><b>DISABLE_SSE4</b> : Disable support for x86 SSE4</li>
<li><b>ENFORCE_SSE4</b> : Build fails if SSE4 is not
supported by the compiler</li>
<li><b>DISABLE_AVX</b> : Disable support for x86 AVX</li>
<li><b>ENFORCE_AVX</b> : Build fails if AVX is not
supported by the compiler</li>
<li><b>DISABLE_FMA4</b> : Disable support for x86 FMA4</li>
<li><b>ENFORCE_FMA4</b> : Build fails if FMA4 is not
supported by the compiler</li>
<li><b>DISABLE_AVX2</b> : Disable support for x86 AVX2</li>
<li><b>ENFORCE_AVX2</b> : Build fails if AVX2 is not
supported by the compiler</li>
<li><b>DISABLE_AVX512F</b> : Disable support for x86 AVX512F</li>
<li><b>ENFORCE_AVX512F</b> : Build fails if AVX512F is not
supported by the compiler</li>
<li><b>DISABLE_SVE</b> : Disable support for AArch64 SVE</li>
<li><b>ENFORCE_SVE</b> : Build fails if SVE is not
supported by the compiler</li>
<li><b>DISABLE_VSX</b> : Disable support for PowerPC VSX</li>
<li><b>ENFORCE_VSX</b> : Build fails if VSX is not
supported by the compiler</li>
<li><b>DISABLE_ZVECTOR2</b> : Disable support for ZVECTOR2</li>
<li><b>ENFORCE_ZVECTOR2</b> : Build fails if ZVECTOR2 is not
supported by the compiler</li>

<!-- Options for libm -->
<li style="margin-top: 1em;"><b>BUILD_GNUABI_LIBS</b> : Avoid building
libraries with GNU ABI if set to FALSE</li>
<li><b>ENFORCE_TESTER3</b> : Build fails if
tester3 cannot be built</li>

<!-- Options for DFT -->
<li style="margin-top: 1em;"><b>BUILD_DFT</b> : Avoid building DFT
libraries if set to FALSE</li>
<li><b>SLEEFDFT_MAXBUTWIDTH</b> : 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.</li>
<li><b>DISABLE_FFTW</b> : Disable FFW-based testing of the DFT
library.</li>

<!-- Options for Quad -->
<li style="margin-top: 1em;"><b>BUILD_QUAD</b> : An <b>experimental</b> quad-precision
library will be built if set to TRUE</li>
</ul>
You will find quick start instructions in the sources or via GitHub in the
<a class="underlined" href="https://github.com/shibatch/sleef/blob/master/README.md">README.md</a>
file.

<h2 id="linux">Compiling and installing the library on Linux</h2>

Expand Down

0 comments on commit 0d42925

Please sign in to comment.