1flexiblas(1)                 The FlexiBLAS Library                flexiblas(1)
2
3
4

NAME

6       flexiblas - the FlexiBLAS administration tool
7

SYNOPSIS

9       flexiblas [options] command [command-options]
10
11       flexiblas64 [options] command [command-options]
12

DESCRIPTION

14       The flexiblas tool is a command line utility shipped with the FlexiBLAS
15       library. It is used to configure the global and the  local  flexiblasrc
16       file.  Its main purpose it selecting the default BLAS backend used with
17       FlexiBLAS and other runtime specific options. FlexiBLAS uses up to four
18       locations  to search for its configuration, a system-wide configuration
19       file, a per-user configuration file, a per-host configuration file, and
20       one  configuration  file  defined  by  an  environment  variable FLEXI‐
21       BLAS_CONFIG. The configuration files are evaluated in this order and  a
22       later loaded one overwrites the settings of a previously loaded one.
23
24       The  flexiblas64  tool is used for the 64-bit integer variant of Flexi‐
25       BLAS.
26
27       Furthermore, it can be used to add or remove  BLAS  backends  form  the
28       configuration files.
29
30
31   Usage Examples
32       If  application are build against FlexiBLAS, there are severval ways to
33       select the active BLAS library. The installed (and known) BLAS backends
34       can be listed via
35
36           flexiblas list
37
38       The default BLAS backend can be set using
39
40          flexiblas default NAME_OF_THE_LIBRARY
41
42       If  the BLAS backend should only be set temporary, this can be done via
43       the FLEXIBLAS environment variable. This can either be set to a name of
44       a BLAS backend (from flexiblas list)
45
46           FLEXIBLAS=NAME_OF_THE_LIBRARY  ./yourapp
47
48       or to the path of a shared object containing a BLAS implementation
49
50           FLEXIBLAS="/usr/lib/libyourblas.so" ./yourapp
51
52
53   Hooks
54       FlexiBLAS supports so called hooks to modify/extent/change the behavior
55       of BLAS and LAPACK functions. This can be used for profiling, automatic
56       offloadlind,  and other debuging purposes. The hooks are configured ei‐
57       ther via the FLEXIBLAS_HOOK environment variable or the flexiblas tool.
58       The  FLEXIBLAS_HOOK variable contains a colon separate list of hooks or
59       shared libraries containing the hook. The hooks are loaded in the order
60       they are specified. If the hook_enabled setting in a configuration file
61       is set but empty all hooks are disabled for  this  configuration  file.
62       In  this  way the per host setting can disable the user settings. Using
63       the hook disableall command the hook_enabled entry is removed and  thus
64       no hook settings are in the configuration.
65
66
67   Configuration Priority
68       FlexiBLAS  uses serveral configuration paths to select the BLAS backend
69       or enable and disable other functionality. The configuration is read in
70       the  following order, thereby previous read information is overwritten.
71       That means that last read configuration has the highest priority.
72
73       1. /etc/flexiblasrc - The system wide configuration file, hooks can not
74       be configured here.
75
76       2.  /etc/flexiblasrc.d/*.conf  - Additional system wide configurations,
77       read only.
78
79       3. ${HOME}/flexiblasrc - The user's configuration file.
80
81       4. ${HOME}/flexiblasrc.$(hostname) - The user's configuration file on a
82       host, useful for NFS homedirectories.
83
84       5.  FLEXIBLAS_CONFIG  - The environment variable is used to specified a
85       separate configuration file, e.g. per project.
86
87       6. FLEXIBLAS, FLEXIBLAS_HOOK - Select a BLAS implementation or  a  hook
88       without changing the config.
89
90
91   64-bit Integers
92       If  FlexiBLAS  is compiled with 64 bit intergers, flexiblas is replaced
93       by flexiblas64 and FLEXIBLAS is replaced by FLEXIBLAS64 in all names of
94       configuration files, environment variable, etc.
95
96

OPTIONS

98   Commands
99       help   Print information about the tool and its usage.
100
101       print  Print  the  whole  BLAS  related  configuration including search
102              paths, default settings, etc.
103
104       list   List all available BLAS libraries from the configuration files.
105
106       default BLASNAME
107              Sets the default BLAS  backend  in  the  selected  configuration
108              file.
109
110       default
111              Removes  the  default  setting  from  the selected configuration
112              file.
113
114       add BLASNAME sharedlibrary.so ["comment string"]
115              Add a new BLAS backend called "BLASNAME" to the selected config‐
116              uration file. This will create a section like
117
118                [BLASNAME]
119                library=sharedlibrary.so
120                comment="comment string"
121
122              in  the  selected  configuration file. The comment string is op‐
123              tional.
124
125       remove NAME
126              Remove a BLAS backed called "NAME" from the selected  configura‐
127              tion file.
128
129       set property [value]
130              Set  a  property  in the configuration file. If the value is not
131              given the property is reset to its default. The available  prop‐
132              erties are listed below.
133
134
135   Hook commands:
136       Hooks  are  additional  plugins that integrate in the call of a BLAS or
137       LAPACK function. They are used for debugging or profiling purpose.
138
139
140       hook list
141              List all available hooks. The hooks are automatically  found  in
142              the FlexiBLAS library directories.
143
144       hook show hook-name
145              Show  details about a specific hook. This includes the name, the
146              authors, a short description, and the list of  configurable  op‐
147              tions.
148
149       hook enable hook-name
150              Enable  a  hook.  If more than one hook is enabled they are exe‐
151              cuted in the order they got enabled.
152
153       hook disable hook-name
154              Disable a hook.
155
156       hook disableall
157              Disable all hooks in a configuration and remove the setting from
158              the configuration. This is necessary if, i.e., hooks are enabled
159              in the user configuration and the host configuration file has an
160              empty  hook_enabled  field.  In this case the FlexiBLAS does not
161              use a hook since the host configuration overwrites the user con‐
162              figuration.  Then hook disableall is used to remove the hook_en‐
163              abled from the host configuration.
164
165       hook enabled
166              Show all enabled hooks in the configuration files.
167
168       hook active
169              Show the currently active hooks  and  from  which  configuration
170              file they are loaded.
171
172       hook set hook-name option-name value
173              Set  an  option for a hook to the given value. All available op‐
174              tions for a hook can be shown with the hook show command.  0ook-
175              name option-name Unset an option for a hook.
176
177
178   General Options:
179       -u, --user
180              Edit  the user's flexiblasrc configuration (default options, ex‐
181              cept of executing as root).
182
183       -g, --global
184              Edit the global flexiblasrc configuration (default  in  case  of
185              executing as root).
186
187       -H, --host
188              Edit the host configuration file.
189
190       -E, --environment
191              Edit  the  configuration  file given by the environment variable
192              FLEXIBLAS_CONFIG.
193
194       -p, --pipe
195              Make the output of some commands, like list pipe  compatible  to
196              use them in scripts.
197
198       -h, --help
199              Print this information and exit.
200
201       -v, --version
202              Print the versionformation and exit.
203
204
205   Properties
206       verbose integer
207              Change  the  verbosity level of FlexiBLAS. The default verbosity
208              level is 0 which only  displays  critical  errors.  If  a  level
209              larger than  is specified, FlexiBLAS will produce many debug in‐
210              formation on stderr.
211
212       nolapack integer
213              If the value is non zero, FlexiBLAS does  not  load  the  LAPACK
214              functions  from  the  backend. That means that only the internal
215              LAPACK routines are used.
216

FILES

218       /etc/flexiblasrc
219              System-wide FlexiBLAS configuration file.
220
221       /etc/flexiblasrc.d/*.conf
222              Additional system-wide configuration files. Read-only, Installed
223              by BLAS library to be included in FlexiBLAS.
224
225       ~/.flexiblasrc
226              User FlexiBLAS configuration file.
227
228       ~/.flexiblasrc.$(hostname)
229              User FlexiBLAS configuration file for a specific host.
230
231

ENVIRONMENT VARIABLES

233       FLEXIBLAS_CONFIG
234              Using  the  FLEXIBLAS_CONFIG  environment variable an additional
235              configuration can be set. This can be used for per-project  set‐
236              tings.
237
238       FLEXIBLAS
239              Select  a  BLAS  implementation  ignoring the configuration set‐
240              tings. If the content of the variable is a path to a shared  ob‐
241              ject containing a BLAS library, this is used as BLAS implementa‐
242              tion. It is not required that this BLAS library is configured in
243              any of the configuration files.
244
245       FLEXIBLAS_HOOK
246              The  FLEXIBLAS_HOOK  variable contains a colon separated list of
247              hooks which should be loaded. If a hook is a path  to  a  shared
248              object  instead  of a name of an available hook, FlexiBLAS tries
249              to  load this library as a hook,
250
251       FLEXIBLAS_LIBRARY_PATH
252              The FLEXIBLAS_LIBRARY_PATH variable contains a  colon  separated
253              list  of  addtional  search  paths for FlexiBLAS.  The paths are
254              used to find BLAS implementations and hooks.
255
256

REPORTING BUGS

258       The current information about the developers and reporting bugs can  be
259       found on the FlexiBLAS homepage.
260
261       FlexiBLAS   Homepage:  <http://www.mpi-magdeburg.mpg.de/projects/flexi
262       blas>
263

AUTHORS

265        Martin Koehler, Jens Saak
266

SEE ALSO

268        M. Koehler and J. Saak, FlexiBLAS - A flexible BLAS library with runtime exchangeable backends,
269        LAPACK Working Note 284, 2013
270
271
273       Copyright (C) 2013-2020 Martin Koehler
274

LICENSE

276       License  GPLv3+:  GNU  GPL  version  3  or  later   <http://gnu.org/li
277       censes/gpl.html>.   This  is  free software: you are free to change and
278       redistribute it.  There is NO WARRANTY, to the extent permitted by law.
279
280
281
282
283M. Koehler                         2013-2022                      flexiblas(1)
Impressum