Skip to content

Commit 933d71f

Browse files
blapieblapie
authored
Port documentation from html to markdown (#564)
The website is now rendered to html using https://just-the-docs.com/ template, thus providing navigation menu and search engine. Sections' landing pages are rendered in Github UI (section/README.md) and on website (section/index.html). Links to other pages work in both Github and website thanks to permalinks. Move images to img/ and sources to src/
1 parent 58ca089 commit 933d71f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

81 files changed

+23208
-33254
lines changed

‎.github/workflows/build-as-subproject.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,8 @@ jobs:
4848
# Create new project
4949
mkdir -p ~/project
5050
# Move examples to root of project
51-
cp docs/CMakeLists.txt.nested ~/project/CMakeLists.txt
52-
cp docs/hellox86.c docs/tutorial.c ~/project/
51+
cp docs/src/CMakeLists.txt.nested ~/project/CMakeLists.txt
52+
cp docs/src/hellox86.c docs/src/tutorial.c ~/project/
5353
# Copy SLEEF sources to project
5454
cd .. && cp -r sleef ~/project/
5555
@@ -105,8 +105,8 @@ jobs:
105105
# Create new project
106106
mkdir -p ~/project
107107
# Move examples to root of project
108-
cp docs/CMakeLists.txt ~/project/
109-
cp docs/hellox86.c docs/tutorial.c ~/project/
108+
cp docs/src/CMakeLists.txt ~/project/
109+
cp docs/src/hellox86.c docs/src/tutorial.c ~/project/
110110
# Add some toolchain files
111111
cp -r toolchains ~/project/
112112

‎.github/workflows/build-examples.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,13 +86,13 @@ jobs:
8686
- name: Hello example native
8787
shell: bash -ex -o pipefail {0}
8888
run: |
89-
gcc docs/hellox86.c -static -o _examples-native/hellox86 -I_install-native/include -L_install-native/lib -lsleef
89+
gcc docs/src/hellox86.c -static -o _examples-native/hellox86 -I_install-native/include -L_install-native/lib -lsleef
9090
./_examples-native/hellox86
9191
9292
- name: DFT example native
9393
shell: bash -ex -o pipefail {0}
9494
run: |
95-
gcc docs/tutorial.c -static -o _examples-native/dft -I_install-native/include -L_install-native/lib -lsleef -lsleefdft -lsleefscalar -lm -fopenmp
95+
gcc docs/src/tutorial.c -static -o _examples-native/dft -I_install-native/include -L_install-native/lib -lsleef -lsleefdft -lsleefscalar -lm -fopenmp
9696
./_examples-native/dft
9797
./_examples-native/dft
9898

‎.github/workflows/pages.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# This workflow uses actions that are not certified by GitHub.
2+
# They are provided by a third-party and are governed by
3+
# separate terms of service, privacy policy, and support
4+
# documentation.
5+
6+
# Sample workflow for building and deploying a Jekyll site to GitHub Pages
7+
name: Deploy Jekyll site to Pages
8+
9+
on:
10+
push:
11+
branches: ["main"]
12+
paths:
13+
- "docs/**"
14+
15+
# Allows you to run this workflow manually from the Actions tab
16+
workflow_dispatch:
17+
18+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
19+
permissions:
20+
contents: read
21+
pages: write
22+
id-token: write
23+
24+
# Allow one concurrent deployment
25+
concurrency:
26+
group: "pages"
27+
cancel-in-progress: true
28+
29+
jobs:
30+
# Build job
31+
build:
32+
runs-on: ubuntu-latest
33+
defaults:
34+
run:
35+
# sources located in /docs
36+
working-directory: docs
37+
steps:
38+
- name: Checkout
39+
uses: actions/checkout@v4
40+
- name: Setup Ruby
41+
uses: ruby/setup-ruby@v1
42+
with:
43+
ruby-version: '3.3' # Not needed with a .ruby-version file
44+
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
45+
cache-version: 0 # Increment this number if you need to re-download cached gems
46+
working-directory: '${{ github.workspace }}/docs' # sources located in /docs
47+
- name: Setup Pages
48+
id: pages
49+
uses: actions/configure-pages@v5
50+
- name: Build with Jekyll
51+
# Outputs to the './_site' directory by default
52+
run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
53+
env:
54+
JEKYLL_ENV: production
55+
- name: Upload artifact
56+
# Automatically uploads an artifact from the './_site' directory by default
57+
uses: actions/upload-pages-artifact@v3
58+
with:
59+
path: "docs/_site/"
60+
61+
# Deployment job
62+
deploy:
63+
environment:
64+
name: github-pages
65+
url: ${{ steps.deployment.outputs.page_url }}
66+
runs-on: ubuntu-latest
67+
needs: build
68+
steps:
69+
- name: Deploy to GitHub Pages
70+
id: deployment
71+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ cmake --build build -j --clean-first
183183
ctest --test-dir build -j
184184
```
185185

186-
For more detailed build instructions please refer to the [dedicated section on CMake](./docs/build-with-cmake.md) or to [our web page][build_info_url].
186+
For more detailed build instructions please refer to the [dedicated section on CMake](./docs/1-user-guide/build-with-cmake) or to [our web page][build_info_url].
187187

188188
## Install SLEEF
189189

‎docs/1-user-guide/README.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
---
2+
layout: default
3+
title: User Guide
4+
nav_order: 2
5+
has_children: true
6+
permalink: /1-user-guide/
7+
---
8+
9+
<h1>User Guide</h1>
10+
11+
Guidelines on how to compile and install the library.
12+
13+
<h2>Table of contents</h2>
14+
15+
* [Preliminaries](#preliminaries)
16+
* [Quick start](#quickstart)
17+
* [Compiling and installing the library on Linu](#linux)
18+
* [Compiling the library with Microsoft Visual C++](#MSVC)
19+
* [Compiling and running "Hello SLEEF"](#hello)
20+
* [Importing SLEEF into your project](#import)
21+
* [Cross compilation for iOS and Android](#cross)
22+
23+
<h2 id="preliminaries">Preliminaries</h2>
24+
25+
In order to build SLEEF, you need [CMake](http://www.cmake.org/), which is an
26+
open-source and cross-platform building tool.
27+
28+
CMake works by allowing the developer to specify build parameters and rules in
29+
a simple text file that cmake then processes to generate project files for the
30+
actual native build tools (e.g. UNIX Makefiles, Microsoft Visual Studio, Apple
31+
XCode, etc). If you are not already familiar with cmake, please refer to the
32+
[official documentation](https://cmake.org/documentation/) or the [basic
33+
introductions in the
34+
wiki](https://gitlab.kitware.com/cmake/community/-/wikis/home).
35+
36+
<h2 id="quickstart">Quick start</h2>
37+
38+
You will find quick start instructions in the sources or via GitHub in the
39+
[README.md](https://github.com/shibatch/sleef/blob/master/README.md#how-to-build-sleef)
40+
file.
41+
42+
A more detailed description of CMake usage is provided in the [Build with
43+
CMake](build-with-cmake) page, along with [a list of CMake
44+
variables](build-with-cmake#sleef-variables) relevant to users.
45+
46+
<h2 id="linux">Compiling and installing the library on Linux</h2>
47+
48+
In order to build the library, you may want to install OpenMP (optional).
49+
50+
In order to test the library, you need to install:
51+
52+
* [the GNU MPFR Library](http://www.mpfr.org/) - libmpfr,
53+
* [Libssl](https://wiki.openssl.org/index.php/Libssl_API) - openssl (recommended),
54+
and you may want to install
55+
* [FFTW](http://www.fftw.org/) - libfftw3 (recommended).
56+
57+
Availability of these libraries are checked upon execution of cmake.
58+
59+
Please run the following from the root directory of SLEEF:
60+
61+
```sh
62+
sudo apt-get install libmpfr-dev libssl-dev libfftw3-dev
63+
cmake -S . -B build/ ..
64+
cmake --build build/ --clean-first -j
65+
ctest --test-dir build/ -j
66+
sudo cmake --install build/ --prefix /path/to/install/dir
67+
```
68+
69+
In order to uninstall the libraries and headers, run the following command.
70+
71+
```sh
72+
sudo xargs rm -v < build/install_manifest.txt
73+
```
74+
75+
<h3 id="lto">Building the library with LTO support</h3>
76+
77+
You can build the library with [link time opimization(LTO)](../3-extra#lto)
78+
support with the following commands. Note that you can only build static
79+
libraries with LTO support. You also have to use the same compiler with the
80+
same version to build the library and other source codes.
81+
82+
```sh
83+
CC=gcc cmake -DBUILD_SHARED_LIBS=FALSE -DSLEEF_ENABLE_LTO=TRUE ..
84+
```
85+
86+
In order to build the library with thinLTO support with clang, you need to
87+
specify LLVM AR command that exactly corresponds to the clang compiler.
88+
89+
```sh
90+
CC=clang-9 cmake -DBUILD_SHARED_LIBS=FALSE -DSLEEF_ENABLE_LTO=TRUE -DSLEEF_LLVM_AR_COMMAND=llvm-ar-9 ..
91+
```
92+
93+
<h3 id="inline">Building the header files for inlining the whole SLEEF functions</h3>
94+
95+
[Header files for inlining the whole SLEEF functions](../3-extra#inline) can be
96+
built with the following commands. With these header files, it may be easier to
97+
inline the whole SLEEF functions than using LTO. You have to specify
98+
`-ffp-contract=off` compiler option when compiling a source code that includes
99+
one of these header files.
100+
101+
```sh
102+
cmake -DSLEEF_BUILD_INLINE_HEADERS=TRUE ..
103+
```
104+
105+
<h2 id="MSVC">Compiling the library with Microsoft Visual C++</h2>
106+
107+
You need Visual Studio 2019. Open developer command prompt for VS2019 and
108+
change directory to sleef root. When configuring a build with CMake, you need to
109+
use a specific generator: `cmake -G"Visual Studio 16 2019" ..` This generator
110+
will create a proper solution `SLEEF.sln` under the build directory. You can
111+
still use `cmake --build .` to build the library without opening Visual Studio.
112+
113+
Below is an example of commands for building SLEEF with Visual Studio.
114+
115+
```sh
116+
mkdir build
117+
cd build
118+
cmake -G"Visual Studio 15 2017 Win64" .. &:: If you are using VS2017
119+
cmake -G"Visual Studio 16 2019" .. &:: If you are using VS2019
120+
cmake --build . --config Release -- /maxcpucount:1
121+
```
122+
123+
<h3 id="cow">Compiling the library with Clang on Windows</h3>
124+
125+
You need Visual Studio 2019. Install ninja via VS2019 installer. Download and
126+
install clang on Windows from
127+
[llvm.org](https://releases.llvm.org/download.html). Below is an example of
128+
commands for building SLEEF with Clang on Windows.
129+
130+
```sh
131+
"c:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
132+
cmake -S . -B build -GNinja -DCMAKE_C_COMPILER:PATH="C:\Program Files\LLVM\bin\clang.exe" ..
133+
cmake --build build --clean-first
134+
```
135+
136+
<h2 id="hello">Compiling and running "Hello SLEEF"</h2>
137+
138+
Now, let's try compiling the [source code shown in Fig.
139+
2.1](../src/hellox86.c).
140+
141+
```c
142+
#include <stdio.h>
143+
#include <x86intrin.h>
144+
#include <sleef.h>
145+
int main(int argc, char **argv) {
146+
double a[] = {2, 10};
147+
double b[] = {3, 20};
148+
__m128d va, vb, vc;
149+
va = _mm_loadu_pd(a);
150+
vb = _mm_loadu_pd(b);
151+
vc = Sleef_powd2_u10(va, vb);
152+
double c[2];
153+
_mm_storeu_pd(c, vc);
154+
printf("pow(%g, %g) = %g\n", a[0], b[0], c[0]);
155+
printf("pow(%g, %g) = %g\n", a[1], b[1], c[1]);
156+
}
157+
```
158+
<p style="text-align:center;">
159+
Fig. 2.1: <a href="../src/hellox86.c">Source code for testing</a>
160+
</p>
161+
162+
```sh
163+
gcc hellox86.c -o hellox86 -lsleef
164+
./hellox86
165+
pow(2, 3) = 8
166+
pow(10, 20) = 1e+20
167+
```
168+
<p style="text-align:center;">
169+
Fig. 2.2: Commands for compiling and executing hellox86.c
170+
</p>
171+
172+
You may need to set `LD_LIBRARY_PATH` environment variable appropriately. If
173+
you are trying to execute the program on Mac OSX or Windows, try copying the
174+
DLLs to the current directory.
175+
176+
<h2 id="import">Importing SLEEF into your project</h2>
177+
178+
Below is an example [CMakeLists.txt](../src/CMakeLists.txt) for compiling the
179+
above hellox86.c. CMake will automatically download SLEEF from GitHub
180+
repository, and thus there is no need to include SLEEF in your software
181+
package. If you prefer importing SLEEF as a submodule in git, you can use
182+
`SOURCE_DIR` option instead of `GIT_REPOSITORY` option for
183+
`ExternalProject_Add`.
184+
185+
```cmake
186+
cmake_minimum_required(VERSION 3.5.1)
187+
include(ExternalProject)
188+
find_package(Git REQUIRED)
189+
190+
ExternalProject_Add(libsleef
191+
GIT_REPOSITORY https://github.com/shibatch/sleef
192+
CMAKE_ARGS -DCMAKE_INSTALL_PREFIX=${CMAKE_BINARY_DIR}/contrib
193+
)
194+
195+
include_directories(${CMAKE_BINARY_DIR}/contrib/include)
196+
link_directories(${CMAKE_BINARY_DIR}/contrib/lib)
197+
198+
add_executable(hellox86 hellox86.c)
199+
add_dependencies(hellox86 libsleef)
200+
target_link_libraries(hellox86 sleef)
201+
```
202+
<p style="text-align:center;">
203+
Fig. 2.3: <a href="../src/CMakeLists.txt">Example CMakeLists.txt</a>
204+
</p>
205+
206+
207+
<h2 id="cross">Cross compilation for iOS and Android</h2>
208+
209+
SLEEF has preliminary support for iOS and Android. Here, "preliminary" means
210+
that the library is only tested to be built, but not tested to work correctly
211+
on the real devices. In order to cross compile the library, you need a cmake
212+
tool chain file for the corresponding OS. The tool chain file for iOS can be
213+
downloaded from
214+
[https://github.com/leetal/ios-cmake](https://github.com/leetal/ios-cmake).
215+
The tool chain file for Android is included in the SDK. You first need to build
216+
the library for the host computer, then for the target OS. Below is an example
217+
sequence of commands for cross compiling the library for iOS.
218+
219+
```sh
220+
mkdir build-native
221+
cd build-native
222+
cmake -GNinja ..
223+
ninja
224+
cd ..
225+
mkdir build-cross
226+
cd build-cross
227+
cmake -GNinja -DCMAKE_TOOLCHAIN_FILE=../ios.toolchain.cmake -DNATIVE_BUILD_DIR=`pwd`/../build-native -DSLEEF_DISABLE_MPFR=TRUE -DSLEEF_DISABLE_SSL=TRUE ..
228+
ninja
229+
```
230+
231+
Below is an example sequence of commands for cross compiling the library for
232+
Android.
233+
234+
```sh
235+
mkdir build-native
236+
cd build-native
237+
cmake -GNinja ..
238+
ninja
239+
cd ..
240+
mkdir build-cross
241+
cd build-cross
242+
cmake -GNinja -DCMAKE_TOOLCHAIN_FILE=/opt/android-ndk-r21d/build/cmake/android.toolchain.cmake -DNATIVE_BUILD_DIR=`pwd`/../build-native -DANDROID_ABI=arm64-v8a ..
243+
ninja
244+
```
245+

0 commit comments

Comments
 (0)
⚡