Skip to content

Commit 74be676

Browse files
martin-frbgmartin-frbg
authored
Merge pull request #5049 from rgommers/docs-buildsystem-page
Rewrite the "Build system" documentation page
2 parents 91d861a + f697cfe commit 74be676

File tree

6 files changed

+233
-137
lines changed

6 files changed

+233
-137
lines changed

‎.github/workflows/docs.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ jobs:
2323
python-version: "3.10"
2424

2525
- name: Install MkDocs and doc theme packages
26-
run: pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
26+
run: pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-mermaid2-plugin
2727

2828
- name: Build docs site
2929
run: mkdocs build

‎docs/build_system.md

Lines changed: 133 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,122 @@
1-
This page describes the Make-based build, which is the default/authoritative
2-
build method. Note that the OpenBLAS repository also supports building with
3-
CMake (not described here) - that generally works and is tested, however there
4-
may be small differences between the Make and CMake builds.
1+
!!! info "Supported build systems"
2+
3+
This page describes the Make-based build, which is the
4+
default/authoritative build method. Note that the OpenBLAS repository also
5+
supports building with CMake (not described here) - that generally works
6+
and is tested, however there may be small differences between the Make and
7+
CMake builds.
8+
9+
10+
## Makefile dependency graph
11+
12+
<!---
13+
An easy way to update this diagram is to copy it into https://mermaid.live
14+
and edit it interactively.
15+
-->
16+
17+
```mermaid
18+
flowchart LR
19+
A[Makefile] -->|included by many of the Makefiles in the subdirectories!| B(Makefile.system)
20+
B -->|triggered, not included, once by Makefile.system, and runs before any of the actual library code is built. builds and runs the 'getarch' tool for cpu identification, runs the compiler detection scripts c_check/f_check| C{Makefile.prebuild}
21+
C -->|either this or Makefile_kernel.conf is generated| D[Makefile.conf]
22+
C -->|temporary Makefile.conf during DYNAMIC_ARCH builds| E[Makefile_kernel.conf]
23+
B -->|defaults for build options that can be given on the make command line| F[Makefile.rule]
24+
B -->|architecture-specific compiler options and OpenBLAS buffer size values| G[Makefile.$ARCH]
25+
A --> exports
26+
A -->|directories: test, ctest, utest, cpp_thread_test| H(test directories)
27+
A --> I($BLASDIRS)
28+
I --> interface
29+
I --> driver/level2
30+
I --> driver/level3
31+
I --> driver/others
32+
A -->|for each target in DYNAMIC_CORE if DYNAMIC_ARCH=1| kernel
33+
A -->|subdirs: timing, testing, testing/EIG, testing/LIN| J($NETLIB_LAPACK_DIR)
34+
A --> relapack
35+
```
536

6-
!!! warning
7-
This page is made by someone who is not the developer and should not be considered as an official documentation of the build system. For getting the full picture, it is best to read the Makefiles and understand them yourself.
837

9-
## Makefile dep graph
38+
## Important Variables
1039

11-
```
12-
Makefile
13-
|
14-
|----- Makefile.system # !!! this is included by many of the Makefiles in the subdirectories !!!
15-
| |
16-
| |===== Makefile.prebuild # This is triggered (not included) once by Makefile.system
17-
| | | # and runs before any of the actual library code is built.
18-
| | | # (builds and runs the "getarch" tool for cpu identification,
19-
| | | # runs the compiler detection scripts c_check and f_check)
20-
| | |
21-
| | ----- (Makefile.conf) [ either this or Makefile_kernel.conf is generated ]
22-
| | | { Makefile.system#L243 }
23-
| | ----- (Makefile_kernel.conf) [ temporary Makefile.conf during DYNAMIC_ARCH builds ]
24-
| |
25-
| |----- Makefile.rule # defaults for build options that can be given on the make command line
26-
| |
27-
| |----- Makefile.$(ARCH) # architecture-specific compiler options and OpenBLAS buffer size values
28-
|
29-
|~~~~~ exports/
30-
|
31-
|~~~~~ test/
32-
|
33-
|~~~~~ utest/
34-
|
35-
|~~~~~ ctest/
36-
|
37-
|~~~~~ cpp_thread_test/
38-
|
39-
|~~~~~ kernel/
40-
|
41-
|~~~~~ ${SUBDIRS}
42-
|
43-
|~~~~~ ${BLASDIRS}
44-
|
45-
|~~~~~ ${NETLIB_LAPACK_DIR}{,/timing,/testing/{EIG,LIN}}
46-
|
47-
|~~~~~ relapack/
48-
```
40+
Most of the tunable variables are found in
41+
[Makefile.rule](https://github.com/xianyi/OpenBLAS/blob/develop/Makefile.rule),
42+
along with their detailed descriptions.
4943

50-
## Important Variables
44+
Most of the variables are detected automatically in
45+
[Makefile.prebuild](https://github.com/xianyi/OpenBLAS/blob/develop/Makefile.prebuild),
46+
if they are not set in the environment.
5147

52-
Most of the tunable variables are found in [Makefile.rule](https://github.com/xianyi/OpenBLAS/blob/develop/Makefile.rule), along with their detailed descriptions.<br/>
53-
Most of the variables are detected automatically in [Makefile.prebuild](https://github.com/xianyi/OpenBLAS/blob/develop/Makefile.prebuild), if they are not set in the environment.
48+
The most commonly used variables are documented below. There are more options
49+
though - please read the linked Makefiles if you want to see all variables.
5450

5551
### CPU related
56-
```
57-
ARCH - Target architecture (eg. x86_64)
58-
TARGET - Target CPU architecture, in case of DYNAMIC_ARCH=1 means library will not be usable on less capable CPUs
59-
TARGET_CORE - TARGET_CORE will override TARGET internally during each cpu-specific cycle of the build for DYNAMIC_ARCH
60-
DYNAMIC_ARCH - For building library for multiple TARGETs (does not lose any optimizations, but increases library size)
61-
DYNAMIC_LIST - optional user-provided subset of the DYNAMIC_CORE list in Makefile.system
62-
```
6352

64-
### Toolchain related
65-
```
66-
CC - TARGET C compiler used for compilation (can be cross-toolchains)
67-
FC - TARGET Fortran compiler used for compilation (can be cross-toolchains, set NOFORTRAN=1 if used cross-toolchain has no fortran compiler)
68-
AR, AS, LD, RANLIB - TARGET toolchain helpers used for compilation (can be cross-toolchains)
53+
- `ARCH`: target architecture (e.g., `x86-64`).
54+
- `DYNAMIC_ARCH`: For building library for multiple `TARGET`s (does not lose any
55+
optimizations, but increases library size).
56+
- `DYNAMIC_LIST`: optional user-provided subset of the `DYNAMIC_CORE` list in
57+
[Makefile.system](https://github.com/xianyi/OpenBLAS/blob/develop/Makefile.system).
58+
- `TARGET`: target CPU architecture. In case of `DYNAMIC_ARCH=1`, it means that
59+
the library will not be usable on less capable CPUs.
60+
- `TARGET_CORE`: override `TARGET` internally during each CPU-specific cycle of
61+
the build for `DYNAMIC_ARCH`.
6962

70-
HOSTCC - compiler of build machine, needed to create proper config files for target architecture
71-
HOST_CFLAGS - flags for build machine compiler
72-
```
7363

74-
### Library related
75-
```
76-
BINARY - 32/64 bit library
64+
### Toolchain related
7765

78-
BUILD_SHARED - Create shared library
79-
BUILD_STATIC - Create static library
66+
- `CC`: `TARGET` C compiler used for compilation (can be cross-toolchains).
67+
- `FC`: `TARGET` Fortran compiler used for compilation (can be cross-toolchains,
68+
set `NOFORTRAN=1` if the used cross-toolchain has no Fortran compiler).
69+
- `COMMON_OPT`: flags to add to all invocations of the target C and Fortran compilers
70+
(overrides `CFLAGS`/`FFLAGS` - prefer using `COMMON_OPT`)
71+
- `CCOMMON_OPT`: flags to add to all invocations of the target C compiler
72+
(overrides `CFLAGS`)
73+
- `FCOMMON_OPT`: flags to add to all invocations of the target Fortran compiler
74+
(overrides `FFLAGS`)
75+
- `LDFLAGS`: flags to add to all target linker invocations
76+
- `AR`, `AS`, `LD`, `RANLIB`: `TARGET` toolchain helpers used for compilation
77+
(can be cross-toolchains).
78+
- `HOSTCC`: compiler of build machine, needed to create proper config files for
79+
the target architecture.
80+
- `HOST_CFLAGS`: flags for the build machine compiler.
8081

81-
QUAD_PRECISION - enable support for IEEE quad precision [ largely unimplemented leftover from GotoBLAS, do not use ]
82-
EXPRECISION - Obsolete option to use float80 of SSE on BSD-like systems
83-
INTERFACE64 - Build with 64bit integer representations to support large array index values [ incompatible with standard API ]
8482

85-
BUILD_SINGLE - build the single-precision real functions of BLAS [and optionally LAPACK]
86-
BUILD_DOUBLE - build the double-precision real functions
87-
BUILD_COMPLEX - build the single-precision complex functions
88-
BUILD_COMPLEX16 - build the double-precision complex functions
89-
(all four types are included in the build by default when none was specifically selected)
83+
### Library related
9084

91-
BUILD_BFLOAT16 - build the "half precision brainfloat" real functions
85+
#### Library kind and bitness options
86+
87+
- `BINARY`: whether to build a 32-bit or 64-bit library (default is `64`, set
88+
to `32` on a 32-bit platform).
89+
- `INTERFACE64`: build with 64-bit (ILP64) integer representations to support
90+
large array index values (incompatible with the standard 32-bit integer (LP64) API).
91+
- `NO_STATIC`: if set to `1`, don't build a static library (default is `0`)
92+
- `NO_SHARED`: if set to `1`, don't build a shared library (default is `0`)
93+
94+
#### Data type options
95+
96+
- `BUILD_SINGLE`: build the single-precision real functions of BLAS and (if
97+
it's built) LAPACK
98+
- `BUILD_DOUBLE`: build the double-precision real functions
99+
- `BUILD_COMPLEX`: build the single-precision complex functions
100+
- `BUILD_COMPLEX16`: build the double-precision complex functions
101+
- `BUILD_BFLOAT16`: build the "half precision brainfloat" real functions
102+
- `EXPRECISION`: (do not use, this is a work in progress) option to use `long
103+
double` functions
104+
105+
By default, the single- and double-precision real and complex floating-point
106+
functions are included in the build, while the half- and extended-precision
107+
functions are not.
92108

93-
USE_THREAD - Use a multithreading backend (default to pthread)
94-
USE_LOCKING - implement locking for thread safety even when USE_THREAD is not set (so that the singlethreaded library can
95-
safely be called from multithreaded programs)
96-
USE_OPENMP - Use OpenMP as multithreading backend
97-
NUM_THREADS - define this to the maximum number of parallel threads you expect to need (defaults to the number of cores in the build cpu)
98-
NUM_PARALLEL - define this to the number of OpenMP instances that your code may use for parallel calls into OpenBLAS (default 1,see below)
99-
100-
```
101-
109+
#### Threading options
110+
111+
- `USE_THREAD`: Use a multithreading backend (defaults to `pthreads`).
112+
- `USE_LOCKING`: implement locking for thread safety even when `USE_THREAD` is
113+
not set (so that the single-threaded library can safely be called from
114+
multithreaded programs).
115+
- `USE_OPENMP`: Use OpenMP as multithreading backend
116+
- `NUM_THREADS`: define this to the maximum number of parallel threads you
117+
expect to need (defaults to the number of cores in the build CPU).
118+
- `NUM_PARALLEL`: define this to the number of OpenMP instances that your code
119+
may use for parallel calls into OpenBLAS (the default is `1`, see below).
102120

103121
OpenBLAS uses a fixed set of memory buffers internally, used for communicating
104122
and compiling partial results from individual threads. For efficiency, the
@@ -118,3 +136,32 @@ same time, then only one of them will be able to make progress while all the
118136
rest of them spin-wait for the one available buffer. Setting `NUM_PARALLEL` to
119137
the upper bound on the number of OpenMP runtimes that you can have in a process
120138
ensures that there are a sufficient number of buffer sets available.
139+
140+
#### Library and symbol name options
141+
142+
- `FIXED_LIBNAME`: if set to `1`, uses a non-versioned name for the library and
143+
no symbolic linking to variant names (default is `0`)
144+
- `LIBNAMEPREFIX`: prefix that, if given, will be inserted in the library name
145+
before `openblas` (e.g., `xxx` will result in `libxxxopenblas.so`)
146+
- `LIBNAMESUFFIX`: suffix that, if given, will be inserted in the library name
147+
after `openblas`, separated by an underscore (e.g., `yyy` will result in
148+
`libopenblas_yyy.so`)
149+
- `SYMBOLPREFIX`: prefix that, if given, will be added to all symbol names
150+
*and* to the library name
151+
- `SYMBOLSUFFIX`: suffix that, if given, will be added to all symbol names
152+
*and* to the library name
153+
154+
#### BLAS and LAPACK options
155+
156+
By default, the Fortran and C interfaces to BLAS and LAPACK are built,
157+
including deprecated functions, while
158+
[ReLAPACK](https://github.com/HPAC/ReLAPACK) is not.
159+
160+
- `NO_CBLAS`: if set to `1`, don't build the CBLAS interface (default is `0`)
161+
- `ONLY_CBLAS`: if set to `1`, only build the CBLAS interface (default is `0`)
162+
- `NO_LAPACK`: if set to `1`, don't build LAPACK (default is `0`)
163+
- `NO_LAPACKE`: if set to `1`, don't build the LAPACKE interface (default is `0`)
164+
- `BUILD_LAPACK_DEPRECATED`: if set to `0`, don't build deprecated LAPACK
165+
functions (default is `1`)
166+
- `BUILD_RELAPACK`: if set to `1`, build Recursive LAPACK on top of LAPACK
167+
(default is `0`)

‎docs/faq.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ Here is the result of the DGEMM subroutine's performance on Intel Core i5-2500K
9999

100100
### <a name="MSVC"></a>How can I call an OpenBLAS function in Microsoft Visual Studio?
101101

102-
Please read [this page](install.md#visual-studio).
102+
Please read [this page](install.md#visual-studio-native-windows-abi).
103103

104104
### <a name="C99_complex_number"></a>How can I use CBLAS and LAPACKE without C99 complex number support (e.g. in Visual Studio)?
105105

0 commit comments

Comments
 (0)