Skip to content

Commit 4547908

Browse files
rgommersrgommers
committed
docs: rewrite "Install OpenBLAS" page (part 1: binaries, basic from source)
1 parent f729013 commit 4547908

File tree

1 file changed

+179
-113
lines changed

1 file changed

+179
-113
lines changed

‎docs/install.md

Lines changed: 179 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,203 @@
11
# Install OpenBLAS
22

3+
OpenBLAS can be installed through package managers or from source. If you only
4+
want to use OpenBLAS rather than make changes to it, we recommend installing a
5+
pre-built binary package with your package manager of choice.
6+
7+
This page contains an overview of installing with package managers as well as
8+
from source. For the latter, see [further down on this page](#building-from-source).
9+
10+
11+
## Installing with a package manager
12+
313
!!! note
4-
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
14+
Almost every package manager provides OpenBLAS packages; the list on this
15+
page is not comprehensive. If your package manager of choice isn't shown
16+
here, please search its package database for `openblas` or `libopenblas`.
517

618

7-
## Quick install
19+
### Linux
820

9-
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.
21+
On Linux, OpenBLAS can be installed with the system package manager, or with a
22+
package manager like [Conda](https://docs.conda.io/en/latest/)
23+
(or alternative package managers for the conda-forge ecosystem, like
24+
[Mamba](https://mamba.readthedocs.io/en/latest/),
25+
[Micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html),
26+
or [Pixi](https://pixi.sh/latest/#windows-installer)),
27+
[Spack](https://spack.io/), or [Nix](https://nixos.org/). For the latter set of
28+
tools, the package name in all cases is `openblas`. Since package management in
29+
quite a few of these tools is declarative (i.e., managed by adding `openblas`
30+
to a metadata file describing the dependencies for your project or
31+
environment), we won't attempt to give detailed instructions for these tools here.
1032

11-
The [Conda-Forge](https://github.com/conda-forge) project maintains packages for the conda package manager at <https://github.com/conda-forge/openblas-feedstock>.
33+
Linux distributions typically split OpenBLAS up in two packages: one containing
34+
the library itself (typically named `openblas` or `libopenblas`), and one containing headers,
35+
pkg-config and CMake files (typically named the same as the package for the
36+
library with `-dev` or `-devel` appended; e.g., `openblas-devel`). Please keep
37+
in mind that if you want to install OpenBLAS in order to use it directly in
38+
your own project, you will need to install both of those packages.
1239

13-
## Source
14-
Download the latest [stable version](https://github.com/xianyi/OpenBLAS/releases) from release page.
40+
Distro-specific installation commands:
1541

16-
## Platforms
42+
=== "Debian/Ubuntu/Mint/Kali"
1743

18-
### Linux
44+
```bash
45+
$ sudo apt update
46+
$ sudo apt install libopenblas-dev
47+
```
48+
OpenBLAS can be configured as the default BLAS through the `update-alternatives` mechanism:
1949

20-
Just type `make` to compile the library.
50+
```bash
51+
$ sudo update-alternatives --config libblas.so.3
52+
```
2153

22-
Notes:
54+
=== "openSUSE/SLE"
2355

24-
* OpenBLAS doesn't support g77. Please use gfortran or other Fortran compilers. e.g. `make FC=gfortran`.
25-
* When building in an emulator (KVM,QEMU etc.) make sure that the combination of CPU features exposed to
26-
the virtual environment matches that of an existing CPU to allow detection of the cpu model to succeed.
27-
(With qemu, this can be done by passing `-cpu host` or a supported model name at invocation)
56+
```bash
57+
$ sudo zypper refresh
58+
$ sudo zypper install openblas-devel
59+
```
2860

61+
OpenBLAS can be configured as the default BLAS through the `update-alternatives` mechanism:
62+
```bash
63+
$ sudo update-alternatives --config libblas.so.3
64+
```
2965

30-
#### Precompiled packages
66+
=== "Fedora/CentOS/RHEL"
3167

32-
##### Debian/Ubuntu/Mint/Kali
33-
OpenBLAS package is available in default repositories and can act as default BLAS in system
68+
```bash
69+
$ dnf check-update
70+
$ dnf install openblas-devel
71+
```
3472

35-
Example installation commands:
36-
```bash
37-
$ sudo apt update
38-
$ apt search openblas
39-
$ sudo apt install libopenblas-dev
40-
$ sudo update-alternatives --config libblas.so.3
41-
```
42-
Alternatively, if distributor's package proves unsatisfactory, you may try latest version of OpenBLAS, [Following guide in OpenBLAS FAQ](faq.md#debianlts)
43-
44-
##### openSuSE/SLE
45-
Recent OpenSUSE versions include OpenBLAS in default repositories and also permit OpenBLAS to act as replacement of system-wide BLAS.
73+
!!! warning
4674

47-
Example installation commands:
48-
```bash
49-
$ sudo zypper ref
50-
$ zypper se openblas
51-
$ sudo zypper in openblas-devel
52-
$ sudo update-alternatives --config libblas.so.3
53-
```
54-
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)
75+
Fedora does not ship the pkg-config files for OpenBLAS. Instead, it wants you to
76+
link against [FlexiBLAS](https://www.mpi-magdeburg.mpg.de/projects/flexiblas) (which
77+
uses OpenBLAS by default as its backend on Fedora), which you can install with:
5578

56-
##### Fedora/CentOS/RHEL
57-
Fedora provides OpenBLAS in default installation repositories.
79+
```bash
80+
$ dnf install flexiblas-devel
81+
```
5882

59-
To install it try following:
60-
```bash
61-
$ dnf search openblas
62-
$ dnf install openblas-devel
63-
```
64-
For CentOS/RHEL/Scientific Linux packages are provided via [Fedora EPEL repository](https://fedoraproject.org/wiki/EPEL)
83+
For CentOS and RHEL, OpenBLAS packages are provided via the [Fedora EPEL repository](https://fedoraproject.org/wiki/EPEL).
84+
After adding that repository and its repository keys, you can install
85+
`openblas-devel` with either `dnf` or `yum`.
6586

66-
After adding repository and repository keys installation is pretty straightforward:
67-
```bash
68-
$ yum search openblas
69-
$ yum install openblas-devel
70-
```
71-
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)
87+
=== "Arch/Manjaro/Antergos"
7288

73-
##### Mageia
74-
Mageia offers ATLAS and NetLIB LAPACK in base repositories.
75-
You can build your own OpenBLAS replacement, and once installed in /opt
76-
TODO: populate /usr/lib64 /usr/include accurately to replicate netlib with update-alternatives
89+
```bash
90+
$ sudo pacman -S openblas
91+
```
7792

78-
##### Arch/Manjaro/Antergos
79-
```bash
80-
$ sudo pacman -S openblas
81-
```
8293

8394
### Windows
8495

85-
The precompiled binaries available with each release (in <https://github.com/xianyi/OpenBLAS/releases>) are
86-
created with MinGW using an option list of
87-
"NUM_THREADS=64 TARGET=GENERIC DYNAMIC_ARCH=1 DYNAMIC_OLDER=1 CONSISTENT_FPCSR=1" - they should work on
88-
any x86 or x86_64 computer. The zip archive contains the include files, static and dll libraries as well
89-
as configuration files for getting them found via CMAKE or pkgconfig - just create a suitable folder for
90-
your OpenBLAS installation and unzip it there. (Note that you will need to edit the provided openblas.pc
91-
and OpenBLASConfig.cmake to reflect the installation path on your computer, as distributed they have "win"
92-
or "win64" reflecting the local paths on the system they were built on). Some programs will expect the DLL
93-
name to be lapack.dll, blas.dll, or (in the case of the statistics package "R") even Rblas.dll to act as a
94-
direct replacement for whatever other implementation of BLAS and LAPACK they use by default. Just copy the
95-
openblas.dll to the desired name(s).
96-
Note that the provided binaries are built with INTERFACE64=0, meaning they use standard 32bit integers for
97-
array indexing and the like (as is the default for most if not all BLAS and LAPACK implementations). If the
98-
documentation of whatever program you are using with OpenBLAS mentions 64bit integers (INTERFACE64=1) for
99-
addressing huge matrix sizes, you will need to build OpenBLAS from source (or open an issue ticket to make
100-
the demand for such a precompiled build known).
101-
102-
#### Precompiled packages
103-
104-
* <http://sourceforge.net/projects/openblas/files>
105-
* <https://www.nuget.org/packages?q=openblas>
96+
=== "Conda-forge"
97+
98+
OpenBLAS can be installed with `conda` (or `mamba`, `micromamba`, or
99+
`pixi`) from conda-forge:
100+
```
101+
conda install openblas
102+
```
103+
104+
Conda-forge provides a method for switching the default BLAS implementation
105+
used by all packages. To use that for OpenBLAS, install `libblas=*=*openblas`
106+
(see [the docs on this mechanism](https://conda-forge.org/docs/maintainer/knowledge_base/#switching-blas-implementation)
107+
for more details).
108+
109+
=== "vcpkg"
110+
111+
OpenBLAS can be installed with vcpkg:
112+
```cmd
113+
# In classic mode:
114+
vcpkg install openblas
115+
116+
# Or in manifest mode:
117+
vcpkg add port openblas
118+
```
119+
120+
=== "OpenBLAS releases"
121+
122+
Windows is the only platform for which binaries are made available by the
123+
OpenBLAS project itself. They can be downloaded from the GitHub
124+
Releases](https://github.com/OpenMathLib/OpenBLAS/releases) page. These
125+
binaries are built with MinGW, using the following build options:
126+
```
127+
NUM_THREADS=64 TARGET=GENERIC DYNAMIC_ARCH=1 DYNAMIC_OLDER=1 CONSISTENT_FPCSR=1 INTERFACE=0
128+
```
129+
There are separate packages for x86-64 and x86. The zip archive contains
130+
the include files, static and shared libraries, as well as configuration
131+
files for getting them found via CMake or pkg-config. To use these
132+
binaries, create a suitable folder for your OpenBLAS installation and unzip
133+
the `.zip` bundle there (note that you will need to edit the provided
134+
`openblas.pc` and `OpenBLASConfig.cmake` to reflect the installation path
135+
on your computer, as distributed they have "win" or "win64" reflecting the
136+
local paths on the system they were built on).
137+
138+
Note that the same binaries can be downloaded
139+
[from SourceForge](http://sourceforge.net/projects/openblas/files); this is
140+
mostly of historical interest.
141+
142+
143+
### macOS
144+
145+
To install OpenBLAS with a package manager on macOS, run:
146+
147+
=== "Homebrew"
148+
149+
```zsh
150+
% brew install openblas
151+
```
152+
153+
=== "MacPorts"
154+
155+
```zsh
156+
% sudo port install OpenBLAS-devel
157+
```
158+
159+
=== "Conda-forge"
160+
161+
```zsh
162+
% conda install openblas
163+
```
164+
165+
Conda-forge provides a method for switching the default BLAS implementation
166+
used by all packages. To use that for OpenBLAS, install `libblas=*=*openblas`
167+
(see [the docs on this mechanism](https://conda-forge.org/docs/maintainer/knowledge_base/#switching-blas-implementation)
168+
for more details).
169+
170+
171+
## Building from source
172+
173+
We recommend download the latest [stable version](https://github.com/OpenMathLib/OpenBLAS/releases)
174+
from the GitHub Releases page, or checking it out from a git tag, rather than a
175+
dev version from the `develop` branch.
176+
177+
!!! tip
178+
179+
The User manual contains [a section with detailed information on compiling OpenBLAS](user_manual.md#compiling-openblas),
180+
including how to customize builds and how to cross-compile. Please read
181+
that documentation first. This page contains only platform-specific build
182+
information, and assumes you already understand the general build system
183+
invocations to build OpenBLAS, with the specific build options you want to
184+
control multi-threading and other non-platform-specific behavior).
185+
186+
187+
### Linux and macOS
188+
189+
Ensure you have C and Fortran compilers installed, then simply type `make` to compile the library.
190+
There are no other build dependencies, nor unusual platform-specific
191+
environment variables to set or other system setup to do.
192+
193+
!!! note
194+
195+
When building in an emulator (KVM, QEMU, etc.), please make sure that the combination of CPU features exposed to
196+
the virtual environment matches that of an existing CPU to allow detection of the CPU model to succeed.
197+
(With `qemu`, this can be done by passing `-cpu host` or a supported model name at invocation).
198+
199+
200+
### Windows
106201

107202
#### Visual Studio
108203

@@ -181,7 +276,7 @@ In newer visual studio versions, Microsoft has changed [how it handles complex t
181276
#endif
182277
```
183278

184-
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.
279+
For reference, see https://github.com/OpenMathLib/OpenBLAS/issues/3661, https://github.com/Reference-LAPACK/lapack/issues/683, and https://stackoverflow.com/questions/47520244/using-openblas-lapacke-in-visual-studio.
185280

186281
###### CMake and Visual Studio
187282

@@ -208,7 +303,7 @@ Step 2 will build the OpenBLAS solution, open it in VS, and build the projects.
208303

209304
###### Build OpenBLAS for Universal Windows Platform
210305

211-
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).
306+
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/OpenMathLib/OpenBLAS/commit/c66b842d66c5516e52804bf5a0544d18b1da1b44).
212307

213308
####### 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.
214309

@@ -246,7 +341,7 @@ Note also that older versions of the alternative builds of mingw-w64 available t
246341
```
247342
<command-line>:0:4: error: expected identifier or '(' before numeric constant
248343
```
249-
If you encounter this, please upgrade your msys2 setup or see https://github.com/xianyi/OpenBLAS/issues/1503 for a workaround.
344+
If you encounter this, please upgrade your msys2 setup or see https://github.com/OpenMathLib/OpenBLAS/issues/1503 for a workaround.
250345

251346
###### Generate import library (before 0.2.10 version)
252347

@@ -266,7 +361,7 @@ Tool to do so is available at https://github.com/rainers/cv2pdb
266361
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.
267362

268363
!!! note
269-
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).
364+
If you need CBLAS, you should include cblas.h in /your/installation/path/include in Visual Studio. Please read [this page](http://github.com/OpenMathLib/OpenBLAS/issues/95).
270365

271366
###### Limitations
272367
* 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.
@@ -365,35 +460,6 @@ The import libraries of MSVC have the suffix `.lib`. They are generated from a `
365460

366461
* 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.
367462

368-
### Mac OSX
369-
370-
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.
371-
372-
#### Precompiled packages
373-
374-
<https://www.macports.org/ports.php?by=name&substr=openblas>
375-
376-
`brew install openblas`
377-
378-
or using the conda package manager from
379-
<https://github.com/conda-forge/miniforge#download>
380-
(which also has packages for the new M1 cpu)
381-
382-
`conda install openblas`
383-
384-
#### Build on Apple M1
385-
386-
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)).
387-
388-
* without Fortran compiler （cannot build LAPACK)
389-
```bash
390-
$ make CC=cc NOFORTRAN=1
391-
```
392-
* with Fortran compiler (you could `brew install gfortran`) https://github.com/xianyi/OpenBLAS/issues/3032
393-
```bash
394-
$ export MACOSX_DEPLOYMENT_TARGET=11.0
395-
$ make CC=cc FC=gfortran
396-
```
397463

398464
### Android
399465

@@ -508,7 +574,7 @@ make \
508574
-j4
509575
sudo make install
510576
```
511-
Also you can find full list of target architectures in [TargetsList.txt](https://github.com/xianyi/OpenBLAS/blob/develop/TargetList.txt)
577+
Also you can find full list of target architectures in [TargetList.txt](https://github.com/OpenMathLib/OpenBLAS/blob/develop/TargetList.txt)
512578

513579
***
514580
anything below this line should be irrelevant nowadays unless you need to perform software archeology

0 commit comments

Comments
 (0)