diff --git a/.github/workflows/codspeed-bench.yml b/.github/workflows/codspeed-bench.yml
index 04befefa9..25e196ef2 100644
--- a/.github/workflows/codspeed-bench.yml
+++ b/.github/workflows/codspeed-bench.yml
@@ -139,6 +139,13 @@ jobs:
cd build/openblas_wrap
python -c'import _flapack; print(dir(_flapack))'
+ - name: Run benchmarks under pytest-benchmark
+ run: |
+ cd benchmark/pybench
+ pip install pytest-benchmark
+ export PYTHONPATH=$PWD/build-install/lib/python${{matrix.pyver}}/site-packages/
+ OPENBLAS_NUM_THREADS=1 pytest benchmarks/bench_blas.py -k 'gesdd'
+
- name: Run benchmarks
uses: CodSpeedHQ/action@v2
with:
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 8f594cdd1..da40b853f 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,8 +1,13 @@
name: Publish docs via GitHub Pages
+
on:
push:
branches:
- develop
+ pull_request:
+ branches:
+ - develop
+
jobs:
build:
name: Deploy docs
@@ -10,12 +15,22 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
- uses: actions/setup-python@v5
with:
python-version: "3.10"
- - run: pip install mkdocs mkdocs-material
- # mkdocs gh-deploy command only builds to the top-level, hence building then deploying ourselves
- - run: mkdocs build
+
+ - name: Install MkDocs and doc theme packages
+ run: pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
+
+ - name: Build docs site
+ run: mkdocs build
+
+ # mkdocs gh-deploy command only builds to the top-level, hence deploying
+ # with this action instead.
+ # Deploys to http://www.openmathlib.org/OpenBLAS/docs/
- name: Deploy docs
uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
if: ${{ github.ref == 'refs/heads/develop' }}
diff --git a/azure-pipelines.yml b/azure-pipelines.yml
index 88696a7d2..d72baabe1 100644
--- a/azure-pipelines.yml
+++ b/azure-pipelines.yml
@@ -141,21 +141,21 @@ jobs:
- job: OSX_OpenMP
pool:
- vmImage: 'macOS-11'
+ vmImage: 'macOS-12'
steps:
- script: |
brew update
- make TARGET=CORE2 DYNAMIC_ARCH=1 USE_OPENMP=1 INTERFACE64=1 CC=gcc-10 FC=gfortran-10
- make TARGET=CORE2 DYNAMIC_ARCH=1 USE_OPENMP=1 INTERFACE64=1 CC=gcc-10 FC=gfortran-10 PREFIX=../blasinst install
+ make TARGET=CORE2 DYNAMIC_ARCH=1 USE_OPENMP=1 INTERFACE64=1 CC=gcc-13 FC=gfortran-13
+ make TARGET=CORE2 DYNAMIC_ARCH=1 USE_OPENMP=1 INTERFACE64=1 CC=gcc-13 FC=gfortran-13 PREFIX=../blasinst install
ls -lR ../blasinst
- job: OSX_GCC_Nothreads
pool:
- vmImage: 'macOS-11'
+ vmImage: 'macOS-12'
steps:
- script: |
brew update
- make USE_THREADS=0 CC=gcc-10 FC=gfortran-10
+ make USE_THREADS=0 CC=gcc-13 FC=gfortran-13
- job: OSX_GCC12
pool:
@@ -195,7 +195,7 @@ jobs:
- job: OSX_dynarch_cmake
pool:
- vmImage: 'macOS-11'
+ vmImage: 'macOS-12'
variables:
LD_LIBRARY_PATH: /usr/local/opt/llvm/lib
LIBRARY_PATH: /usr/local/opt/llvm/lib
@@ -203,7 +203,7 @@ jobs:
- script: |
mkdir build
cd build
- cmake -DTARGET=CORE2 -DDYNAMIC_ARCH=1 -DDYNAMIC_LIST='NEHALEM HASWELL SKYLAKEX' -DCMAKE_C_COMPILER=gcc-10 -DCMAKE_Fortran_COMPILER=gfortran-10 -DBUILD_SHARED_LIBS=ON ..
+ cmake -DTARGET=CORE2 -DDYNAMIC_ARCH=1 -DDYNAMIC_LIST='NEHALEM HASWELL SKYLAKEX' -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_Fortran_COMPILER=gfortran-13 -DBUILD_SHARED_LIBS=ON ..
cmake --build .
ctest
@@ -242,7 +242,7 @@ jobs:
- job: OSX_NDK_ARMV7
pool:
- vmImage: 'macOS-11'
+ vmImage: 'macOS-12'
steps:
- script: |
brew update
@@ -252,35 +252,35 @@ jobs:
- job: OSX_IOS_ARMV8
pool:
- vmImage: 'macOS-11'
+ vmImage: 'macOS-12'
variables:
- CC: /Applications/Xcode_12.4.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
- CFLAGS: -O2 -Wno-macro-redefined -isysroot /Applications/Xcode_12.4.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS14.4.sdk -arch arm64 -miphoneos-version-min=10.0
+ CC: /Applications/Xcode_14.2.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
+ CFLAGS: -O2 -Wno-macro-redefined -isysroot /Applications/Xcode_14.2.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS16.2.sdk -arch arm64 -miphoneos-version-min=10.0
steps:
- script: |
make TARGET=ARMV8 DYNAMIC_ARCH=1 NUM_THREADS=32 HOSTCC=clang NOFORTRAN=1
- job: OSX_IOS_ARMV7
pool:
- vmImage: 'macOS-11'
+ vmImage: 'macOS-12'
variables:
- CC: /Applications/Xcode_12.4.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
- CFLAGS: -O2 -mno-thumb -Wno-macro-redefined -isysroot /Applications/Xcode_12.4.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS14.4.sdk -arch armv7 -miphoneos-version-min=5.1
+ CC: /Applications/Xcode_14.2.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
+ CFLAGS: -O2 -mno-thumb -Wno-macro-redefined -isysroot /Applications/Xcode_14.2.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS16.2.sdk -arch armv7 -miphoneos-version-min=5.1
steps:
- script: |
make TARGET=ARMV7 DYNAMIC_ARCH=1 NUM_THREADS=32 HOSTCC=clang NOFORTRAN=1
- job: OSX_xbuild_DYNAMIC_ARM64
pool:
- vmImage: 'macOS-11'
+ vmImage: 'macOS-12'
variables:
- CC: /Applications/Xcode_12.5.1.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
- CFLAGS: -O2 -Wno-macro-redefined -isysroot /Applications/Xcode_12.5.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX11.3.sdk -arch arm64
+ CC: /Applications/Xcode_14.2.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
+ CFLAGS: -O2 -Wno-macro-redefined -isysroot /Applications/Xcode_14.2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX13.1.sdk -arch arm64
steps:
- script: |
- ls /Applications/Xcode_12.5.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs
- /Applications/Xcode_12.5.1.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang -arch arm64 --print-supported-cpus
- /Applications/Xcode_11.7.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang --version
+ ls /Applications/Xcode_14.2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs
+ /Applications/Xcode_12.2.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang -arch arm64 --print-supported-cpus
+ /Applications/Xcode_14.2.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang --version
make TARGET=ARMV8 DYNAMIC_ARCH=1 NUM_THREADS=32 HOSTCC=clang NOFORTRAN=1
- job: ALPINE_MUSL
diff --git a/benchmark/pybench/benchmarks/bench_blas.py b/benchmark/pybench/benchmarks/bench_blas.py
index 70ea03073..628c0cb2a 100644
--- a/benchmark/pybench/benchmarks/bench_blas.py
+++ b/benchmark/pybench/benchmarks/bench_blas.py
@@ -234,11 +234,14 @@ def test_gesdd(benchmark, mn, variant):
gesdd = ow.get_func('gesdd', variant)
u, s, vt, info = benchmark(run_gesdd, a, lwork, gesdd)
- assert info == 0
+ if variant != 's':
+ # On entry to SLASCL parameter number 4 had an illegal value
+ # under codspeed (cannot repro locally or on CI w/o codspeed)
+ # https://github.com/OpenMathLib/OpenBLAS/issues/4776
+ assert info == 0
- atol = {'s': 1e-5, 'd': 1e-13}
-
- np.testing.assert_allclose(u @ np.diag(s) @ vt, a, atol=atol[variant])
+ atol = {'s': 1e-5, 'd': 1e-13}
+ np.testing.assert_allclose(u @ np.diag(s) @ vt, a, atol=atol[variant])
# linalg.eigh
diff --git a/cmake/prebuild.cmake b/cmake/prebuild.cmake
index 6d98ed32e..e64352f4a 100644
--- a/cmake/prebuild.cmake
+++ b/cmake/prebuild.cmake
@@ -1309,6 +1309,15 @@ endif ()
"#define DTB_DEFAULT_ENTRIES 128\n"
"#define DTB_SIZE 4096\n"
"#define L2_ASSOCIATIVE 8\n")
+ elseif ("${TCORE}" STREQUAL "RISCV64_GENERIC")
+ file(APPEND ${TARGET_CONF_TEMP}
+ "#define L1_DATA_SIZE 32768\n"
+ "#define L1_DATA_LINESIZE 32\n"
+ "#define L2_SIZE 1048576\n"
+ "#define L2_LINESIZE 32 \n"
+ "#define DTB_DEFAULT_ENTRIES 128\n"
+ "#define DTB_SIZE 4096\n"
+ "#define L2_ASSOCIATIVE 4\n")
endif()
set(SBGEMM_UNROLL_M 8)
set(SBGEMM_UNROLL_N 4)
diff --git a/cmake/system.cmake b/cmake/system.cmake
index 479f50538..e4778249f 100644
--- a/cmake/system.cmake
+++ b/cmake/system.cmake
@@ -615,7 +615,7 @@ if (${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
endif ()
if (CMAKE_Fortran_COMPILER)
-if (${F_COMPILER} STREQUAL "NAG" OR ${F_COMPILER} STREQUAL "CRAY" OR CMAKE_Fortran_COMPILER_ID MATCHES "LLVMFlang.*")
+if ("${F_COMPILER}" STREQUAL "NAG" OR "${F_COMPILER}" STREQUAL "CRAY" OR CMAKE_Fortran_COMPILER_ID MATCHES "LLVMFlang.*")
set(FILTER_FLAGS "-msse3;-mssse3;-msse4.1;-mavx;-mavx2,-mskylake-avx512")
if (CMAKE_Fortran_COMPILER_ID MATCHES "LLVMFlang.*")
message(STATUS "removing fortran flags")
diff --git a/common_x86_64.h b/common_x86_64.h
index dda168d6c..21cd198f3 100644
--- a/common_x86_64.h
+++ b/common_x86_64.h
@@ -253,7 +253,7 @@ static __inline unsigned int blas_quickdivide(unsigned int x, unsigned int y){
#ifndef BUFFERSIZE
#define BUFFER_SIZE (32 << 22)
#else
-#define BUFFER_SIZE (32 << BUFFERSIZE)
+#define BUFFER_SIZE (32UL << BUFFERSIZE)
#endif
#define SEEK_ADDRESS
diff --git a/cpuid_x86.c b/cpuid_x86.c
index e157232cf..f77cca1d8 100644
--- a/cpuid_x86.c
+++ b/cpuid_x86.c
@@ -1529,6 +1529,7 @@ int get_cpuname(void){
switch (model) {
case 5: // Comet Lake H and S
case 6: // Comet Lake U
+ case 10: // Meteor Lake
if(support_avx2())
return CPUTYPE_HASWELL;
if(support_avx())
@@ -2391,10 +2392,10 @@ int get_coretype(void){
else
return CORE_NEHALEM;
}
- case 15:
- if (model <= 0x2) return CORE_NORTHWOOD;
- else return CORE_PRESCOTT;
}
+ case 15:
+ if (model <= 0x2) return CORE_NORTHWOOD;
+ else return CORE_PRESCOTT;
}
}
diff --git a/docs/about.md b/docs/about.md
index 95acdccc8..dea1adab1 100644
--- a/docs/about.md
+++ b/docs/about.md
@@ -2,25 +2,45 @@
We have a [GitHub discussions](https://github.com/OpenMathLib/OpenBLAS/discussions/) forum to discuss usage and development of OpenBLAS. We also have a [Google group for *users*](https://groups.google.com/forum/#!forum/openblas-users) and a [Google group for *development of*](https://groups.google.com/forum/#!forum/openblas-dev) OpenBLAS.
-## Donations
-
-You can read OpenBLAS statement of receipts and disbursement and cash balance on [google doc](https://docs.google.com/spreadsheet/ccc?key=0AghkTjXe2lDndE1UZml0dGpaUzJmZGhvenBZd1F2R1E&usp=sharing). A backer list is available [on GitHub](https://github.com/OpenMathLib/OpenBLAS/blob/develop/BACKERS.md).
-
-We welcome the hardware donation, including the latest CPU and boards.
-
## Acknowledgements
-This work is partially supported by
+This work was or is partially supported by the following grants, contracts and institutions:
+
* Research and Development of Compiler System and Toolchain for Domestic CPU, National S&T Major Projects: Core Electronic Devices, High-end General Chips and Fundamental Software (No.2009ZX01036-001-002)
* National High-tech R&D Program of China (Grant No.2012AA010903)
+* [PerfXLab](http://www.perfxlab.com/)
+* Chan Zuckerberg Initiative's Essential Open Source Software for Science program:
+ * Cycle 1 grant: [Strengthening NumPy's foundations - growing beyond code](https://figshare.com/articles/journal_contribution/Proposal_NumPy_OpenBLAS_for_Chan_Zuckerberg_Initiative_EOSS_2019_round_1/10302167) (2019-2020)
+ * Cycle 3 grant: [Improving usability and sustainability for NumPy and OpenBLAS](https://chanzuckerberg.com/eoss/proposals/improving-usability-and-sustainability-for-numpy-and-openblas/) (2020-2021)
+* Sovereign Tech Fund funding: [Keeping high performance linear algebra computation accessible and open for all](https://www.sovereigntechfund.de/tech/openblas) (2023-2024)
-## Users of OpenBLAS
+Over the course of OpenBLAS development, a number of donations were received.
+You can read OpenBLAS's statement of receipts and disbursement and cash balance in
+[this Google doc](https://docs.google.com/spreadsheet/ccc?key=0AghkTjXe2lDndE1UZml0dGpaUzJmZGhvenBZd1F2R1E&usp=sharing) (covers 2013-2016).
+A list of backers is available [in BACKERS.md](https://github.com/OpenMathLib/OpenBLAS/blob/develop/BACKERS.md) in the main repo.
-* Julia - a high-level, high-performance dynamic programming language for technical computing
-* Ceemple v1.0.3 (C++ technical computing environment), including OpenBLAS, Qt, Boost, OpenCV and others. The only solution with immediate-recompilation of C++ code. Available from Ceemple C++ Technical Computing.
-* [netlib-java](https://github.com/fommil/netlib-java) and various upstream libraries, allowing OpenBLAS to be used from languages on the Java Virtual Machine.
+### Donations
+
+We welcome hardware donations, including the latest CPUs and motherboards.
+
+
+## Open source users of OpenBLAS
+
+Prominent open source users of OpenBLAS include:
+
+* [Julia](https://julialang.org) - a high-level, high-performance dynamic programming language for technical computing
+* [NumPy](https://numpy.org) - the fundamental package for scientific computing with Python
+* [SciPy](https://scipy.org) - fundamental algorithms for scientific computing in Python
+* [R](https://www.r-project.org/) - a free software environment for statistical computing and graphics
+* [OpenCV](https://opencv.org/) - the world's biggest computer vision library
+
+OpenBLAS is packaged in most major Linux distros, as well as general and
+numerical computing-focused packaging ecosystems like Nix, Homebrew, Spack and
+conda-forge.
+
+OpenBLAS is used directly by libraries written in C, C++ and Fortran (and
+probably other languages), and directly by end users in those languages.
-
## Publications
diff --git a/docs/build_system.md b/docs/build_system.md
index 98808fdfa..3de220580 100644
--- a/docs/build_system.md
+++ b/docs/build_system.md
@@ -1,3 +1,8 @@
+This page describes the Make-based build, which is the default/authoritative
+build method. Note that the OpenBLAS repository also supports building with
+CMake (not described here) - that generally works and is tested, however there
+may be small differences between the Make and CMake builds.
+
!!! warning
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.
@@ -95,10 +100,21 @@ NUM_PARALLEL - define this to the number of OpenMP instances that your code m
```
-OpenBLAS uses a fixed set of memory buffers internally, used for communicating and compiling partial results from individual threads.
-For efficiency, the management array structure for these buffers is sized at build time - this makes it necessary to know in advance how
-many threads need to be supported on the target system(s).
-With OpenMP, there is an additional level of complexity as there may be calls originating from a parallel region in the calling program. If OpenBLAS gets called from a single parallel region, it runs single-threaded automatically to avoid overloading the system by fanning out its own set of threads.
-In the case that an OpenMP program makes multiple calls from independent regions or instances in parallel, this default serialization is not
-sufficient as the additional caller(s) would compete for the original set of buffers already in use by the first call.
-So if multiple OpenMP runtimes call into OpenBLAS at the same time, then only one of them will be able to make progress while all the rest of them spin-wait for the one available buffer. Setting NUM_PARALLEL to the upper bound on the number of OpenMP runtimes that you can have in a process ensures that there are a sufficient number of buffer sets available
\ No newline at end of file
+OpenBLAS uses a fixed set of memory buffers internally, used for communicating
+and compiling partial results from individual threads. For efficiency, the
+management array structure for these buffers is sized at build time - this
+makes it necessary to know in advance how many threads need to be supported on
+the target system(s).
+
+With OpenMP, there is an additional level of complexity as there may be calls
+originating from a parallel region in the calling program. If OpenBLAS gets
+called from a single parallel region, it runs single-threaded automatically to
+avoid overloading the system by fanning out its own set of threads. In the case
+that an OpenMP program makes multiple calls from independent regions or
+instances in parallel, this default serialization is not sufficient as the
+additional caller(s) would compete for the original set of buffers already in
+use by the first call. So if multiple OpenMP runtimes call into OpenBLAS at the
+same time, then only one of them will be able to make progress while all the
+rest of them spin-wait for the one available buffer. Setting `NUM_PARALLEL` to
+the upper bound on the number of OpenMP runtimes that you can have in a process
+ensures that there are a sufficient number of buffer sets available.
diff --git a/docs/developers.md b/docs/developers.md
index 08443b7e4..b2c62eeb6 100644
--- a/docs/developers.md
+++ b/docs/developers.md
@@ -1,6 +1,6 @@
# Developer manual
-## Source codes Layout
+## Source code layout
```
OpenBLAS/
@@ -51,8 +51,7 @@ OpenBLAS/
```
-A call tree for `dgemm` is as following.
-
+A call tree for `dgemm` looks as follows:
```
interface/gemm.c
│
@@ -61,10 +60,9 @@ driver/level3/level3.c
gemm assembly kernels at kernel/
```
-To find the kernel currently used for a particular supported cpu, please check the corresponding `kernel/$(ARCH)/KERNEL.$(CPU)` file.
-
-Here is an example for `kernel/x86_64/KERNEL.HASWELL`
+To find the kernel currently used for a particular supported CPU, please check the corresponding `kernel/$(ARCH)/KERNEL.$(CPU)` file.
+Here is an example for `kernel/x86_64/KERNEL.HASWELL`:
```
...
DTRMMKERNEL = dtrmm_kernel_4x8_haswell.c
@@ -73,71 +71,122 @@ DGEMMKERNEL = dgemm_kernel_4x8_haswell.S
```
According to the above `KERNEL.HASWELL`, OpenBLAS Haswell dgemm kernel file is `dgemm_kernel_4x8_haswell.S`.
+
## Optimizing GEMM for a given hardware
-Read the Goto paper to understand the algorithm.
+!!! abstract "Read the Goto paper to understand the algorithm"
-Goto, Kazushige; van de Geijn, Robert A. (2008). ["Anatomy of High-Performance Matrix Multiplication"](http://delivery.acm.org/10.1145/1360000/1356053/a12-goto.pdf?ip=155.68.162.54&id=1356053&acc=ACTIVE%20SERVICE&key=A79D83B43E50B5B8%2EF070BBE7E45C3F17%2E4D4702B0C3E38B35%2E4D4702B0C3E38B35&__acm__=1517932837_edfe766f1e295d9a7830812371e1d173). ACM Transactions on Mathematical Software 34 (3): Article 12
-(The above link is available only to ACM members, but this and many related papers is also available on the pages
-of van de Geijn's FLAME project, http://www.cs.utexas.edu/~flame/web/FLAMEPublications.html )
+ Goto, Kazushige; van de Geijn, Robert A. (2008).
+ ["Anatomy of High-Performance Matrix Multiplication"](http://delivery.acm.org/10.1145/1360000/1356053/a12-goto.pdf?ip=155.68.162.54&id=1356053&acc=ACTIVE%20SERVICE&key=A79D83B43E50B5B8%2EF070BBE7E45C3F17%2E4D4702B0C3E38B35%2E4D4702B0C3E38B35&__acm__=1517932837_edfe766f1e295d9a7830812371e1d173).
+ ACM Transactions on Mathematical Software 34 (3): Article 12
-The `driver/level3/level3.c` is the implementation of Goto's algorithm. Meanwhile, you can look at `kernel/generic/gemmkernel_2x2.c`, which is a naive `2x2` register blocking gemm kernel in C.
+ (The above link is available only to ACM members, but this and many related
+ papers is also available on [the pages of van de Geijn's FLAME project](http://www.cs.utexas.edu/~flame/web/FLAMEPublications.html))
-Then,
-* Write optimized assembly kernels. consider instruction pipeline, available registers, memory/cache accessing
-* Tuning cache block size, `Mc`, `Kc`, and `Nc`
+The `driver/level3/level3.c` is the implementation of Goto's algorithm.
+Meanwhile, you can look at `kernel/generic/gemmkernel_2x2.c`, which is a naive
+`2x2` register blocking `gemm` kernel in C. Then:
-Note that not all of the cpu-specific parameters in param.h are actively used in algorithms. DNUMOPT only appears as a scale factor in profiling output of the level3 syrk interface code, while its counterpart SNUMOPT (aliased as NUMOPT in common.h) is not used anywhere at all.
-SYMV_P is only used in the generic kernels for the symv and chemv/zhemv functions - at least some of those are usually overridden by cpu-specific implementations, so if you start by cloning the existing implementation for a related cpu you need to check its KERNEL file to see if tuning SYMV_P would have any effect at all.
-GEMV_UNROLL is only used by some older x86_64 kernels, so not all sections in param.h define it.
-Similarly, not all of the cpu parameters like L2 or L3 cache sizes are necessarily used in current kernels for a given model - by all indications the cpu identification code was imported from some other project originally.
+* Write optimized assembly kernels. Consider instruction pipeline, available registers, memory/cache access.
+* Tune cache block sizes (`Mc`, `Kc`, and `Nc`)
-## Run OpenBLAS Test
+Note that not all of the CPU-specific parameters in `param.h` are actively used in algorithms.
+`DNUMOPT` only appears as a scale factor in profiling output of the level3 `syrk` interface code,
+while its counterpart `SNUMOPT` (aliased as `NUMOPT` in `common.h`) is not used anywhere at all.
-We use netlib blas test, cblas test, and LAPACK test. Meanwhile, we use [BLAS-Tester](https://github.com/xianyi/BLAS-Tester), a modified test tool from ATLAS.
+`SYMV_P` is only used in the generic kernels for the `symv` and `chemv`/`zhemv` functions -
+at least some of those are usually overridden by CPU-specific implementations, so if you start
+by cloning the existing implementation for a related CPU you need to check its `KERNEL` file
+to see if tuning `SYMV_P` would have any effect at all.
-* Run `test` and `ctest` at OpenBLAS. e.g. `make test` or `make ctest`.
-* Run regression test `utest` at OpenBLAS.
-* Run LAPACK test. e.g. `make lapack-test`.
-* Clone [BLAS-Tester](https://github.com/xianyi/BLAS-Tester), which can compare the OpenBLAS result with netlib reference BLAS.
+`GEMV_UNROLL` is only used by some older x86-64 kernels, so not all sections in `param.h` define it.
+Similarly, not all of the CPU parameters like L2 or L3 cache sizes are necessarily used in current
+kernels for a given model - by all indications the CPU identification code was imported from some
+other project originally.
+
+
+## Running OpenBLAS tests
+
+We use tests for Netlib BLAS, CBLAS, and LAPACK. In addition, we use
+OpenBLAS-specific regression tests. They can be run with Make:
+
+* `make -C test` for BLAS tests
+* `make -C ctest` for CBLAS tests
+* `make -C utest` for OpenBLAS regression tests
+* `make lapack-test` for LAPACK tests
+
+We also use the [BLAS-Tester](https://github.com/xianyi/BLAS-Tester) tests for regression testing.
+It is basically the ATLAS test suite adapted for building with OpenBLAS.
+
+The project makes use of several Continuous Integration (CI) services
+conveniently interfaced with GitHub to automatically run tests on a number of
+platforms and build configurations.
+
+Also note that the test suites included with "numerically heavy" projects like
+Julia, NumPy, SciPy, Octave or QuantumEspresso can be used for regression
+testing, when those projects are built such that they use OpenBLAS.
-The project makes use of several Continuous Integration (CI) services conveniently interfaced with github to automatically check compilability on a number of platforms.
-Lastly, the testsuites included with "numerically heavy" projects like Julia, NumPy, Octave or QuantumEspresso can be used for regression testing.
## Benchmarking
-Several simple C benchmarks for performance testing individual BLAS functions are available in the `benchmark` folder, and its `scripts` subdirectory contains corresponding versions for Python, Octave and R.
-Other options include
+A number of benchmarking methods are used by OpenBLAS:
-* https://github.com/RoyiAvital/MatlabJuliaMatrixOperationsBenchmark (various matrix operations in Julia and Matlab)
-* https://github.com/mmperf/mmperf/ (single-core matrix multiplication)
+- Several simple C benchmarks for performance testing individual BLAS functions
+ are available in the `benchmark` folder. They can be run locally through the
+ `Makefile` in that directory. And the `benchmark/scripts` subdirectory
+ contains similar benchmarks that use OpenBLAS via NumPy, SciPy, Octave and R.
+- On pull requests, a representative set of functions is tested for performance
+ regressions with Codspeed; results can be viewed at
+ [https://codspeed.io/OpenMathLib/OpenBLAS](https://codspeed.io/OpenMathLib/OpenBLAS).
+- The [OpenMathLib/BLAS-Benchmarks](https://github.com/OpenMathLib/BLAS-Benchmarks) repository
+ contains an [Airspeed Velocity](https://github.com/airspeed-velocity/asv/)-based benchmark
+ suite which is run on several CPU architectures in cron jobs. Results are published
+ to a dashboard: [http://www.openmathlib.org/BLAS-Benchmarks/](http://www.openmathlib.org/BLAS-Benchmarks/).
-## Adding autodetection support for a new revision or variant of a supported cpu
+Benchmarking code for BLAS libraries, and specific performance analysis results, can be found
+in a number of places. For example:
-Especially relevant for x86_64, a new cpu model may be a "refresh" (die shrink and/or different number of cores) within an existing
-model family without significant changes to its instruction set. (e.g. Intel Skylake, Kaby Lake etc. still are fundamentally Haswell,
-low end Goldmont etc. are Nehalem). In this case, compilation with the appropriate older TARGET will already lead to a satisfactory build.
+* [MatlabJuliaMatrixOperationsBenchmark](https://github.com/RoyiAvital/MatlabJuliaMatrixOperationsBenchmark)
+ (various matrix operations in Julia and Matlab)
+* [mmperf/mmperf](https://github.com/mmperf/mmperf/) (single-core matrix multiplication)
+
+
+## Adding autodetection support for a new revision or variant of a supported CPU
+
+Especially relevant for x86-64, a new CPU model may be a "refresh" (die shrink and/or different number of cores) within an existing
+model family without significant changes to its instruction set (e.g., Intel Skylake and Kaby Lake still are fundamentally the same architecture as Haswell,
+low end Goldmont etc. are Nehalem). In this case, compilation with the appropriate older `TARGET` will already lead to a satisfactory build.
To achieve autodetection of the new model, its CPUID (or an equivalent identifier) needs to be added in the `cpuid_.c`
-relevant for its general architecture, with the returned name for the new type set appropriately. For x86 which has the most complex
-cpuid file, there are two functions that need to be edited - get_cpuname() to return e.g. CPUTYPE_HASWELL and get_corename() for the (broader)
-core family returning e.g. CORE_HASWELL. (This information ends up in the Makefile.conf and config.h files generated by `getarch`. Failure to
-set either will typically lead to a missing definition of the GEMM_UNROLL parameters later in the build, as `getarch_2nd` will be unable to
-find a matching parameter section in param.h.)
+relevant for its general architecture, with the returned name for the new type set appropriately. For x86, which has the most complex
+`cpuid` file, there are two functions that need to be edited: `get_cpuname()` to return, e.g., `CPUTYPE_HASWELL` and `get_corename()` for the (broader)
+core family returning, e.g., `CORE_HASWELL`.[^1]
-For architectures where "DYNAMIC_ARCH" builds are supported, a similar but simpler code section for the corresponding runtime detection of the cpu exists in `driver/others/dynamic.c` (for x86) and `driver/others/dynamic_.c` for other architectures.
+[^1]:
+ This information ends up in the `Makefile.conf` and `config.h` files generated by `getarch`. Failure to
+ set either will typically lead to a missing definition of the `GEMM_UNROLL` parameters later in the build,
+ as `getarch_2nd` will be unable to find a matching parameter section in `param.h`.
+
+For architectures where `DYNAMIC_ARCH` builds are supported, a similar but simpler code section for the corresponding
+runtime detection of the CPU exists in `driver/others/dynamic.c` (for x86), and `driver/others/dynamic_.c` for other architectures.
Note that for x86 the CPUID is compared after splitting it into its family, extended family, model and extended model parts, so the single decimal
-number returned by Linux in /proc/cpuinfo for the model has to be converted back to hexadecimal before splitting into its constituent
-digits, e.g. 142 = 8E , translates to extended model 8, model 14.
+number returned by Linux in `/proc/cpuinfo` for the model has to be converted back to hexadecimal before splitting into its constituent
+digits. For example, `142 == 8E` translates to extended model 8, model 14.
-## Adding dedicated support for a new cpu model
-Usually it will be possible to start from an existing model, clone its KERNEL configuration file to the new name to use for this TARGET and eventually replace individual kernels with versions better suited for peculiarities of the new cpu model. In addition, it is necessary to add
-(or clone at first) the corresponding section of GEMM_UNROLL parameters in the toplevel param.h, and possibly to add definitions such as USE_TRMM
-(governing whether TRMM functions use the respective GEMM kernel or a separate source file) to the Makefiles (and CMakeLists.txt) in the kernel
-directory. The new cpu name needs to be added to TargetLists.txt and the cpu autodetection code used by the `getarch` helper program - contained in
+## Adding dedicated support for a new CPU model
+
+Usually it will be possible to start from an existing model, clone its `KERNEL` configuration file to the new name to use for this
+`TARGET` and eventually replace individual kernels with versions better suited for peculiarities of the new CPU model.
+In addition, it is necessary to add (or clone at first) the corresponding section of `GEMM_UNROLL` parameters in the top-level `param.h`,
+and possibly to add definitions such as `USE_TRMM` (governing whether `TRMM` functions use the respective `GEMM` kernel or a separate source file)
+to the `Makefile`s (and `CMakeLists.txt`) in the kernel directory. The new CPU name needs to be added to `TargetList.txt`,
+and the CPU auto-detection code used by the `getarch` helper program - contained in
the `cpuid_.c` file amended to include the CPUID (or equivalent) information processing required (see preceding section).
+
## Adding support for an entirely new architecture
-This endeavour is best started by cloning the entire support structure for 32bit ARM, and within that the ARMV5 cpu in particular as this is implemented through plain C kernels only. An example providing a convenient "shopping list" can be seen in pull request #1526.
+This endeavour is best started by cloning the entire support structure for 32-bit ARM, and within that the ARMv5 CPU in particular,
+as this is implemented through plain C kernels only. An example providing a convenient "shopping list" can be seen in pull request
+[#1526](https://github.com/OpenMathLib/OpenBLAS/pull/1526).
diff --git a/docs/distributing.md b/docs/distributing.md
index ff481b048..98b390a9f 100644
--- a/docs/distributing.md
+++ b/docs/distributing.md
@@ -49,7 +49,7 @@ settings):
to provide an ILP64 interface build as well, use a symbol suffix to avoid
symbol name clashes (see the next section).
-[^1] All major distributions do include LAPACK as of mid 2023 as far as we
+[^1]: All major distributions do include LAPACK as of mid 2023 as far as we
know. Older versions of Arch Linux did not, and that was known to cause
problems.
diff --git a/docs/extensions.md b/docs/extensions.md
index 3502f6487..483b00928 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -1,4 +1,9 @@
-* BLAS-like extensions
+OpenBLAS for the most part contains implementations of the reference (Netlib)
+BLAS, CBLAS, LAPACK and LAPACKE interfaces. A few OpenBLAS-specific functions
+are also provided however, which mostly can be seen as "BLAS extensions".
+This page documents those non-standard APIs.
+
+## BLAS-like extensions
| Routine | Data Types | Description |
| ------------- |:------------- | :---------------|
@@ -9,20 +14,26 @@
| ?geadd | s,d,c,z | matrix add |
| ?gemmt | s,d,c,z | gemm but only a triangular part updated|
-* BLAS-like and Conversion functions for bfloat16 (available when OpenBLAS was compiled with BUILD_BFLOAT16=1)
- * `void cblas_sbstobf16` converts a float array to an array of bfloat16 values by rounding
- * `void cblas_sbdtobf16` converts a double array to an array of bfloat16 values by rounding
- * `void cblas_sbf16tos` converts a bfloat16 array to an array of floats
- * `void cblas_dbf16tod` converts a bfloat16 array to an array of doubles
- * `float cblas_sbdot` computes the dot product of two bfloat16 arrays
- * `void cblas_sbgemv` performs the matrix-vector operations of GEMV with the input matrix and X vector as bfloat16
- * `void cblas_sbgemm` performs the matrix-matrix operations of GEMM with both input arrays containing bfloat16
-* Utility functions
- * openblas_get_num_threads
- * openblas_set_num_threads
- * `int openblas_get_num_procs(void)` returns the number of processors available on the system (may include "hyperthreading cores")
- * `int openblas_get_parallel(void)` returns 0 for sequential use, 1 for platform-based threading and 2 for OpenMP-based threading
- * `char * openblas_get_config()` returns the options OpenBLAS was built with, something like `NO_LAPACKE DYNAMIC_ARCH NO_AFFINITY Haswell`
- * `int openblas_set_affinity(int thread_index, size_t cpusetsize, cpu_set_t *cpuset)` sets the cpu affinity mask of the given thread to the provided cpuset. (Only available under Linux, with semantics identical to pthread_setaffinity_np)
+## bfloat16 functionality
+
+BLAS-like and conversion functions for `bfloat16` (available when OpenBLAS was compiled with `BUILD_BFLOAT16=1`):
+
+* `void cblas_sbstobf16` converts a float array to an array of bfloat16 values by rounding
+* `void cblas_sbdtobf16` converts a double array to an array of bfloat16 values by rounding
+* `void cblas_sbf16tos` converts a bfloat16 array to an array of floats
+* `void cblas_dbf16tod` converts a bfloat16 array to an array of doubles
+* `float cblas_sbdot` computes the dot product of two bfloat16 arrays
+* `void cblas_sbgemv` performs the matrix-vector operations of GEMV with the input matrix and X vector as bfloat16
+* `void cblas_sbgemm` performs the matrix-matrix operations of GEMM with both input arrays containing bfloat16
+
+## Utility functions
+
+* `openblas_get_num_threads`
+* `openblas_set_num_threads`
+* `int openblas_get_num_procs(void)` returns the number of processors available on the system (may include "hyperthreading cores")
+* `int openblas_get_parallel(void)` returns 0 for sequential use, 1 for platform-based threading and 2 for OpenMP-based threading
+* `char * openblas_get_config()` returns the options OpenBLAS was built with, something like `NO_LAPACKE DYNAMIC_ARCH NO_AFFINITY Haswell`
+* `int openblas_set_affinity(int thread_index, size_t cpusetsize, cpu_set_t *cpuset)` sets the CPU affinity mask of the given thread
+ to the provided cpuset. Only available on Linux, with semantics identical to `pthread_setaffinity_np`.
diff --git a/docs/install.md b/docs/install.md
index dff18e150..1b04165c7 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,677 +1,749 @@
# Install OpenBLAS
+OpenBLAS can be installed through package managers or from source. If you only
+want to use OpenBLAS rather than make changes to it, we recommend installing a
+pre-built binary package with your package manager of choice.
+
+This page contains an overview of installing with package managers as well as
+from source. For the latter, see [further down on this page](#building-from-source).
+
+
+## Installing with a package manager
+
!!! note
- Lists of precompiled packages are not comprehensive, is not meant to validate nor endorse a particular third-party build over others, and may not always lead to the newest version
+ Almost every package manager provides OpenBLAS packages; the list on this
+ page is not comprehensive. If your package manager of choice isn't shown
+ here, please search its package database for `openblas` or `libopenblas`.
-## Quick install
-
-Precompiled packages have recently become available for a number of platforms through their normal installation procedures, so for users of desktop devices at least, the instructions below are mostly relevant when you want to try the most recent development snapshot from git. See your platform's relevant "Precompiled packages" section.
-
-The [Conda-Forge](https://github.com/conda-forge) project maintains packages for the conda package manager at .
-
-## Source
-Download the latest [stable version](https://github.com/xianyi/OpenBLAS/releases) from release page.
-
-## Platforms
-
### Linux
-Just type `make` to compile the library.
+On Linux, OpenBLAS can be installed with the system package manager, or with a
+package manager like [Conda](https://docs.conda.io/en/latest/)
+(or alternative package managers for the conda-forge ecosystem, like
+[Mamba](https://mamba.readthedocs.io/en/latest/),
+[Micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html),
+or [Pixi](https://pixi.sh/latest/#windows-installer)),
+[Spack](https://spack.io/), or [Nix](https://nixos.org/). For the latter set of
+tools, the package name in all cases is `openblas`. Since package management in
+quite a few of these tools is declarative (i.e., managed by adding `openblas`
+to a metadata file describing the dependencies for your project or
+environment), we won't attempt to give detailed instructions for these tools here.
-Notes:
+Linux distributions typically split OpenBLAS up in two packages: one containing
+the library itself (typically named `openblas` or `libopenblas`), and one containing headers,
+pkg-config and CMake files (typically named the same as the package for the
+library with `-dev` or `-devel` appended; e.g., `openblas-devel`). Please keep
+in mind that if you want to install OpenBLAS in order to use it directly in
+your own project, you will need to install both of those packages.
-* OpenBLAS doesn't support g77. Please use gfortran or other Fortran compilers. e.g. `make FC=gfortran`.
-* When building in an emulator (KVM,QEMU etc.) make sure that the combination of CPU features exposed to
- the virtual environment matches that of an existing CPU to allow detection of the cpu model to succeed.
- (With qemu, this can be done by passing `-cpu host` or a supported model name at invocation)
+Distro-specific installation commands:
+=== "Debian/Ubuntu/Mint/Kali"
-#### Precompiled packages
+ ```bash
+ $ sudo apt update
+ $ sudo apt install libopenblas-dev
+ ```
+ OpenBLAS can be configured as the default BLAS through the `update-alternatives` mechanism:
-##### Debian/Ubuntu/Mint/Kali
- OpenBLAS package is available in default repositories and can act as default BLAS in system
+ ```bash
+ $ sudo update-alternatives --config libblas.so.3
+ ```
-Example installation commands:
-```bash
-$ sudo apt update
-$ apt search openblas
-$ sudo apt install libopenblas-dev
-$ sudo update-alternatives --config libblas.so.3
-```
- Alternatively, if distributor's package proves unsatisfactory, you may try latest version of OpenBLAS, [Following guide in OpenBLAS FAQ](faq.md#debianlts)
-
-##### openSuSE/SLE
- Recent OpenSUSE versions include OpenBLAS in default repositories and also permit OpenBLAS to act as replacement of system-wide BLAS.
+=== "openSUSE/SLE"
- Example installation commands:
-```bash
-$ sudo zypper ref
-$ zypper se openblas
-$ sudo zypper in openblas-devel
-$ sudo update-alternatives --config libblas.so.3
-```
-Should you be using older OpenSUSE or SLE that provides no OpenBLAS, you can attach optional or experimental openSUSE repository as a new package source to acquire recent build of OpenBLAS following [instructions on openSUSE software site](https://software.opensuse.org/package/openblas)
+ ```bash
+ $ sudo zypper refresh
+ $ sudo zypper install openblas-devel
+ ```
-##### Fedora/CentOS/RHEL
-Fedora provides OpenBLAS in default installation repositories.
+ OpenBLAS can be configured as the default BLAS through the `update-alternatives` mechanism:
+ ```bash
+ $ sudo update-alternatives --config libblas.so.3
+ ```
-To install it try following:
-```bash
-$ dnf search openblas
-$ dnf install openblas-devel
-```
-For CentOS/RHEL/Scientific Linux packages are provided via [Fedora EPEL repository](https://fedoraproject.org/wiki/EPEL)
+=== "Fedora/CentOS/RHEL"
-After adding repository and repository keys installation is pretty straightforward:
-```bash
-$ yum search openblas
-$ yum install openblas-devel
-```
-No alternatives mechanism is provided for BLAS, and packages in system repositories are linked against NetLib BLAS or ATLAS BLAS libraries. You may wish to re-package RPMs to use OpenBLAS instead [as described here](https://fedoraproject.org/wiki/How_to_create_an_RPM_package)
+ ```bash
+ $ dnf check-update
+ $ dnf install openblas-devel
+ ```
-##### Mageia
-Mageia offers ATLAS and NetLIB LAPACK in base repositories.
-You can build your own OpenBLAS replacement, and once installed in /opt
-TODO: populate /usr/lib64 /usr/include accurately to replicate netlib with update-alternatives
+ !!! warning
+
+ Fedora does not ship the pkg-config files for OpenBLAS. Instead, it wants you to
+ link against [FlexiBLAS](https://www.mpi-magdeburg.mpg.de/projects/flexiblas) (which
+ uses OpenBLAS by default as its backend on Fedora), which you can install with:
+
+ ```bash
+ $ dnf install flexiblas-devel
+ ```
+
+ For CentOS and RHEL, OpenBLAS packages are provided via the [Fedora EPEL repository](https://fedoraproject.org/wiki/EPEL).
+ After adding that repository and its repository keys, you can install
+ `openblas-devel` with either `dnf` or `yum`.
+
+=== "Arch/Manjaro/Antergos"
+
+ ```bash
+ $ sudo pacman -S openblas
+ ```
-##### Arch/Manjaro/Antergos
-```bash
-$ sudo pacman -S openblas
-```
### Windows
-The precompiled binaries available with each release (in ) are
-created with MinGW using an option list of
-"NUM_THREADS=64 TARGET=GENERIC DYNAMIC_ARCH=1 DYNAMIC_OLDER=1 CONSISTENT_FPCSR=1" - they should work on
-any x86 or x86_64 computer. The zip archive contains the include files, static and dll libraries as well
-as configuration files for getting them found via CMAKE or pkgconfig - just create a suitable folder for
-your OpenBLAS installation and unzip it there. (Note that you will need to edit the provided openblas.pc
-and OpenBLASConfig.cmake to reflect the installation path on your computer, as distributed they have "win"
-or "win64" reflecting the local paths on the system they were built on). Some programs will expect the DLL
-name to be lapack.dll, blas.dll, or (in the case of the statistics package "R") even Rblas.dll to act as a
-direct replacement for whatever other implementation of BLAS and LAPACK they use by default. Just copy the
-openblas.dll to the desired name(s).
-Note that the provided binaries are built with INTERFACE64=0, meaning they use standard 32bit integers for
-array indexing and the like (as is the default for most if not all BLAS and LAPACK implementations). If the
-documentation of whatever program you are using with OpenBLAS mentions 64bit integers (INTERFACE64=1) for
-addressing huge matrix sizes, you will need to build OpenBLAS from source (or open an issue ticket to make
-the demand for such a precompiled build known).
+=== "Conda-forge"
-#### Precompiled packages
+ OpenBLAS can be installed with `conda` (or `mamba`, `micromamba`, or
+ `pixi`) from conda-forge:
+ ```
+ conda install openblas
+ ```
-*
-*
+ Conda-forge provides a method for switching the default BLAS implementation
+ used by all packages. To use that for OpenBLAS, install `libblas=*=*openblas`
+ (see [the docs on this mechanism](https://conda-forge.org/docs/maintainer/knowledge_base/#switching-blas-implementation)
+ for more details).
-#### Visual Studio
+=== "vcpkg"
-As of OpenBLAS v0.2.15, we support MinGW and Visual Studio (using CMake to generate visual studio solution files – note that you will need at least version 3.11 of CMake for linking to work correctly) to build OpenBLAS on Windows.
+ OpenBLAS can be installed with vcpkg:
+ ```cmd
+ # In classic mode:
+ vcpkg install openblas
-Note that you need a Fortran compiler if you plan to build and use the LAPACK functions included with OpenBLAS. The sections below describe using either `flang` as an add-on to clang/LLVM or `gfortran` as part of MinGW for this purpose. If you want to use the Intel Fortran compiler `ifort` for this, be sure to also use the Intel C compiler `icc` for building the C parts, as the ABI imposed by `ifort` is incompatible with `msvc`.
+ # Or in manifest mode:
+ vcpkg add port openblas
+ ```
-##### 1. Native (MSVC) ABI
+=== "OpenBLAS releases"
-A fully-optimized OpenBLAS that can be statically or dynamically linked to your application can currently be built for the 64-bit architecture with the LLVM compiler infrastructure. We're going to use Miniconda3 to grab all of the tools we need, since some of them are in an experimental status. Before you begin, you'll need to have Microsoft Visual Studio 2015 or newer installed.
+ Windows is the only platform for which binaries are made available by the
+ OpenBLAS project itself. They can be downloaded from the GitHub
+ Releases](https://github.com/OpenMathLib/OpenBLAS/releases) page. These
+ binaries are built with MinGW, using the following build options:
+ ```
+ NUM_THREADS=64 TARGET=GENERIC DYNAMIC_ARCH=1 DYNAMIC_OLDER=1 CONSISTENT_FPCSR=1 INTERFACE=0
+ ```
+ There are separate packages for x86-64 and x86. The zip archive contains
+ the include files, static and shared libraries, as well as configuration
+ files for getting them found via CMake or pkg-config. To use these
+ binaries, create a suitable folder for your OpenBLAS installation and unzip
+ the `.zip` bundle there (note that you will need to edit the provided
+ `openblas.pc` and `OpenBLASConfig.cmake` to reflect the installation path
+ on your computer, as distributed they have "win" or "win64" reflecting the
+ local paths on the system they were built on).
-1. Install Miniconda3 for 64 bits using `winget install --id Anaconda.Miniconda3` or easily download from [conda.io](https://docs.conda.io/en/latest/miniconda.html).
-2. Open the "Anaconda Command Prompt," now available in the Start Menu, or at `%USERPROFILE%\miniconda3\shell\condabin\conda-hook.ps1`.
-3. In that command prompt window, use `cd` to change to the directory where you want to build OpenBLAS
+ Note that the same binaries can be downloaded
+ [from SourceForge](http://sourceforge.net/projects/openblas/files); this is
+ mostly of historical interest.
+
+
+### macOS
+
+To install OpenBLAS with a package manager on macOS, run:
+
+=== "Homebrew"
+
+ ```zsh
+ % brew install openblas
+ ```
+
+=== "MacPorts"
+
+ ```zsh
+ % sudo port install OpenBLAS-devel
+ ```
+
+=== "Conda-forge"
+
+ ```zsh
+ % conda install openblas
+ ```
+
+ Conda-forge provides a method for switching the default BLAS implementation
+ used by all packages. To use that for OpenBLAS, install `libblas=*=*openblas`
+ (see [the docs on this mechanism](https://conda-forge.org/docs/maintainer/knowledge_base/#switching-blas-implementation)
+ for more details).
+
+
+### FreeBSD
+
+You can install OpenBLAS from the FreeBSD [Ports collection](https://www.freebsd.org/ports/index.html):
+```
+pkg install openblas
+```
+
+
+## Building from source
+
+We recommend download the latest [stable version](https://github.com/OpenMathLib/OpenBLAS/releases)
+from the GitHub Releases page, or checking it out from a git tag, rather than a
+dev version from the `develop` branch.
+
+!!! tip
+
+ The User manual contains [a section with detailed information on compiling OpenBLAS](user_manual.md#compiling-openblas),
+ including how to customize builds and how to cross-compile. Please read
+ that documentation first. This page contains only platform-specific build
+ information, and assumes you already understand the general build system
+ invocations to build OpenBLAS, with the specific build options you want to
+ control multi-threading and other non-platform-specific behavior).
+
+
+### Linux and macOS
+
+Ensure you have C and Fortran compilers installed, then simply type `make` to compile the library.
+There are no other build dependencies, nor unusual platform-specific
+environment variables to set or other system setup to do.
+
+!!! note
+
+ When building in an emulator (KVM, QEMU, etc.), please make sure that the combination of CPU features exposed to
+ the virtual environment matches that of an existing CPU to allow detection of the CPU model to succeed.
+ (With `qemu`, this can be done by passing `-cpu host` or a supported model name at invocation).
+
+
+### Windows
+
+We support building OpenBLAS with either MinGW or Visual Studio on Windows.
+Using MSVC will yield an OpenBLAS build with the Windows platform-native ABI.
+Using MinGW will yield a different ABI. We'll describe both methods in detail
+in this section, since the process for each is quite different.
+
+#### Visual Studio & native Windows ABI
+
+For Visual Studio, you can use CMake to generate Visual Studio solution files;
+note that you will need at least CMake 3.11 for linking to work correctly).
+
+Note that you need a Fortran compiler if you plan to build and use the LAPACK
+functions included with OpenBLAS. The sections below describe using either
+`flang` as an add-on to clang/LLVM or `gfortran` as part of MinGW for this
+purpose. If you want to use the Intel Fortran compiler (`ifort` or `ifx`) for
+this, be sure to also use the Intel C compiler (`icc` or `icx`) for building
+the C parts, as the ABI imposed by `ifort` is incompatible with MSVC
+
+A fully-optimized OpenBLAS that can be statically or dynamically linked to your
+application can currently be built for the 64-bit architecture with the LLVM
+compiler infrastructure. We're going to use [Miniconda3](https://docs.anaconda.com/miniconda/)
+to grab all of the tools we need, since some of them are in an experimental
+status. Before you begin, you'll need to have Microsoft Visual Studio 2015 or
+newer installed.
+
+1. Install Miniconda3 for 64-bit Windows using `winget install --id Anaconda.Miniconda3`,
+ or easily download from [conda.io](https://docs.conda.io/en/latest/miniconda.html).
+2. Open the "Anaconda Command Prompt" now available in the Start Menu, or at `%USERPROFILE%\miniconda3\shell\condabin\conda-hook.ps1`.
+3. In that command prompt window, use `cd` to change to the directory where you want to build OpenBLAS.
4. Now install all of the tools we need:
-
```
conda update -n base conda
conda config --add channels conda-forge
conda install -y cmake flang clangdev perl libflang ninja
```
+5. Still in the Anaconda Command Prompt window, activate the 64-bit MSVC environment with `vcvarsall x64`.
+ On Windows 11 with Visual Studio 2022, this would be done by invoking:
+
+ ```shell
+ "c:\Program Files\Microsoft Visual Studio\2022\Preview\vc\Auxiliary\Build\vcvars64.bat"
+ ```
+
+ With VS2019, the command should be the same (except for the year number of course).
+ For other versions of MSVC, please check the Visual Studio documentation for
+ exactly how to invoke the `vcvars64.bat` script.
+
+ Confirm that the environment is active by typing `link`. This should return
+ a long list of possible options for the `link` command. If it just returns
+ _"command not found"_ or similar, review and retype the call to `vcvars64.bat`.
-5. Still in the Anaconda Command Prompt window, activate the MSVC environment for 64 bits with `vcvarsall x64`. On Windows 11 with Visual Studio 2022, this would be done by invoking:
+ !!! note
- ```shell
- "c:\Program Files\Microsoft Visual Studio\2022\Preview\vc\Auxiliary\Build\vcvars64.bat"
- ```
+ if you are working from a Visual Studio command prompt window instead
+ (so that you do not have to do the `vcvars` call), you need to invoke
+ `conda activate` so that `CONDA_PREFIX` etc. get set up correctly before
+ proceeding to step 6. Failing to do so will lead to link errors like
+ `libflangmain.lib` not getting found later in the build.
- With VS2019, the command should be the same – except for the year number, obviously. For other/older versions of MSVC,
- the VS documentation or a quick search on the web should turn up the exact wording you need.
+6. Now configure the project with CMake. Starting in the project directory, execute the following:
+ ```
+ set "LIB=%CONDA_PREFIX%\Library\lib;%LIB%"
+ set "CPATH=%CONDA_PREFIX%\Library\include;%CPATH%"
+ mkdir build
+ cd build
+ cmake .. -G "Ninja" -DCMAKE_CXX_COMPILER=clang-cl -DCMAKE_C_COMPILER=clang-cl -DCMAKE_Fortran_COMPILER=flang -DCMAKE_MT=mt -DBUILD_WITHOUT_LAPACK=no -DNOFORTRAN=0 -DDYNAMIC_ARCH=ON -DCMAKE_BUILD_TYPE=Release
+ ```
- Confirm that the environment is active by typing `link` – this should return a long list of possible options for the `link` command. If it just
- returns "command not found" or similar, review and retype the call to vcvars64.bat.
- **NOTE:** if you are working from a Visual Studio Command prompt window instead (so that you do not have to do the vcvars call), you need to invoke
- `conda activate` so that CONDA_PREFIX etc. get set up correctly before proceeding to step 6. Failing to do so will lead to link errors like
- libflangmain.lib not getting found later in the build.
+ You may want to add further options in the `cmake` command here. For
+ instance, the default only produces a static `.lib` version of the library.
+ If you would rather have a DLL, add `-DBUILD_SHARED_LIBS=ON` above. Note that
+ this step only creates some command files and directories, the actual build
+ happens next.
-6. Now configure the project with CMake. Starting in the project directory, execute the following:
+7. Build the project:
- ```
- set "LIB=%CONDA_PREFIX%\Library\lib;%LIB%"
- set "CPATH=%CONDA_PREFIX%\Library\include;%CPATH%"
- mkdir build
- cd build
- cmake .. -G "Ninja" -DCMAKE_CXX_COMPILER=clang-cl -DCMAKE_C_COMPILER=clang-cl -DCMAKE_Fortran_COMPILER=flang -DCMAKE_MT=mt -DBUILD_WITHOUT_LAPACK=no -DNOFORTRAN=0 -DDYNAMIC_ARCH=ON -DCMAKE_BUILD_TYPE=Release
- ```
+ ```
+ cmake --build . --config Release
+ ```
+ This step will create the OpenBLAS library in the `lib` directory, and
+ various build-time tests in the `test`, `ctest` and `openblas_utest`
+ directories. However it will not separate the header files you might need
+ for building your own programs from those used internally. To put all
+ relevant files in a more convenient arrangement, run the next step.
- You may want to add further options in the `cmake` command here – for instance, the default only produces a static .lib version of the library. If you would rather have a DLL, add -DBUILD_SHARED_LIBS=ON above. Note that this step only creates some command files and directories, the actual build happens next.
+8. Install all relevant files created by the build:
+
+ ```
+ cmake --install . --prefix c:\opt -v
+ ```
+ This will copy all files that are needed for building and running your own
+ programs with OpenBLAS to the given location, creating appropriate
+ subdirectories for the individual kinds of files. In the case of `C:\opt` as
+ given above, this would be:
+
+ - `C:\opt\include\openblas` for the header files,
+ - `C:\opt\bin` for the `libopenblas.dll` shared library,
+ - `C:\opt\lib` for the static library, and
+ - `C:\opt\share` holds various support files that enable other cmake-based
+ build scripts to find OpenBLAS automatically.
-7. Build the project:
+!!! tip "Change in complex types for Visual Studio 2017 and up"
- ```
- cmake --build . --config Release
- ```
- This step will create the OpenBLAS library in the "lib" directory, and various build-time tests in the `test`, `ctest` and `openblas_utest` directories. However it will not separate the header files you might need for building your own programs from those used internally. To put all relevant files in a more convenient arrangement, run the next step.
+ In newer Visual Studio versions, Microsoft has changed
+ [how it handles complex types](https://docs.microsoft.com/en-us/cpp/c-runtime-library/complex-math-support?view=msvc-170#types-used-in-complex-math).
+ Even when using a precompiled version of OpenBLAS, you might need to define
+ `LAPACK_COMPLEX_CUSTOM` in order to define complex types properly for MSVC.
+ For example, some variant of the following might help:
-8. Install all relevant files created by the build
+ ```c
+ #if defined(_MSC_VER)
+ #include
+ #define LAPACK_COMPLEX_CUSTOM
+ #define lapack_complex_float _Fcomplex
+ #define lapack_complex_double _Dcomplex
+ #endif
+ ```
- ```
- cmake --install . --prefix c:\opt -v
- ```
- This will copy all files that are needed for building and running your own programs with OpenBLAS to the given location, creating appropriate subdirectories for the individual kinds of files. In the case of "C:\opt" as given above, this would be C:\opt\include\openblas for the header files,
- C:\opt\bin for the libopenblas.dll and C:\opt\lib for the static library. C:\opt\share holds various support files that enable other cmake-based build scripts to find OpenBLAS automatically.
+ For reference, see
+ [openblas#3661](https://github.com/OpenMathLib/OpenBLAS/issues/3661),
+ [lapack#683](https://github.com/Reference-LAPACK/lapack/issues/683), and
+ [this Stack Overflow question](https://stackoverflow.com/questions/47520244/using-openblas-lapacke-in-visual-studio).
-###### Visual studio 2017+ (C++2017 standard)
-In newer visual studio versions, Microsoft has changed [how it handles complex types](https://docs.microsoft.com/en-us/cpp/c-runtime-library/complex-math-support?view=msvc-170#types-used-in-complex-math). Even when using a precompiled version of OpenBLAS, you might need to define `LAPACK_COMPLEX_CUSTOM` in order to define complex types properly for MSVC. For example, some variant of the following might help:
+!!! warning "Building 32-bit binaries with MSVC"
-```
-#if defined(_MSC_VER)
- #include
- #define LAPACK_COMPLEX_CUSTOM
- #define lapack_complex_float _Fcomplex
- #define lapack_complex_double _Dcomplex
-#endif
-```
+ This method may produce binaries which demonstrate significantly lower
+ performance than those built with the other methods. The Visual Studio
+ compiler does not support the dialect of assembly used in the cpu-specific
+ optimized files, so only the "generic" `TARGET` which is written in pure C
+ will get built. For the same reason it is not possible (and not necessary)
+ to use `-DDYNAMIC_ARCH=ON` in a Visual Studio build. You may consider
+ building for the 32-bit architecture using the GNU (MinGW) ABI instead.
-For reference, see https://github.com/xianyi/OpenBLAS/issues/3661, https://github.com/Reference-LAPACK/lapack/issues/683, and https://stackoverflow.com/questions/47520244/using-openblas-lapacke-in-visual-studio.
-
-###### CMake and Visual Studio
-
-To build OpenBLAS for the 32-bit architecture, you'll need to use the builtin Visual Studio compilers.
-
-!!! note
- This method may produce binaries which demonstrate significantly lower performance than those built with the other methods. (The Visual Studio compiler does not support the dialect of assembly used in the cpu-specific optimized files, so only the "generic" TARGET which is
- written in pure C will get built. For the same reason it is not possible (and not necessary) to use -DDYNAMIC_ARCH=ON in a Visual Studio build) You may consider building for the 32-bit architecture using the GNU (MinGW) ABI.
-
-####### 1. Install CMake at Windows
-
-####### 2. Use CMake to generate Visual Studio solution files
+##### CMake & Visual Studio integration
+To generate Visual Studio solution files, ensure CMake is installed and then run:
```
# Do this from Powershell so cmake can find visual studio
cmake -G "Visual Studio 14 Win64" -DCMAKE_BUILD_TYPE=Release .
```
-###### Build the solution at Visual Studio
+To then build OpenBLAS using those solution files from within Visual Studio, we
+also need Perl. Please install it and ensure it's on the `PATH` (see, e.g.,
+[this Stack Overflow question for how](http://stackoverflow.com/questions/3051049/active-perl-installation-on-windows-operating-system)).
-Note that this step depends on perl, so you'll need to install perl for windows, and put perl on your path so VS can start perl (http://stackoverflow.com/questions/3051049/active-perl-installation-on-windows-operating-system).
-
-Step 2 will build the OpenBLAS solution, open it in VS, and build the projects. Note that the dependencies do not seem to be automatically configured: if you try to build libopenblas directly, it will fail with a message saying that some .obj files aren't found, but if you build the projects libopenblas depends on before building libopenblas, the build will succeed.
+If you build from within Visual Studio, the dependencies may not be
+automatically configured: if you try to build `libopenblas` directly, it may
+fail with a message saying that some `.obj` files aren't found. If this
+happens, you can work around the problem by building the projects that
+`libopenblas` depends on before building `libopenblas` itself.
###### Build OpenBLAS for Universal Windows Platform
-OpenBLAS can be built for use on the [Universal Windows Platform](https://en.wikipedia.org/wiki/Universal_Windows_Platform) using a two step process since commit [c66b842](https://github.com/xianyi/OpenBLAS/commit/c66b842d66c5516e52804bf5a0544d18b1da1b44).
+OpenBLAS can be built targeting [Universal Windows Platform](https://en.wikipedia.org/wiki/Universal_Windows_Platform)
+(UWP) like this:
-####### 1. Follow steps 1 and 2 above to build the Visual Studio solution files for Windows. This builds the helper executables which are required when building the OpenBLAS Visual Studio solution files for UWP in step 2.
+1. Follow the steps above to build the Visual Studio solution files for
+ Windows. This builds the helper executables which are required when building
+ the OpenBLAS Visual Studio solution files for UWP in step 2.
+2. Remove the generated `CMakeCache.txt` and the `CMakeFiles` directory from
+ the OpenBLAS source directory, then re-run CMake with the following options:
-####### 2. Remove the generated CMakeCache.txt and CMakeFiles directory from the OpenBLAS source directory and re-run CMake with the following options:
-
-```
-# do this to build UWP compatible solution files
-cmake -G "Visual Studio 14 Win64" -DCMAKE_SYSTEM_NAME=WindowsStore -DCMAKE_SYSTEM_VERSION="10.0" -DCMAKE_SYSTEM_PROCESSOR=AMD64 -DVS_WINRT_COMPONENT=TRUE -DCMAKE_BUILD_TYPE=Release .
-```
-
-####### Build the solution with Visual Studio
-
-This will build the OpenBLAS binaries with the required settings for use with UWP.
-
-##### 2. GNU (MinGW) ABI
-
-The resulting library can be used in Visual Studio, but it can only be linked dynamically. This configuration has not been thoroughly tested and should be considered experimental.
-
-###### Incompatible x86 calling conventions
-
-Due to incompatibilities between the calling conventions of MinGW and Visual Studio you will need to make the following modifications ( **32-bit only** ):
-
-1. Use the newer GCC 4.7.0. The older GCC (<4.7.0) has an ABI incompatibility for returning aggregate structures larger than 8 bytes with MSVC.
+ ```
+ # do this to build UWP compatible solution files
+ cmake -G "Visual Studio 14 Win64" -DCMAKE_SYSTEM_NAME=WindowsStore -DCMAKE_SYSTEM_VERSION="10.0" -DCMAKE_SYSTEM_PROCESSOR=AMD64 -DVS_WINRT_COMPONENT=TRUE -DCMAKE_BUILD_TYPE=Release .
+ ```
+3. Now build the solution with Visual Studio.
-###### Build OpenBLAS on Windows OS
-1. Install the MinGW (GCC) compiler suite, either 32-bit (http://www.mingw.org/) or 64-bit (http://mingw-w64.sourceforge.net/). Be sure to install its gfortran package as well (unless you really want to build the BLAS part of OpenBLAS only) and check that gcc and gfortran are the same version – mixing compilers from different sources or release versions can lead to strange error messages in the linking stage. In addition, please install MSYS with MinGW.
-1. Build OpenBLAS in the MSYS shell. Usually, you can just type "make". OpenBLAS will detect the compiler and CPU automatically.
-1. After the build is complete, OpenBLAS will generate the static library "libopenblas.a" and the shared dll library "libopenblas.dll" in the folder. You can type "make PREFIX=/your/installation/path install" to install the library to a certain location.
+#### MinGW & GNU ABI
!!! note
- We suggest using official MinGW or MinGW-w64 compilers. A user reported that s/he met `Unhandled exception` by other compiler suite. https://groups.google.com/forum/#!topic/openblas-users/me2S4LkE55w
-Note also that older versions of the alternative builds of mingw-w64 available through http://www.msys2.org may contain a defect that leads to a compilation failure accompanied by the error message
-```
-:0:4: error: expected identifier or '(' before numeric constant
-```
-If you encounter this, please upgrade your msys2 setup or see https://github.com/xianyi/OpenBLAS/issues/1503 for a workaround.
+ The resulting library from building with MinGW as described below can be
+ used in Visual Studio, but it can only be linked dynamically. This
+ configuration has not been thoroughly tested and should be considered
+ experimental.
-###### Generate import library (before 0.2.10 version)
-1. First, you will need to have the `lib.exe` tool in the Visual Studio command prompt.
-1. Open the command prompt and type `cd OPENBLAS_TOP_DIR/exports`, where OPENBLAS_TOP_DIR is the main folder of your OpenBLAS installation.
-1. For a 32-bit library, type `lib /machine:i386 /def:libopenblas.def`. For 64-bit, type `lib /machine:X64 /def:libopenblas.def`.
-1. This will generate the import library "libopenblas.lib" and the export library "libopenblas.exp" in OPENBLAS_TOP_DIR/exports. Although these two files have the same name, they are totally different.
+To build OpenBLAS on Windows with MinGW:
-###### Generate import library (0.2.10 and after version)
-1. OpenBLAS already generated the import library "libopenblas.dll.a" for "libopenblas.dll".
+1. Install the MinGW (GCC) compiler suite, either the 32-bit
+ [MinGW]((http://www.mingw.org/) or the 64-bit
+ [MinGW-w64](http://mingw-w64.sourceforge.net/) toolchain. Be sure to install
+ its `gfortran` package as well (unless you really want to build the BLAS part
+ of OpenBLAS only) and check that `gcc` and `gfortran` are the same version.
+ In addition, please install MSYS2 with MinGW.
+2. Build OpenBLAS in the MSYS2 shell. Usually, you can just type `make`.
+ OpenBLAS will detect the compiler and CPU automatically.
+3. After the build is complete, OpenBLAS will generate the static library
+ `libopenblas.a` and the shared library `libopenblas.dll` in the folder. You
+ can type `make PREFIX=/your/installation/path install` to install the
+ library to a certain location.
-###### generate windows native PDB files from gcc/gfortran build
-Tool to do so is available at https://github.com/rainers/cv2pdb
+Note that OpenBLAS will generate the import library `libopenblas.dll.a` for
+`libopenblas.dll` by default.
-###### Use OpenBLAS .dll library in Visual Studio
-1. Copy the import library (before 0.2.10: "OPENBLAS_TOP_DIR/exports/libopenblas.lib", 0.2.10 and after: "OPENBLAS_TOP_DIR/libopenblas.dll.a") and .dll library "libopenblas.dll" into the same folder(The folder of your project that is going to use the BLAS library. You may need to add the libopenblas.dll.a to the linker input list: properties->Linker->Input).
-1. Please follow the documentation about using third-party .dll libraries in MS Visual Studio 2008 or 2010. Make sure to link against a library for the correct architecture. For example, you may receive an error such as "The application was unable to start correctly (0xc000007b)" which typically indicates a mismatch between 32/64-bit libraries.
+If you want to generate Windows-native PDB files from a MinGW build, you can
+use the [cv2pdb](https://github.com/rainers/cv2pdb) tool to do so.
-!!! note
- If you need CBLAS, you should include cblas.h in /your/installation/path/include in Visual Studio. Please read [this page](http://github.com/xianyi/OpenBLAS/issues/95).
+To then use the built OpenBLAS shared library in Visual Studio:
-###### Limitations
-* Both static and dynamic linking are supported with MinGW. With Visual Studio, however, only dynamic linking is supported and so you should use the import library.
-* Debugging from Visual Studio does not work because MinGW and Visual Studio have incompatible formats for debug information (PDB vs. DWARF/STABS). You should either debug with GDB on the command-line or with a visual frontend, for instance [Eclipse](http://www.eclipse.org/cdt/) or [Qt Creator](http://qt.nokia.com/products/developer-tools/).
+1. Copy the import library (`OPENBLAS_TOP_DIR/libopenblas.dll.a`) and the
+ shared library (`libopenblas.dll`) into the same folder (this must be the
+ folder of your project that is going to use the BLAS library. You may need
+ to add `libopenblas.dll.a` to the linker input list: `properties->Linker->Input`).
+2. Please follow the Visual Studio documentation about using third-party .dll
+ libraries, and make sure to link against a library for the correct
+ architecture.[^1]
+3. If you need CBLAS, you should include `cblas.h` in
+ `/your/installation/path/include` in Visual Studio. Please see
+ [openblas#95](http://github.com/OpenMathLib/OpenBLAS/issues/95) for more details.
+
+[^1]:
+ If the OpenBLAS DLLs are not linked correctly, you may see an error like
+ _"The application was unable to start correctly (0xc000007b)"_, which typically
+ indicates a mismatch between 32-bit and 64-bit libraries.
+
+!!! info "Limitations of using the MinGW build within Visual Studio"
+
+ - Both static and dynamic linking are supported with MinGW. With Visual
+ Studio, however, only dynamic linking is supported and so you should use
+ the import library.
+ - Debugging from Visual Studio does not work because MinGW and Visual
+ Studio have incompatible formats for debug information (PDB vs.
+ DWARF/STABS). You should either debug with GDB on the command line or
+ with a visual frontend, for instance [Eclipse](http://www.eclipse.org/cdt/) or
+ [Qt Creator](http://qt.nokia.com/products/developer-tools/).
#### Windows on Arm
-##### Prerequisites
+The following tools needs to be installed to build for Windows on Arm (WoA):
-Following tools needs to be installed
+- Clang for Windows on Arm.
+ Find the latest LLVM build for WoA from [LLVM release page](https://releases.llvm.org/).
+ E.g: LLVM 12 build for WoA64 can be found [here](https://github.com/llvm/llvm-project/releases/download/llvmorg-12.0.0/LLVM-12.0.0-woa64.exe)
+ Run the LLVM installer and ensure that LLVM is added to environment PATH.
+- Download and install classic Flang for Windows on Arm.
+ Classic Flang is the only available Fortran compiler for Windows on Arm for now.
+ A pre-release build can be found [here](https://github.com/kaadam/flang/releases/tag/v0.1)
+ There is no installer for classic flang and the zip package can be
+ extracted and the path needs to be added to environment `PATH`.
+ E.g., in PowerShell:
+ ```
+ $env:Path += ";C:\flang_woa\bin"
+ ```
-###### 1. Download and install clang for windows on arm
+The following steps describe how to build the static library for OpenBLAS with and without LAPACK:
-Find the latest LLVM build for WoA from [LLVM release page](https://releases.llvm.org/)
+1. Build OpenBLAS static library with BLAS and LAPACK routines with Make:
-E.g: LLVM 12 build for WoA64 can be found [here](https://github.com/llvm/llvm-project/releases/download/llvmorg-12.0.0/LLVM-12.0.0-woa64.exe)
+ ```bash
+ $ make CC="clang-cl" HOSTCC="clang-cl" AR="llvm-ar" BUILD_WITHOUT_LAPACK=0 NOFORTRAN=0 DYNAMIC_ARCH=0 TARGET=ARMV8 ARCH=arm64 BINARY=64 USE_OPENMP=0 PARALLEL=1 RANLIB="llvm-ranlib" MAKE=make F_COMPILER=FLANG FC=FLANG FFLAGS_NOOPT="-march=armv8-a -cpp" FFLAGS="-march=armv8-a -cpp" NEED_PIC=0 HOSTARCH=arm64 libs netlib
+ ```
-Run the LLVM installer and ensure that LLVM is added to environment PATH.
+2. Build static library with BLAS routines using CMake:
-###### 2. Download and install classic flang for windows on arm
+ Classic Flang has compatibility issues with CMake, hence only BLAS routines can be compiled with CMake:
-Classic flang is the only available FORTRAN compiler for windows on arm for now and a pre-release build can be found [here](https://github.com/kaadam/flang/releases/tag/v0.1)
+ ```bash
+ $ mkdir build
+ $ cd build
+ $ cmake .. -G Ninja -DCMAKE_C_COMPILER=clang -DBUILD_WITHOUT_LAPACK=1 -DNOFORTRAN=1 -DDYNAMIC_ARCH=0 -DTARGET=ARMV8 -DARCH=arm64 -DBINARY=64 -DUSE_OPENMP=0 -DCMAKE_SYSTEM_PROCESSOR=ARM64 -DCMAKE_CROSSCOMPILING=1 -DCMAKE_SYSTEM_NAME=Windows
+ $ cmake --build . --config Release
+ ```
-There is no installer for classic flang and the zip package can be extracted and the path needs to be added to environment PATH.
+!!! tip "`getarch.exe` execution error"
-E.g: on PowerShell
+ If you notice that platform-specific headers by `getarch.exe` are not
+ generated correctly, this could be due to a known debug runtime DLL issue for
+ arm64 platforms. Please check out [this page](https://linaro.atlassian.net/wiki/spaces/WOAR/pages/28677636097/Debug+run-time+DLL+issue#Workaround)
+ for a workaround.
-```
-$env:Path += ";C:\flang_woa\bin"
-```
-##### Build
+#### Generating an import library
-The following steps describe how to build the static library for OpenBLAS with and without LAPACK
+Microsoft Windows has this thing called "import libraries". You need it for
+MSVC; you don't need it for MinGW because the `ld` linker is smart enough -
+however, you may still want it for some reason, so we'll describe the process
+for both MSVC and MinGW.
-###### 1. Build OpenBLAS static library with BLAS and LAPACK routines with Make
+Import libraries are compiled from a list of what symbols to use, which are
+contained in a `.def` file. A `.def` file should be already be present in the
+`exports` directory under the top-level OpenBLAS directory after you've run a build.
+In your shell, move to this directory: `cd exports`.
-Following command can be used to build OpenBLAS static library with BLAS and LAPACK routines
+=== "MSVC"
-```bash
-$ make CC="clang-cl" HOSTCC="clang-cl" AR="llvm-ar" BUILD_WITHOUT_LAPACK=0 NOFORTRAN=0 DYNAMIC_ARCH=0 TARGET=ARMV8 ARCH=arm64 BINARY=64 USE_OPENMP=0 PARALLEL=1 RANLIB="llvm-ranlib" MAKE=make F_COMPILER=FLANG FC=FLANG FFLAGS_NOOPT="-march=armv8-a -cpp" FFLAGS="-march=armv8-a -cpp" NEED_PIC=0 HOSTARCH=arm64 libs netlib
-```
+ Unlike MinGW, MSVC absolutely requires an import library. Now the C ABI of
+ MSVC and MinGW are actually identical, so linking is actually okay (any
+ incompatibility in the C ABI would be a bug).
-###### 2. Build static library with BLAS routines using CMake
+ The import libraries of MSVC have the suffix `.lib`. They are generated
+ from a `.def` file using MSVC's `lib.exe`. See [the MSVC instructions](use_visual_studio.md#generate-import-library-before-0210-version).
-Classic flang has compatibility issues with cmake hence only BLAS routines can be compiled with CMake
+=== "MinGW"
-```bash
-$ mkdir build
-$ cd build
-$ cmake .. -G Ninja -DCMAKE_C_COMPILER=clang -DBUILD_WITHOUT_LAPACK=1 -DNOFORTRAN=1 -DDYNAMIC_ARCH=0 -DTARGET=ARMV8 -DARCH=arm64 -DBINARY=64 -DUSE_OPENMP=0 -DCMAKE_SYSTEM_PROCESSOR=ARM64 -DCMAKE_CROSSCOMPILING=1 -DCMAKE_SYSTEM_NAME=Windows
-$ cmake --build . --config Release
-```
-
-###### `getarch.exe` execution error
-
-If you notice that platform-specific headers by `getarch.exe` are not generated correctly, It could be due to a known debug runtime DLL issue for arm64 platforms. Please check out [link](https://linaro.atlassian.net/wiki/spaces/WOAR/pages/28677636097/Debug+run-time+DLL+issue#Workaround) for the workaround.
-
-#### MinGW import library
-
-Microsoft Windows has this thing called "import libraries". You don't need it in MinGW because the `ld` linker from GNU Binutils is smart, but you may still want it for whatever reason.
-
-##### Make the `.def`
-
-Import libraries are compiled from a list of what symbols to use, `.def`. This should be already in your `exports` directory: `cd OPENBLAS_TOP_DIR/exports`.
-
-##### Making a MinGW import library
-
-MinGW import libraries have the suffix `.a`, same as static libraries. (It's actually more common to do `.dll.a`...)
-
-You need to first prepend `libopenblas.def` with a line `LIBRARY libopenblas.dll`:
+ MinGW import libraries have the suffix `.a`, just like static libraries.
+ Our goal is to produce the file `libopenblas.dll.a`.
+ You need to first insert a line `LIBRARY libopenblas.dll` in `libopenblas.def`:
+ ```
cat <(echo "LIBRARY libopenblas.dll") libopenblas.def > libopenblas.def.1
mv libopenblas.def.1 libopenblas.def
+ ```
-Now it probably looks like:
-
+ Now the `.def` file probably looks like:
+ ```
LIBRARY libopenblas.dll
EXPORTS
caxpy=caxpy_ @1
caxpy_=caxpy_ @2
...
+ ```
+ Then, generate the import library: `dlltool -d libopenblas.def -l libopenblas.dll.a`
-Then, generate the import library: `dlltool -d libopenblas.def -l libopenblas.a`
+ _Again, there is basically **no point** in making an import library for use in MinGW. It actually slows down linking._
-Again, there is basically **no point** in making an import library for use in MinGW. It actually slows down linking.
-
-##### Making a MSVC import library
-
-Unlike MinGW, MSVC absolutely requires an import library. Now the C ABI of MSVC and MinGW are actually identical, so linking is actually okay. (Any incompatibility in the C ABI would be a bug.)
-
-The import libraries of MSVC have the suffix `.lib`. They are generated from a `.def` file using MSVC's `lib.exe`. See [the MSVC instructions](use_visual_studio.md#generate-import-library-before-0210-version).
-
-##### Notes
-
-* Always remember that MinGW is **not the same** as MSYS2 or Cygwin. MSYS2 and Cygwin are full POSIX environments with a lot of magic such as `fork()` and its own `malloc()`. MinGW, which builds on the normal Microsoft C Runtime, has none of that. Be clear about which one you are building for.
-
-### Mac OSX
-
-If your CPU is Sandy Bridge, please use Clang version 3.1 and above. The Clang 3.0 will generate the wrong AVX binary code of OpenBLAS.
-
-#### Precompiled packages
-
-
-
-`brew install openblas`
-
-or using the conda package manager from
-
-(which also has packages for the new M1 cpu)
-
- `conda install openblas`
-
-#### Build on Apple M1
-
-On newer versions of Xcode and on arm64, you might need to compile with a newer macOS target (11.0) than the default (10.8) with `MACOSX_DEPLOYMENT_TARGET=11.0`, or switch your command-line tools to use an older SDK (e.g., [13.1](https://developer.apple.com/download/all/?q=Xcode%2013)).
-
-* without Fortran compiler （cannot build LAPACK)
- ```bash
- $ make CC=cc NOFORTRAN=1
- ```
-* with Fortran compiler (you could `brew install gfortran`) https://github.com/xianyi/OpenBLAS/issues/3032
- ```bash
- $ export MACOSX_DEPLOYMENT_TARGET=11.0
- $ make CC=cc FC=gfortran
- ```
### Android
-#### Prerequisites
+To build OpenBLAS for Android, you will need the following tools installed on your machine:
-In addition to the Android NDK, you will need both Perl and a C compiler on the build host as these are currently
-required by the OpenBLAS build environment.
+- [The Android NDK](https://developer.android.com/ndk/)
+- Perl
+- Clang compiler on the build machine
+
+The next two sections below describe how to build with Clang for ARMV7 and
+ARMV8 targets, respectively. The same basic principles as described below for
+ARMV8 should also apply to building an x86 or x86-64 version (substitute
+something like `NEHALEM` for the target instead of `ARMV8`, and replace all the
+`aarch64` in the toolchain paths with `x86` or `x96_64` as appropriate).
+
+!!! info "Historic note"
+
+ Since NDK version 19, the default toolchain is provided as a standalone
+ toolchain, so building one yourself following
+ [building a standalone toolchain](http://developer.android.com/ndk/guides/standalone_toolchain.html)
+ should no longer be necessary.
-#### Building with android NDK using clang compiler
-Around version 11 Android NDKs stopped supporting gcc, so you would need to use clang to compile OpenBLAS. clang is supported from OpenBLAS 0.2.20 version onwards. See below sections on how to build with clang for ARMV7 and ARMV8 targets. The same basic principles as described below for ARMV8 should also apply to building an x86 or x86_64 version (substitute something like NEHALEM for the target instead of ARMV8 and replace all the aarch64 in the toolchain paths obviously)
-"Historic" notes:
-Since version 19 the default toolchain is provided as a standalone toolchain, so building one yourself following [building a standalone toolchain](http://developer.android.com/ndk/guides/standalone_toolchain.html) should no longer be necessary.
-If you want to use static linking with an old NDK version older than about r17, you need to choose an API level below 23 currently due to NDK bug 272 (https://github.com/android-ndk/ndk/issues/272 , the libc.a lacks a definition of stderr) that will probably be fixed in r17 of the NDK.
+#### Building for ARMV7
-#### Build ARMV7 with clang
-```
-## Set path to ndk-bundle
+```bash
+# Set path to ndk-bundle
export NDK_BUNDLE_DIR=/path/to/ndk-bundle
-## Set the PATH to contain paths to clang and arm-linux-androideabi-* utilities
+# Set the PATH to contain paths to clang and arm-linux-androideabi-* utilities
export PATH=${NDK_BUNDLE_DIR}/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin:${NDK_BUNDLE_DIR}/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH
-## Set LDFLAGS so that the linker finds the appropriate libgcc
+# Set LDFLAGS so that the linker finds the appropriate libgcc
export LDFLAGS="-L${NDK_BUNDLE_DIR}/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/lib/gcc/arm-linux-androideabi/4.9.x"
-## Set the clang cross compile flags
+# Set the clang cross compile flags
export CLANG_FLAGS="-target arm-linux-androideabi -marm -mfpu=vfp -mfloat-abi=softfp --sysroot ${NDK_BUNDLE_DIR}/platforms/android-23/arch-arm -gcc-toolchain ${NDK_BUNDLE_DIR}/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/"
#OpenBLAS Compile
make TARGET=ARMV7 ONLY_CBLAS=1 AR=ar CC="clang ${CLANG_FLAGS}" HOSTCC=gcc ARM_SOFTFP_ABI=1 -j4
```
-On a Mac, it may also be necessary to give the complete path to the `ar` utility in the make command above, like so:
-```
+
+On macOS, it may also be necessary to give the complete path to the `ar`
+utility in the make command above, like so:
+```bash
AR=${NDK_BUNDLE_DIR}/toolchains/arm-linux-androideabi-4.9/prebuilt/darwin-x86_64/bin/arm-linux-androideabi-gcc-ar
```
-otherwise you may get a linker error complaining about a "malformed archive header name at 8" when the native OSX ar command was invoked instead.
+otherwise you may get a linker error complaining like `malformed archive header
+name at 8` when the native macOS `ar` command was invoked instead.
+
-#### Build ARMV8 with clang
-```
-## Set path to ndk-bundle
+#### Building for ARMV8
+
+```bash
+# Set path to ndk-bundle
export NDK_BUNDLE_DIR=/path/to/ndk-bundle/
-## Export PATH to contain directories of clang and aarch64-linux-android-* utilities
+# Export PATH to contain directories of clang and aarch64-linux-android-* utilities
export PATH=${NDK_BUNDLE_DIR}/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/:${NDK_BUNDLE_DIR}/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH
-## Setup LDFLAGS so that loader can find libgcc and pass -lm for sqrt
+# Setup LDFLAGS so that loader can find libgcc and pass -lm for sqrt
export LDFLAGS="-L${NDK_BUNDLE_DIR}/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/lib/gcc/aarch64-linux-android/4.9.x -lm"
-## Setup the clang cross compile options
+# Setup the clang cross compile options
export CLANG_FLAGS="-target aarch64-linux-android --sysroot ${NDK_BUNDLE_DIR}/platforms/android-23/arch-arm64 -gcc-toolchain ${NDK_BUNDLE_DIR}/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/"
-## Compile
+# Compile
make TARGET=ARMV8 ONLY_CBLAS=1 AR=ar CC="clang ${CLANG_FLAGS}" HOSTCC=gcc -j4
```
-Note: Using TARGET=CORTEXA57 in place of ARMV8 will pick up better optimized routines. Implementations for CORTEXA57 target is compatible with all other armv8 targets.
+Note: using `TARGET=CORTEXA57` in place of `ARMV8` will pick up better
+optimized routines. Implementations for the `CORTEXA57` target are compatible
+with all other `ARMV8` targets.
-Note: For NDK 23b, something as simple as
-```
+Note: for NDK 23b, something as simple as:
+```bash
export PATH=/opt/android-ndk-r23b/toolchains/llvm/prebuilt/linux-x86_64/bin/:$PATH
make HOSTCC=gcc CC=/opt/android-ndk-r23b/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android31-clang ONLY_CBLAS=1 TARGET=ARMV8
```
appears to be sufficient on Linux.
-#### Alternative script which was tested on OSX with NDK(21.3.6528147)
-This script will build openblas for 3 architecture (ARMV7,ARMV8,X86) and put them with `sudo make install` to `/opt/OpenBLAS/lib`
-```
-export NDK=YOUR_PATH_TO_SDK/Android/sdk/ndk/21.3.6528147
-export TOOLCHAIN=$NDK/toolchains/llvm/prebuilt/darwin-x86_64
-make clean
-make \
- TARGET=ARMV7 \
- ONLY_CBLAS=1 \
- CC="$TOOLCHAIN"/bin/armv7a-linux-androideabi21-clang \
- AR="$TOOLCHAIN"/bin/arm-linux-androideabi-ar \
- HOSTCC=gcc \
- ARM_SOFTFP_ABI=1 \
+??? note "Alternative build script for 3 architectures"
+
+ This script will build OpenBLAS for 3 architecture (`ARMV7`, `ARMV8`, `X86`) and install them to `/opt/OpenBLAS/lib`.
+ It was tested on macOS with NDK version 21.3.6528147.
+
+ ```bash
+ export NDK=YOUR_PATH_TO_SDK/Android/sdk/ndk/21.3.6528147
+ export TOOLCHAIN=$NDK/toolchains/llvm/prebuilt/darwin-x86_64
+
+ make clean
+ make \
+ TARGET=ARMV7 \
+ ONLY_CBLAS=1 \
+ CC="$TOOLCHAIN"/bin/armv7a-linux-androideabi21-clang \
+ AR="$TOOLCHAIN"/bin/arm-linux-androideabi-ar \
+ HOSTCC=gcc \
+ ARM_SOFTFP_ABI=1 \
+ -j4
+ sudo make install
+
+ make clean
+ make \
+ TARGET=CORTEXA57 \
+ ONLY_CBLAS=1 \
+ CC=$TOOLCHAIN/bin/aarch64-linux-android21-clang \
+ AR=$TOOLCHAIN/bin/aarch64-linux-android-ar \
+ HOSTCC=gcc \
-j4
-sudo make install
+ sudo make install
-make clean
-make \
- TARGET=CORTEXA57 \
- ONLY_CBLAS=1 \
- CC=$TOOLCHAIN/bin/aarch64-linux-android21-clang \
- AR=$TOOLCHAIN/bin/aarch64-linux-android-ar \
- HOSTCC=gcc \
- -j4
-sudo make install
-
-make clean
-make \
- TARGET=ATOM \
- ONLY_CBLAS=1 \
+ make clean
+ make \
+ TARGET=ATOM \
+ ONLY_CBLAS=1 \
CC="$TOOLCHAIN"/bin/i686-linux-android21-clang \
AR="$TOOLCHAIN"/bin/i686-linux-android-ar \
HOSTCC=gcc \
ARM_SOFTFP_ABI=1 \
-j4
-sudo make install
+ sudo make install
-## This will build for x86_64
-make clean
-make \
- TARGET=ATOM BINARY=64\
+ ## This will build for x86_64
+ make clean
+ make \
+ TARGET=ATOM BINARY=64\
ONLY_CBLAS=1 \
CC="$TOOLCHAIN"/bin/x86_64-linux-android21-clang \
AR="$TOOLCHAIN"/bin/x86_64-linux-android-ar \
HOSTCC=gcc \
ARM_SOFTFP_ABI=1 \
-j4
-sudo make install
-```
-Also you can find full list of target architectures in [TargetsList.txt](https://github.com/xianyi/OpenBLAS/blob/develop/TargetList.txt)
+ sudo make install
+ ```
+ You can find full list of target architectures in [TargetList.txt](https://github.com/OpenMathLib/OpenBLAS/blob/develop/TargetList.txt)
-***
-anything below this line should be irrelevant nowadays unless you need to perform software archeology
-***
-#### Building OpenBLAS with very old gcc-based versions of the NDK, without Fortran
-
-The prebuilt Android NDK toolchains do not include Fortran, hence parts like LAPACK cannot be built. You can still build OpenBLAS without it. For instructions on how to build OpenBLAS with Fortran, see the [next section](#building-openblas-with-fortran).
-
-To use easily the prebuilt toolchains, follow [building a standalone toolchain](http://developer.android.com/ndk/guides/standalone_toolchain.html) for your desired architecture.
-This would be `arm-linux-androideabi-gcc-4.9` for ARMV7 and `aarch64-linux-android-gcc-4.9` for ARMV8.
-
-You can build OpenBLAS (0.2.19 and earlier) with:
-```
-## Add the toolchain to your path
-export PATH=/path/to/standalone-toolchain/bin:$PATH
-
-## Build without Fortran for ARMV7
-make TARGET=ARMV7 HOSTCC=gcc CC=arm-linux-androideabi-gcc NOFORTRAN=1 libs
-## Build without Fortran for ARMV8
-make TARGET=ARMV8 BINARY=64 HOSTCC=gcc CC=aarch64-linux-android-gcc NOFORTRAN=1 libs
-```
-
-Since we are cross-compiling, we make the `libs` recipe, not `all`. Otherwise you will get errors when trying to link/run tests as versions up to and including 0.2.19 cannot build a shared library for Android.
-
-From 0.2.20 on, you should leave off the "libs" to get a full build, and you may want to use the softfp ABI instead of the deprecated hardfp one on ARMV7 so you would use
-```
-## Add the toolchain to your path
-export PATH=/path/to/standalone-toolchain/bin:$PATH
-
-## Build without Fortran for ARMV7
-make TARGET=ARMV7 ARM_SOFTFP_ABI=1 HOSTCC=gcc CC=arm-linux-androideabi-gcc NOFORTRAN=1
-## Build without Fortran for ARMV8
-make TARGET=ARMV8 BINARY=64 HOSTCC=gcc CC=aarch64-linux-android-gcc NOFORTRAN=1
-```
-
-If you get an error about stdio.h not being found, you need to specify your sysroot in the CFLAGS argument to `make` like
-```CFLAGS=--sysroot=$NDK/platforms/android-16/arch-arm```
-When you are done, install OpenBLAS into the desired directory. Be sure to also use all command line options
-here that you specified for building, otherwise errors may occur as it tries to install things you did not build:
-```
-make PREFIX=/path/to/install-dir TARGET=... install
-```
-
-#### Building OpenBLAS with Fortran
-
-Instructions on how to build the GNU toolchains with Fortran can be found [here](https://github.com/buffer51/android-gfortran). The [Releases section](https://github.com/buffer51/android-gfortran/releases) provides prebuilt versions, use the standalone one.
-
-You can build OpenBLAS with:
-```
-## Add the toolchain to your path
-export PATH=/path/to/standalone-toolchain-with-fortran/bin:$PATH
-
-## Build with Fortran for ARMV7
-make TARGET=ARMV7 HOSTCC=gcc CC=arm-linux-androideabi-gcc FC=arm-linux-androideabi-gfortran libs
-## Build with LAPACK for ARMV8
-make TARGET=ARMV8 BINARY=64 HOSTCC=gcc CC=aarch64-linux-android-gcc FC=aarch64-linux-android-gfortran libs
-```
-
-As mentioned above you can leave off the `libs` argument here when building 0.2.20 and later, and you may want to add ARM_SOFTFP_ABI=1 when building for ARMV7.
-
-#### Linking OpenBLAS (0.2.19 and earlier) for ARMV7
-
-If you are using `ndk-build`, you need to set the ABI to hard floating points in your Application.mk:
-```
-APP_ABI := armeabi-v7a-hard
-```
-
-This will set the appropriate flags for you. If you are not using `ndk-build`, you will want to add the following flags:
-```
-TARGET_CFLAGS += -mhard-float -D_NDK_MATH_NO_SOFTFP=1
-TARGET_LDFLAGS += -Wl,--no-warn-mismatch -lm_hard
-```
-
-From 0.2.20 on, it is also possible to build for the softfp ABI by specifying ARM_SOFTFP_ABI=1 during the build.
-In that case, also make sure that all your dependencies are compiled with -mfloat-abi=softfp as well, as mixing
-"hard" and "soft" floating point ABIs in a program will make it crash.
### iPhone/iOS
-As none of the current developers uses iOS, the following instructions are what was found to work in our Azure CI setup, but as far as we know this builds a fully working OpenBLAS for this platform.
+As none of the current developers uses iOS, the following instructions are what
+was found to work in our Azure CI setup, but as far as we know this builds a
+fully working OpenBLAS for this platform.
Go to the directory where you unpacked OpenBLAS,and enter the following commands:
-```
- CC=/Applications/Xcode_12.4.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
+```bash
+CC=/Applications/Xcode_12.4.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
CFLAGS= -O2 -Wno-macro-redefined -isysroot /Applications/Xcode_12.4.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS14.4.sdk -arch arm64 -miphoneos-version-min=10.0
make TARGET=ARMV8 DYNAMIC_ARCH=1 NUM_THREADS=32 HOSTCC=clang NOFORTRAN=1
```
-Adjust MIN_IOS_VERSION as necessary for your installation, e.g. change the version number
+Adjust `MIN_IOS_VERSION` as necessary for your installation. E.g., change the version number
to the minimum iOS version you want to target and execute this file to build the library.
+
### MIPS
-For mips targets you will need latest toolchains
-P5600 - MTI GNU/Linux Toolchain
-I6400, P6600 - IMG GNU/Linux Toolchain
+For MIPS targets you will need latest toolchains:
-The download link is below
-(http://codescape-mips-sdk.imgtec.com/components/toolchain/2016.05-03/downloads.html)
+- P5600 - MTI GNU/Linux Toolchain
+- I6400, P6600 - IMG GNU/Linux Toolchain
-You can use following commandlines for builds
+You can use following commandlines for builds:
+```bash
+IMG_TOOLCHAIN_DIR={full IMG GNU/Linux Toolchain path including "bin" directory -- for example, /opt/linux_toolchain/bin}
+IMG_GCC_PREFIX=mips-img-linux-gnu
+IMG_TOOLCHAIN=${IMG_TOOLCHAIN_DIR}/${IMG_GCC_PREFIX}
- IMG_TOOLCHAIN_DIR={full IMG GNU/Linux Toolchain path including "bin" directory -- for example, /opt/linux_toolchain/bin}
- IMG_GCC_PREFIX=mips-img-linux-gnu
- IMG_TOOLCHAIN=${IMG_TOOLCHAIN_DIR}/${IMG_GCC_PREFIX}
+# I6400 Build (n32):
+make BINARY=32 BINARY32=1 CC=$IMG_TOOLCHAIN-gcc AR=$IMG_TOOLCHAIN-ar FC="$IMG_TOOLCHAIN-gfortran -EL -mabi=n32" RANLIB=$IMG_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS=$CFLAGS LDFLAGS=$CFLAGS TARGET=I6400
- I6400 Build (n32):
- make BINARY=32 BINARY32=1 CC=$IMG_TOOLCHAIN-gcc AR=$IMG_TOOLCHAIN-ar FC="$IMG_TOOLCHAIN-gfortran -EL -mabi=n32" RANLIB=$IMG_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS=$CFLAGS LDFLAGS=$CFLAGS TARGET=I6400
+# I6400 Build (n64):
+make BINARY=64 BINARY64=1 CC=$IMG_TOOLCHAIN-gcc AR=$IMG_TOOLCHAIN-ar FC="$IMG_TOOLCHAIN-gfortran -EL" RANLIB=$IMG_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS=$CFLAGS LDFLAGS=$CFLAGS TARGET=I6400
- I6400 Build (n64):
- make BINARY=64 BINARY64=1 CC=$IMG_TOOLCHAIN-gcc AR=$IMG_TOOLCHAIN-ar FC="$IMG_TOOLCHAIN-gfortran -EL" RANLIB=$IMG_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS=$CFLAGS LDFLAGS=$CFLAGS TARGET=I6400
+# P6600 Build (n32):
+make BINARY=32 BINARY32=1 CC=$IMG_TOOLCHAIN-gcc AR=$IMG_TOOLCHAIN-ar FC="$IMG_TOOLCHAIN-gfortran -EL -mabi=n32" RANLIB=$IMG_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS=$CFLAGS LDFLAGS=$CFLAGS TARGET=P6600
- P6600 Build (n32):
- make BINARY=32 BINARY32=1 CC=$IMG_TOOLCHAIN-gcc AR=$IMG_TOOLCHAIN-ar FC="$IMG_TOOLCHAIN-gfortran -EL -mabi=n32" RANLIB=$IMG_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS=$CFLAGS LDFLAGS=$CFLAGS TARGET=P6600
+# P6600 Build (n64):
+make BINARY=64 BINARY64=1 CC=$IMG_TOOLCHAIN-gcc AR=$IMG_TOOLCHAIN-ar FC="$IMG_TOOLCHAIN-gfortran -EL" RANLIB=$IMG_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS="$CFLAGS" LDFLAGS="$CFLAGS" TARGET=P6600
- P6600 Build (n64):
- make BINARY=64 BINARY64=1 CC=$IMG_TOOLCHAIN-gcc AR=$IMG_TOOLCHAIN-ar FC="$IMG_TOOLCHAIN-gfortran -EL" RANLIB=$IMG_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS="$CFLAGS" LDFLAGS="$CFLAGS" TARGET=P6600
+MTI_TOOLCHAIN_DIR={full MTI GNU/Linux Toolchain path including "bin" directory -- for example, /opt/linux_toolchain/bin}
+MTI_GCC_PREFIX=mips-mti-linux-gnu
+MTI_TOOLCHAIN=${IMG_TOOLCHAIN_DIR}/${IMG_GCC_PREFIX}
- MTI_TOOLCHAIN_DIR={full MTI GNU/Linux Toolchain path including "bin" directory -- for example, /opt/linux_toolchain/bin}
- MTI_GCC_PREFIX=mips-mti-linux-gnu
- MTI_TOOLCHAIN=${IMG_TOOLCHAIN_DIR}/${IMG_GCC_PREFIX}
+# P5600 Build:
- P5600 Build:
+make BINARY=32 BINARY32=1 CC=$MTI_TOOLCHAIN-gcc AR=$MTI_TOOLCHAIN-ar FC="$MTI_TOOLCHAIN-gfortran -EL" RANLIB=$MTI_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS=$CFLAGS LDFLAGS=$CFLAGS TARGET=P5600
+```
- make BINARY=32 BINARY32=1 CC=$MTI_TOOLCHAIN-gcc AR=$MTI_TOOLCHAIN-ar FC="$MTI_TOOLCHAIN-gfortran -EL" RANLIB=$MTI_TOOLCHAIN-ranlib HOSTCC=gcc CFLAGS="-EL" FFLAGS=$CFLAGS LDFLAGS=$CFLAGS TARGET=P5600
### FreeBSD
You will need to install the following tools from the FreeBSD ports tree:
-* lang/gcc [1]
+
+* lang/gcc
* lang/perl5.12
* ftp/curl
* devel/gmake
* devel/patch
To compile run the command:
-
- $ gmake CC=gcc46 FC=gfortran46
-
-Note that you need to build with GNU make and manually specify the compiler, otherwhise gcc 4.2 from the base system would be used.
-
-[1]: [Removal of Fortran from the FreeBSD base system](http://www.bsdunix.ch/serendipity/index.php?/archives/345-Removal-of-Fortran-from-the-FreeBSD-base-system.html)
-
-
-```
-pkg install openblas
+```bash
+$ gmake CC=gcc FC=gfortran
```
-see
### Cortex-M
-Cortex-M is a widely used microcontroller that is present in a variety of industrial and consumer electronics.
-A common variant of the Cortex-M is the STM32F4xx series. Here, we will give instructions for building for
-the STM32F4xx.
+Cortex-M is a widely used microcontroller that is present in a variety of
+industrial and consumer electronics. A common variant of the Cortex-M is the
+`STM32F4xx` series. Here, we will give instructions for building for that
+series.
-First, install the embedded arm gcc compiler from the arm website. Then, create the following toolchain file and build as follows.
+First, install the embedded Arm GCC compiler from the Arm website. Then, create
+the following `toolchain.cmake` file:
```cmake
-# cmake .. -G Ninja -DCMAKE_C_COMPILER=arm-none-eabi-gcc -DCMAKE_TOOLCHAIN_FILE:PATH="toolchain.cmake" -DNOFORTRAN=1 -DTARGET=ARMV5 -DEMBEDDED=1
-
set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR arm)
@@ -686,14 +758,20 @@ set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
```
-In your embedded application, the following functions need to be provided for OpenBLAS to work correctly:
+Then build OpenBLAS with:
+```bash
+$ cmake .. -G Ninja -DCMAKE_C_COMPILER=arm-none-eabi-gcc -DCMAKE_TOOLCHAIN_FILE:PATH="toolchain.cmake" -DNOFORTRAN=1 -DTARGET=ARMV5 -DEMBEDDED=1
+```
+In your embedded application, the following functions need to be provided for OpenBLAS to work correctly:
```C
void free(void* ptr);
void* malloc(size_t size);
```
!!! note
- If you are developing for an embedded platform, it is your responsibility to make sure that the device has sufficient memory for malloc calls. [Libmemory][2] provides one implementation of malloc for embedded platforms.
-[2]: https://github.com/embeddedartistry/libmemory
+ If you are developing for an embedded platform, it is your responsibility
+ to make sure that the device has sufficient memory for `malloc` calls.
+ [Libmemory](https://github.com/embeddedartistry/libmemory)
+ provides one implementation of `malloc` for embedded platforms.
diff --git a/docs/user_manual.md b/docs/user_manual.md
index 4d5fa9eaa..7abdcf0b8 100644
--- a/docs/user_manual.md
+++ b/docs/user_manual.md
@@ -1,70 +1,174 @@
-## Compile the library
+
+This user manual covers compiling OpenBLAS itself, linking your code to OpenBLAS,
+example code to use the C (CBLAS) and Fortran (BLAS) APIs, and some troubleshooting
+tips. Compiling OpenBLAS is optional, since you may be able to install with a
+package manager.
+
+!!! Note BLAS API reference documentation
+
+ The OpenBLAS documentation does not contain API reference documentation for
+ BLAS or LAPACK, since these are standardized APIs, the documentation for
+ which can be found in other places. If you want to understand every BLAS
+ and LAPACK function and definition, we recommend reading the
+ [Netlib BLAS ](http://netlib.org/blas/) and [Netlib LAPACK](http://netlib.org/lapack/)
+ documentation.
+
+ OpenBLAS does contain a limited number of functions that are non-standard,
+ these are documented at [OpenBLAS extension functions](extensions.md).
+
+
+## Compiling OpenBLAS
+
### Normal compile
- * type `make` to detect the CPU automatically.
- or
- * type `make TARGET=xxx` to set target CPU, e.g. `make TARGET=NEHALEM`. The full target list is in file TargetList.txt.
+
+The default way to build and install OpenBLAS from source is with Make:
+```
+make # add `-j4` to compile in parallel with 4 processes
+make install
+```
+
+By default, the CPU architecture is detected automatically when invoking
+`make`, and the build is optimized for the detected CPU. To override the
+autodetection, use the `TARGET` flag:
+
+```
+# `make TARGET=xxx` sets target CPU: e.g. for an Intel Nehalem CPU:
+make TARGET=NEHALEM
+```
+The full list of known target CPU architectures can be found in
+`TargetList.txt` in the root of the repository.
### Cross compile
-Please set `CC` and `FC` with the cross toolchains. Then, set `HOSTCC` with your host C compiler. At last, set `TARGET` explicitly.
-Examples:
+For a basic cross-compilation with Make, three steps need to be taken:
-* On x86 box, compile the library for ARM Cortex-A9 linux.
+- Set the `CC` and `FC` environment variables to select the cross toolchains
+ for C and Fortran.
+- Set the `HOSTCC` environment variable to select the host C compiler (i.e. the
+ regular C compiler for the machine on which you are invoking the build).
+- Set `TARGET` explicitly to the CPU architecture on which the produced
+ OpenBLAS binaries will be used.
-Install only gnueabihf versions. Please check https://github.com/xianyi/OpenBLAS/issues/936#issuecomment-237596847
+#### Cross-compilation examples
- make CC=arm-linux-gnueabihf-gcc FC=arm-linux-gnueabihf-gfortran HOSTCC=gcc TARGET=CORTEXA9
-
-* On X86 box, compile this library for loongson3a CPU.
+Compile the library for ARM Cortex-A9 linux on an x86-64 machine
+_(note: install only `gnueabihf` versions of the cross toolchain - see
+[this issue comment](https://github.com/OpenMathLib/OpenBLAS/issues/936#issuecomment-237596847)
+for why_):
+```
+make CC=arm-linux-gnueabihf-gcc FC=arm-linux-gnueabihf-gfortran HOSTCC=gcc TARGET=CORTEXA9
+```
+Compile OpenBLAS for a loongson3a CPU on an x86-64 machine:
```
make BINARY=64 CC=mips64el-unknown-linux-gnu-gcc FC=mips64el-unknown-linux-gnu-gfortran HOSTCC=gcc TARGET=LOONGSON3A
```
-* On X86 box, compile this library for loongson3a CPU with loongcc (based on Open64) compiler.
-
+Compile OpenBLAS for loongson3a CPU with the `loongcc` (based on Open64) compiler on an x86-64 machine:
```
make CC=loongcc FC=loongf95 HOSTCC=gcc TARGET=LOONGSON3A CROSS=1 CROSS_SUFFIX=mips64el-st-linux-gnu- NO_LAPACKE=1 NO_SHARED=1 BINARY=32
```
-### Debug version
+### Building a debug version
- make DEBUG=1
+Add `DEBUG=1` to your build command, e.g.:
+```
+make DEBUG=1
+```
-### Install to the directory (optional)
+### Install to a specific directory
-Example:
+!!! note
- make install PREFIX=your_installation_directory
+ Installing to a directory is optional; it is also possible to use the shared or static
+ libraries directly from the build directory.
-The default directory is /opt/OpenBLAS. Note that any flags passed to `make` during build should also be passed to `make install` to circumvent any install errors, i.e. some headers not being copied over correctly.
+Use `make install` with the `PREFIX` flag to install to a specific directory:
-For more information, please read [Installation Guide](install.md).
+```
+make install PREFIX=/path/to/installation/directory
+```
-## Link the library
+The default directory is `/opt/OpenBLAS`.
-* Link shared library
+!!! important
+ Note that any flags passed to `make` during build should also be passed to
+ `make install` to circumvent any install errors, i.e. some headers not
+ being copied over correctly.
+
+For more detailed information on building/installing from source, please read
+the [Installation Guide](install.md).
+
+
+## Linking to OpenBLAS
+
+OpenBLAS can be used as a shared or a static library.
+
+### Link a shared library
+
+The shared library is normally called `libopenblas.so`, but not that the name
+may be different as a result of build flags used or naming choices by a distro
+packager (see [distributing.md] for details). To link a shared library named
+`libopenblas.so`, the flag `-lopenblas` is needed. To find the OpenBLAS headers,
+a `-I/path/to/includedir` is needed. And unless the library is installed in a
+directory that the linker searches by default, also `-L` and `-Wl,-rpath` flags
+are needed. For a source file `test.c` (e.g., the example code under _Call
+CBLAS interface_ further down), the shared library can then be linked with:
```
gcc -o test test.c -I/your_path/OpenBLAS/include/ -L/your_path/OpenBLAS/lib -Wl,-rpath,/your_path/OpenBLAS/lib -lopenblas
```
-The `-Wl,-rpath,/your_path/OpenBLAS/lib` option to linker can be omitted if you ran `ldconfig` to update linker cache, put `/your_path/OpenBLAS/lib` in `/etc/ld.so.conf` or a file in `/etc/ld.so.conf.d`, or installed OpenBLAS in a location that is part of the `ld.so` default search path (usually /lib,/usr/lib and /usr/local/lib). Alternatively, you can set the environment variable LD_LIBRARY_PATH to point to the folder that contains libopenblas.so. Otherwise, linking at runtime will fail with a message like `cannot open shared object file: no such file or directory`
+The `-Wl,-rpath,/your_path/OpenBLAS/lib` linker flag can be omitted if you
+ran `ldconfig` to update linker cache, put `/your_path/OpenBLAS/lib` in
+`/etc/ld.so.conf` or a file in `/etc/ld.so.conf.d`, or installed OpenBLAS in a
+location that is part of the `ld.so` default search path (usually `/lib`,
+`/usr/lib` and `/usr/local/lib`). Alternatively, you can set the environment
+variable `LD_LIBRARY_PATH` to point to the folder that contains `libopenblas.so`.
+Otherwise, the build may succeed but at runtime loading the library will fail
+with a message like:
+```
+cannot open shared object file: no such file or directory
+```
-If the library is multithreaded, please add `-lpthread`. If the library contains LAPACK functions, please add `-lgfortran` or other Fortran libs, although if you only make calls to LAPACKE routines, i.e. your code has `#include "lapacke.h"` and makes calls to methods like `LAPACKE_dgeqrf`, `-lgfortran` is not needed.
+More flags may be needed, depending on how OpenBLAS was built:
-* Link static library
+- If `libopenblas` is multi-threaded, please add `-lpthread`.
+- If the library contains LAPACK functions (usually also true), please add
+ `-lgfortran` (other Fortran libraries may also be needed, e.g. `-lquadmath`).
+ Note that if you only make calls to LAPACKE routines, i.e. your code has
+ `#include "lapacke.h"` and makes calls to methods like `LAPACKE_dgeqrf`,
+ then `-lgfortran` is not needed.
+!!! tip Use pkg-config
+
+ Usually a pkg-config file (e.g., `openblas.pc`) is installed together
+ with a `libopenblas` shared library. pkg-config is a tool that will
+ tell you the exact flags needed for linking. For example:
+
+ ```
+ $ pkg-config --cflags openblas
+ -I/usr/local/include
+ $ pkg-config --libs openblas
+ -L/usr/local/lib -lopenblas
+ ```
+
+### Link a static library
+
+Linking a static library is simpler - add the path to the static OpenBLAS
+library to the compile command:
```
gcc -o test test.c /your/path/libopenblas.a
```
-You can download `test.c` from https://gist.github.com/xianyi/5780018
## Code examples
### Call CBLAS interface
-This example shows calling cblas_dgemm in C. https://gist.github.com/xianyi/6930656
+
+This example shows calling `cblas_dgemm` in C:
+
+
```c
#include
#include
@@ -83,14 +187,17 @@ void main()
}
```
+To compile this file, save it as `test_cblas_dgemm.c` and then run:
```
-gcc -o test_cblas_open test_cblas_dgemm.c -I /your_path/OpenBLAS/include/ -L/your_path/OpenBLAS/lib -lopenblas -lpthread -lgfortran
+gcc -o test_cblas_open test_cblas_dgemm.c -I/your_path/OpenBLAS/include/ -L/your_path/OpenBLAS/lib -lopenblas -lpthread -lgfortran
```
+will result in a `test_cblas_open` executable.
### Call BLAS Fortran interface
-This example shows calling dgemm Fortran interface in C. https://gist.github.com/xianyi/5780018
+This example shows calling the `dgemm` Fortran interface in C:
+
```c
#include "stdio.h"
#include "stdlib.h"
@@ -158,22 +265,41 @@ int main(int argc, char* argv[])
}
```
+To compile this file, save it as `time_dgemm.c` and then run:
```
gcc -o time_dgemm time_dgemm.c /your/path/libopenblas.a -lpthread
-./time_dgemm
```
+You can then run it as: `./time_dgemm `, with `m`, `n`, and `k` input
+parameters to the `time_dgemm` executable.
+
+!!! note
+
+ When calling the Fortran interface from C, you have to deal with symbol name
+ differences caused by compiler conventions. That is why the `dgemm_` function
+ call in the example above has a trailing underscore. This is what it looks like
+ when using `gcc`/`gfortran`, however such details may change for different
+ compilers. Hence it requires extra support code. The CBLAS interface may be
+ more portable when writing C code.
+
+ When writing code that needs to be portable and work across different
+ platforms and compilers, the above code example is not recommended for
+ usage. Instead, we advise looking at how OpenBLAS (or BLAS in general, since
+ this problem isn't specific to OpenBLAS) functions are called in widely
+ used projects like Julia, SciPy, or R.
+
## Troubleshooting
-* Please read [Faq](faq.md) at first.
-* Please use gcc version 4.6 and above to compile Sandy Bridge AVX kernels on Linux/MingW/BSD.
-* Please use Clang version 3.1 and above to compile the library on Sandy Bridge microarchitecture. The Clang 3.0 will generate the wrong AVX binary code.
-* The number of CPUs/Cores should less than or equal to 256. On Linux x86_64(amd64), there is experimental support for up to 1024 CPUs/Cores and 128 numa nodes if you build the library with BIGNUMA=1.
-* OpenBLAS does not set processor affinity by default. On Linux, you can enable processor affinity by commenting the line NO_AFFINITY=1 in Makefile.rule. But this may cause [the conflict with R parallel](https://stat.ethz.ch/pipermail/r-sig-hpc/2012-April/001348.html).
-* On Loongson 3A. make test would be failed because of pthread_create error. The error code is EAGAIN. However, it will be OK when you run the same testcase on shell.
-
-## BLAS reference manual
-
-If you want to understand every BLAS function and definition, please read [Intel MKL reference manual](https://software.intel.com/en-us/intel-mkl/documentation) or [netlib.org](http://netlib.org/blas/)
-
-Here are [OpenBLAS extension functions](extensions.md)
+* Please read the [FAQ](faq.md) first, your problem may be described there.
+* Please ensure you are using a recent enough compiler, that supports the
+ features your CPU provides (example: GCC versions before 4.6 were known to
+ not support AVX kernels, and before 6.1 AVX512CD kernels).
+* The number of CPU cores supported by default is <=256. On Linux x86-64, there
+ is experimental support for up to 1024 cores and 128 NUMA nodes if you build
+ the library with `BIGNUMA=1`.
+* OpenBLAS does not set processor affinity by default. On Linux, you can enable
+ processor affinity by commenting out the line `NO_AFFINITY=1` in
+ `Makefile.rule`.
+* On Loongson 3A, `make test` is known to fail with a `pthread_create` error
+ and an `EAGAIN` error code. However, it will be OK when you run the same
+ testcase in a shell.
diff --git a/mkdocs.yml b/mkdocs.yml
index 74a18a5bb..374b03e39 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,17 +1,44 @@
site_name: OpenBLAS
site_url: https://openblas.net/docs/
+repo_url: https://github.com/OpenMathLib/OpenBLAS
+copyright: Copyright © 2012- OpenBLAS contributors
+
theme:
name: material
logo: logo.svg
favicon: logo.svg
+ features:
+ - header.autohide
palette:
- primary: grey
+ # Palette toggle for dark mode
+ - scheme: slate
+ primary: blue grey
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+
+ # Palette toggle for light mode
+ - scheme: default
+ primary: blue grey
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+
+plugins:
+ - search
+ - git-revision-date-localized:
+ enable_creation_date: true
+
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
+ - footnotes
+ - pymdownx.tabbed:
+ alternate_style: true
- toc:
toc_depth: 4
+
nav:
- index.md
- install.md
@@ -23,3 +50,10 @@ nav:
- ci.md
- about.md
- faq.md
+
+extra:
+ social:
+ - icon: fontawesome/brands/github
+ link: https://github.com/OpenMathLib/OpenBLAS
+ - icon: material/license
+ link: https://github.com/OpenMathLib/OpenBLAS/LICENSE
diff --git a/param.h b/param.h
index 2ebe824db..2618e1f60 100644
--- a/param.h
+++ b/param.h
@@ -2553,7 +2553,7 @@ USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#endif
-#if defined(POWER9) && defined(OS_LINUX)
+#if defined(POWER9) && (defined(OS_LINUX) || defined(OS_FREEBSD))
#define SNUMOPT 16
#define DNUMOPT 8