floraachy
/
OpenBLAS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
OpenBLAS/docs/distributing/index.html

947 lines
33 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link rel="canonical" href="https://openblas.net/docs/distributing/">
<link rel="prev" href="../build_system/">
<link rel="next" href="../ci/">
<link rel="icon" href="../logo.svg">
<meta name="generator" content="mkdocs-1.6.0, mkdocs-material-9.5.23">
<title>Redistributing OpenBLAS - OpenBLAS</title>
<link rel="stylesheet" href="../assets/stylesheets/main.6543a935.min.css">
<link rel="stylesheet" href="../assets/stylesheets/palette.06af60db.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="grey" data-md-color-accent="indigo">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#redistributing-openblas" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href=".." title="OpenBLAS" class="md-header__button md-logo" aria-label="OpenBLAS" data-md-component="logo">
<img src="../logo.svg" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
OpenBLAS
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Redistributing OpenBLAS
</span>
</div>
</div>
</div>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg>
</button>
</nav>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href=".." title="OpenBLAS" class="md-nav__button md-logo" aria-label="OpenBLAS" data-md-component="logo">
<img src="../logo.svg" alt="logo">
</a>
OpenBLAS
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href=".." class="md-nav__link">
<span class="md-ellipsis">
Home
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../install/" class="md-nav__link">
<span class="md-ellipsis">
Install OpenBLAS
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../user_manual/" class="md-nav__link">
<span class="md-ellipsis">
User manual
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../extensions/" class="md-nav__link">
<span class="md-ellipsis">
Extensions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../developers/" class="md-nav__link">
<span class="md-ellipsis">
Developer manual
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../build_system/" class="md-nav__link">
<span class="md-ellipsis">
Build system
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Redistributing OpenBLAS
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Redistributing OpenBLAS
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#ilp64-interface-builds" class="md-nav__link">
<span class="md-ellipsis">
ILP64 interface builds
</span>
</a>
<nav class="md-nav" aria-label="ILP64 interface builds">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#the-current-openblas-agreed-upon-ilp64-convention" class="md-nav__link">
<span class="md-ellipsis">
The current OpenBLAS agreed-upon ILP64 convention
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#the-upcoming-standardized-ilp64-convention" class="md-nav__link">
<span class="md-ellipsis">
The upcoming standardized ILP64 convention
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#performance-and-runtime-behavior-related-build-options" class="md-nav__link">
<span class="md-ellipsis">
Performance and runtime behavior related build options
</span>
</a>
<nav class="md-nav" aria-label="Performance and runtime behavior related build options">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#threading-related-options" class="md-nav__link">
<span class="md-ellipsis">
Threading related options
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#cpu-architecture-related-options" class="md-nav__link">
<span class="md-ellipsis">
CPU architecture related options
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#real-world-examples" class="md-nav__link">
<span class="md-ellipsis">
Real-world examples
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../ci/" class="md-nav__link">
<span class="md-ellipsis">
CI jobs
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../about/" class="md-nav__link">
<span class="md-ellipsis">
About
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../faq/" class="md-nav__link">
<span class="md-ellipsis">
FAQ
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#ilp64-interface-builds" class="md-nav__link">
<span class="md-ellipsis">
ILP64 interface builds
</span>
</a>
<nav class="md-nav" aria-label="ILP64 interface builds">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#the-current-openblas-agreed-upon-ilp64-convention" class="md-nav__link">
<span class="md-ellipsis">
The current OpenBLAS agreed-upon ILP64 convention
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#the-upcoming-standardized-ilp64-convention" class="md-nav__link">
<span class="md-ellipsis">
The upcoming standardized ILP64 convention
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#performance-and-runtime-behavior-related-build-options" class="md-nav__link">
<span class="md-ellipsis">
Performance and runtime behavior related build options
</span>
</a>
<nav class="md-nav" aria-label="Performance and runtime behavior related build options">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#threading-related-options" class="md-nav__link">
<span class="md-ellipsis">
Threading related options
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#cpu-architecture-related-options" class="md-nav__link">
<span class="md-ellipsis">
CPU architecture related options
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#real-world-examples" class="md-nav__link">
<span class="md-ellipsis">
Real-world examples
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1 id="redistributing-openblas">Redistributing OpenBLAS</h1>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This document contains recommendations only - packagers and other
redistributors are in charge of how OpenBLAS is built and distributed in their
systems, and may have good reasons to deviate from the guidance given on this
page. These recommendations are aimed at general packaging systems, with a user
base that typically is large, open source (or freely available at least), and
doesn't behave uniformly or that the packager is directly connected with.*</p>
</div>
<p>OpenBLAS has a large number of build-time options which can be used to change
how it behaves at runtime, how artifacts or symbols are named, etc. Variation
in build configuration can be necessary to acheive a given end goal within a
distribution or as an end user. However, such variation can also make it more
difficult to build on top of OpenBLAS and ship code or other packages in a way
that works across many different distros. Here we provide guidance about the
most important build options, what effects they may have when changed, and
which ones to default to.</p>
<p>The Make and CMake build systems provide equivalent options and yield more or
less the same artifacts, but not exactly (the CMake builds are still
experimental). You can choose either one and the options will function in the
same way, however the CMake outputs may require some renaming. To review
available build options, see <code>Makefile.rule</code> or <code>CMakeLists.txt</code> in the root of
the repository.</p>
<p>Build options typically fall into two categories: (a) options that affect the
user interface, such as library and symbol names or APIs that are made
available, and (b) options that affect performance and runtime behavior, such
as threading behavior or CPU architecture-specific code paths. The user
interface options are more important to keep aligned between distributions,
while for the performance-related options there are typically more reasons to
make choices that deviate from the defaults.</p>
<p>Here are recommendations for user interface related packaging choices where it
is not likely to be a good idea to deviate (typically these are the default
settings):</p>
<ol>
<li>Include CBLAS. The CBLAS interface is widely used and it doesn't affect
binary size much, so don't turn it off.</li>
<li>Include LAPACK and LAPACKE. The LAPACK interface is also widely used, and
while it does make up a significant part of the binary size of the installed
library, that does not outweigh the regression in usability when deviating
from the default here.[^1]</li>
<li>Always distribute the pkg-config (<code>.pc</code>) and CMake <code>.cmake</code>) dependency
detection files. These files are used by build systems when users want to
link against OpenBLAS, and there is no benefit of leaving them out.</li>
<li>Provide the LP64 interface by default, and if in addition to that you choose
to provide an ILP64 interface build as well, use a symbol suffix to avoid
symbol name clashes (see the next section).</li>
</ol>
<p>[^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.</p>
<h2 id="ilp64-interface-builds">ILP64 interface builds</h2>
<p>The LP64 (32-bit integer) interface is the default build, and has
well-established C and Fortran APIs as determined by the reference (Netlib)
BLAS and LAPACK libraries. The ILP64 (64-bit integer) interface however does
not have a standard API: symbol names and shared/static library names can be
produced in multiple ways, and this tends to make it difficult to use.
As of today there is an agreed-upon way of choosing names for OpenBLAS between
a number of key users/redistributors, which is the closest thing to a standard
that there is now. However, there is an ongoing standardization effort in the
reference BLAS and LAPACK libraries, which differs from the current OpenBLAS
agreed-upon convention. In this section we'll aim to explain both.</p>
<p>Those two methods are fairly similar, and have a key thing in common: <em>using a
symbol suffix</em>. This is good practice; it is recommended that if you distribute
an ILP64 build, to have it use a symbol suffix containing <code>64</code> in the name.
This avoids potential symbol clashes when different packages which depend on
OpenBLAS load both an LP64 and an ILP64 library into memory at the same time.</p>
<h3 id="the-current-openblas-agreed-upon-ilp64-convention">The current OpenBLAS agreed-upon ILP64 convention</h3>
<p>This convention comprises the shared library name and the symbol suffix in the
shared library. The symbol suffix to use is <code>64_</code>, implying that the library
name will be <code>libopenblas64_.so</code> and the symbols in that library end in <code>64_</code>.
The central issue where this was discussed is
<a href="https://github.com/xianyi/OpenBLAS/issues/646">openblas#646</a>, and adopters
include Fedora, Julia, NumPy and SciPy - SuiteSparse already used it as well.</p>
<p>To build shared and static libraries with the currently recommended ILP64
conventions with Make:
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>make<span class="w"> </span><span class="nv">INTERFACE64</span><span class="o">=</span><span class="m">1</span><span class="w"> </span><span class="nv">SYMBOLSUFFIX</span><span class="o">=</span>64_
</code></pre></div></p>
<p>This will produce libraries named <code>libopenblas64_.so|a</code>, a pkg-config file
named <code>openblas64.pc</code>, and CMake and header files.</p>
<p>Installing locally and inspecting the output will show a few more details:
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>make<span class="w"> </span>install<span class="w"> </span><span class="nv">PREFIX</span><span class="o">=</span><span class="nv">$PWD</span>/../openblas/make64<span class="w"> </span><span class="nv">INTERFACE64</span><span class="o">=</span><span class="m">1</span><span class="w"> </span><span class="nv">SYMBOLSUFFIX</span><span class="o">=</span>64_
$<span class="w"> </span>tree<span class="w"> </span>.<span class="w"> </span><span class="c1"># output slightly edited down</span>
.
├──<span class="w"> </span>include
│<span class="w">   </span>├──<span class="w"> </span>cblas.h
│<span class="w">   </span>├──<span class="w"> </span>f77blas.h
│<span class="w">   </span>├──<span class="w"> </span>lapacke_config.h
│<span class="w">   </span>├──<span class="w"> </span>lapacke.h
│<span class="w">   </span>├──<span class="w"> </span>lapacke_mangling.h
│<span class="w">   </span>├──<span class="w"> </span>lapacke_utils.h
│<span class="w">   </span>├──<span class="w"> </span>lapack.h
│<span class="w">   </span>└──<span class="w"> </span>openblas_config.h
└──<span class="w"> </span>lib
<span class="w"> </span>├──<span class="w"> </span>cmake
<span class="w"> </span>│<span class="w">   </span>└──<span class="w"> </span>openblas
<span class="w"> </span>│<span class="w">   </span>├──<span class="w"> </span>OpenBLASConfig.cmake
<span class="w"> </span>│<span class="w">   </span>└──<span class="w"> </span>OpenBLASConfigVersion.cmake
<span class="w"> </span>├──<span class="w"> </span>libopenblas64_.a
<span class="w"> </span>├──<span class="w"> </span>libopenblas64_.so
<span class="w"> </span>└──<span class="w"> </span>pkgconfig
<span class="w"> </span>└──<span class="w"> </span>openblas64.pc
</code></pre></div></p>
<p>A key point are the symbol names. These will equal the LP64 symbol names, then
(for Fortran only) the compiler mangling, and then the <code>64_</code> symbol suffix.
Hence to obtain the final symbol names, we need to take into account which
Fortran compiler we are using. For the most common cases (e.g., gfortran, Intel
Fortran, or Flang), that means appending a single underscore. In that case, the
result is:</p>
<table>
<thead>
<tr>
<th>base API name</th>
<th>binary symbol name</th>
<th>call from Fortran code</th>
<th>call from C code</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>dgemm</code></td>
<td><code>dgemm_64_</code></td>
<td><code>dgemm_64(...)</code></td>
<td><code>dgemm_64_(...)</code></td>
</tr>
<tr>
<td><code>cblas_dgemm</code></td>
<td><code>cblas_dgemm64_</code></td>
<td>n/a</td>
<td><code>cblas_dgemm64_(...)</code></td>
</tr>
</tbody>
</table>
<p>It is quite useful to have these symbol names be as uniform as possible across
different packaging systems.</p>
<p>The equivalent build options with CMake are:
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>mkdir<span class="w"> </span>build<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span><span class="nb">cd</span><span class="w"> </span>build
$<span class="w"> </span>cmake<span class="w"> </span>..<span class="w"> </span>-DINTERFACE64<span class="o">=</span><span class="m">1</span><span class="w"> </span>-DSYMBOLSUFFIX<span class="o">=</span>64_<span class="w"> </span>-DBUILD_SHARED_LIBS<span class="o">=</span>ON<span class="w"> </span>-DBUILD_STATIC_LIBS<span class="o">=</span>ON
$<span class="w"> </span>cmake<span class="w"> </span>--build<span class="w"> </span>.<span class="w"> </span>-j
</code></pre></div></p>
<p>Note that the result is not 100% identical to the Make result. For example, the
library name ends in <code>_64</code> rather than <code>64_</code> - it is recommended to rename them
to match the Make library names (also update the <code>libsuffix</code> entry in
<code>openblas64.pc</code> to match that rename).
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>cmake<span class="w"> </span>--install<span class="w"> </span>.<span class="w"> </span>--prefix<span class="w"> </span><span class="nv">$PWD</span>/../../openblas/cmake64
$<span class="w"> </span>tree<span class="w"> </span>.
.
├──<span class="w"> </span>include
│<span class="w">   </span>└──<span class="w"> </span>openblas64
│<span class="w">   </span>├──<span class="w"> </span>cblas.h
│<span class="w">   </span>├──<span class="w"> </span>f77blas.h
│<span class="w">   </span>├──<span class="w"> </span>lapacke_config.h
│<span class="w">   </span>├──<span class="w"> </span>lapacke_example_aux.h
│<span class="w">   </span>├──<span class="w"> </span>lapacke.h
│<span class="w">   </span>├──<span class="w"> </span>lapacke_mangling.h
│<span class="w">   </span>├──<span class="w"> </span>lapacke_utils.h
│<span class="w">   </span>├──<span class="w"> </span>lapack.h
│<span class="w">   </span>├──<span class="w"> </span>openblas64
│<span class="w">   </span>│<span class="w">   </span>└──<span class="w"> </span>lapacke_mangling.h
│<span class="w">   </span>└──<span class="w"> </span>openblas_config.h
└──<span class="w"> </span>lib
<span class="w"> </span>├──<span class="w"> </span>cmake
<span class="w"> </span>│<span class="w">   </span>└──<span class="w"> </span>OpenBLAS64
<span class="w"> </span>│<span class="w">   </span>├──<span class="w"> </span>OpenBLAS64Config.cmake
<span class="w"> </span>│<span class="w">   </span>├──<span class="w"> </span>OpenBLAS64ConfigVersion.cmake
<span class="w"> </span>│<span class="w">   </span>├──<span class="w"> </span>OpenBLAS64Targets.cmake
<span class="w"> </span>│<span class="w">   </span>└──<span class="w"> </span>OpenBLAS64Targets-noconfig.cmake
<span class="w"> </span>├──<span class="w"> </span>libopenblas_64.a
<span class="w"> </span>├──<span class="w"> </span>libopenblas_64.so<span class="w"> </span>-&gt;<span class="w"> </span>libopenblas_64.so.0
<span class="w"> </span>└──<span class="w"> </span>pkgconfig
<span class="w"> </span>└──<span class="w"> </span>openblas64.pc
</code></pre></div></p>
<h3 id="the-upcoming-standardized-ilp64-convention">The upcoming standardized ILP64 convention</h3>
<p>While the <code>64_</code> convention above got some adoption, it's slightly hacky and is
implemented through the use of <code>objcopy</code>. An effort is ongoing for a more
broadly adopted convention in the reference BLAS and LAPACK libraries, using
(a) the <code>_64</code> suffix, and (b) applying that suffix <em>before</em> rather than after
Fortran compiler mangling. The central issue for this is
<a href="https://github.com/Reference-LAPACK/lapack/issues/666">lapack#666</a>.</p>
<p>For the most common cases of compiler mangling (a single <code>_</code> appended), the end
result will be:</p>
<table>
<thead>
<tr>
<th>base API name</th>
<th>binary symbol name</th>
<th>call from Fortran code</th>
<th>call from C code</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>dgemm</code></td>
<td><code>dgemm_64_</code></td>
<td><code>dgemm_64(...)</code></td>
<td><code>dgemm_64_(...)</code></td>
</tr>
<tr>
<td><code>cblas_dgemm</code></td>
<td><code>cblas_dgemm_64</code></td>
<td>n/a</td>
<td><code>cblas_dgemm_64(...)</code></td>
</tr>
</tbody>
</table>
<p>For other compiler mangling schemes, replace the trailing <code>_</code> by the scheme in use.</p>
<p>The shared library name for this <code>_64</code> convention should be <code>libopenblas_64.so</code>.</p>
<p>Note: it is not yet possible to produce an OpenBLAS build which employs this
convention! Once reference BLAS and LAPACK with support for <code>_64</code> have been
released, a future OpenBLAS release will support it. For now, please use the
older <code>64_</code> scheme and avoid using the name <code>libopenblas_64.so</code>; it should be
considered reserved for future use of the <code>_64</code> standard as prescribed by
reference BLAS/LAPACK.</p>
<h2 id="performance-and-runtime-behavior-related-build-options">Performance and runtime behavior related build options</h2>
<p>For these options there are multiple reasonable or common choices.</p>
<h3 id="threading-related-options">Threading related options</h3>
<p>OpenBLAS can be built as a multi-threaded or single-threaded library, with the
default being multi-threaded. It's expected that the default <code>libopenblas</code>
library is multi-threaded; if you'd like to also distribute single-threaded
builds, consider naming them <code>libopenblas_sequential</code>.</p>
<p>OpenBLAS can be built with pthreads or OpenMP as the threading model, with the
default being pthreads. Both options are commonly used, and the choice here
should not influence the shared library name. The choice will be captured by
the <code>.pc</code> file. E.g.,:
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>pkg-config<span class="w"> </span>--libs<span class="w"> </span>openblas
-fopenmp<span class="w"> </span>-lopenblas
$<span class="w"> </span>cat<span class="w"> </span>openblas.pc
...
<span class="nv">openblas_config</span><span class="o">=</span><span class="w"> </span>...<span class="w"> </span><span class="nv">USE_OPENMP</span><span class="o">=</span><span class="m">0</span><span class="w"> </span><span class="nv">MAX_THREADS</span><span class="o">=</span><span class="m">24</span>
</code></pre></div></p>
<p>The maximum number of threads users will be able to use is determined at build
time by the <code>NUM_THREADS</code> build option. It defaults to 24, and there's a wide
range of values that are reasonable to use (up to 256). 64 is a typical choice
here; there is a memory footprint penalty that is linear in <code>NUM_THREADS</code>.
Please see <code>Makefile.rule</code> for more details.</p>
<h3 id="cpu-architecture-related-options">CPU architecture related options</h3>
<p>OpenBLAS contains a lot of CPU architecture-specific optimizations, hence when
distributing to a user base with a variety of hardware, it is recommended to
enable CPU architecture runtime detection. This will dynamically select
optimized kernels for individual APIs. To do this, use the <code>DYNAMIC_ARCH=1</code>
build option. This is usually done on all common CPU families, except when
there are known issues.</p>
<p>In case the CPU architecture is known (e.g. you're building binaries for macOS
M1 users), it is possible to specify the target architecture directly with the
<code>TARGET=</code> build option.</p>
<p><code>DYNAMIC_ARCH</code> and <code>TARGET</code> are covered in more detail in the main <code>README.md</code>
in this repository.</p>
<h2 id="real-world-examples">Real-world examples</h2>
<p>OpenBLAS is likely to be distributed in one of these distribution models:</p>
<ol>
<li>As a standalone package, or multiple packages, in a packaging ecosystem like
a Linux distro, Homebrew, conda-forge or MSYS2.</li>
<li>Vendored as part of a larger package, e.g. in Julia, NumPy, SciPy, or R.</li>
<li>Locally, e.g. making available as a build on a single HPC cluster.</li>
</ol>
<p>The guidance on this page is most important for models (1) and (2). These links
to build recipes for a representative selection of packaging systems may be
helpful as a reference:</p>
<ul>
<li><a href="https://src.fedoraproject.org/rpms/openblas/blob/rawhide/f/openblas.spec">Fedora</a></li>
<li><a href="https://salsa.debian.org/science-team/openblas/-/blob/master/debian/rules">Debian</a></li>
<li><a href="https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/openblas.rb">Homebrew</a></li>
<li><a href="https://github.com/msys2/MINGW-packages/blob/master/mingw-w64-openblas/PKGBUILD">MSYS2</a></li>
<li><a href="https://github.com/conda-forge/openblas-feedstock/blob/main/recipe/build.sh">conda-forge</a></li>
<li><a href="https://github.com/MacPython/openblas-libs/blob/main/tools/build_openblas.sh">NumPy/SciPy</a></li>
<li><a href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/science/math/openblas/default.nix">Nixpkgs</a></li>
</ul>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": "..", "features": [], "search": "../assets/javascripts/workers/search.b8dbb3d2.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
<script src="../assets/javascripts/bundle.ebd0bdb7.min.js"></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink