flexiblas(1)

NAME
flexiblas - the FlexiBLAS administration tool

SYNOPSIS
flexiblas [options] command [command-options] flexiblas64 [options] command [command-options]

DESCRIPTION
The flexiblas tool is a command line utility shipped with the FlexiBLAS library. It is used to configure the global and the local flexiblasrc file. Its main purpose it selecting the default BLAS backend used with FlexiBLAS and other runtime specific options. FlexiBLAS uses up to four locations to search for its configuration, a system-wide configuration file, a per-user configuration file, a per-host configuration file, and one configuration file defined by an environment variable FLEXIBLAS_CONFIG. The configuration files are evaluated in this order and a later loaded one overwrites the settings of a previously loaded one. The flexiblas64 tool is used for the 64-bit integer variant of FlexiBLAS. Furthermore, it can be used to add or remove BLAS backends form the configuration files.

  Usage Examples
If application are build against FlexiBLAS, there are severval ways to select the active BLAS library. The installed (and known) BLAS backends can be listed via
    flexiblas list The default BLAS backend can be set using
   flexiblas default NAME_OF_THE_LIBRARY If the BLAS backend should only be set temporary, this can be done via the FLEXIBLAS environment variable. This can either be set to a name of a BLAS backend (from flexiblas list)
    FLEXIBLAS=NAME_OF_THE_LIBRARY ./yourapp or to the path of a shared object containing a BLAS implementation
    FLEXIBLAS="/usr/lib/libyourblas.so" ./yourapp

  Hooks
FlexiBLAS supports so called hooks to modify/extent/change the behavior of BLAS and LAPACK functions. This can be used for profiling, automatic offloadlind, and other debuging purposes. The hooks are configured either via the FLEXIBLAS_HOOK environment variable or the flexiblas tool. The FLEXIBLAS_HOOK variable contains a colon separate list of hooks or shared libraries containing the hook. The hooks are loaded in the order they are specified. If the hook_enabled setting in a configuration file is set but empty all hooks are disabled for this configuration file. In this way the per host setting can disable the user settings. Using the hook disableall command the hook_enabled entry is removed and thus no hook settings are in the configuration.

  Configuration Priority
FlexiBLAS uses serveral configuration paths to select the BLAS backend or enable and disable other functionality. The configuration is read in the following order, thereby previous read information is overwritten. That means that last read configuration has the highest priority. 1. /etc/flexiblasrc - The system wide configuration file, hooks can not be configured here. 2. /etc/flexiblasrc.d/*.conf - Additional system wide configurations, read only. 3. ${HOME}/flexiblasrc - The user's configuration file. 4. ${HOME}/flexiblasrc.$(hostname) - The user's configuration file on a host, useful for NFS homedirectories. 5. FLEXIBLAS_CONFIG - The environment variable is used to specified a separate configuration file, e.g. per project. 6. FLEXIBLAS, FLEXIBLAS_HOOK - Select a BLAS implementation or a hook without changing the config.

  64-bit Integers
If FlexiBLAS is compiled with 64 bit intergers, flexiblas is replaced by flexiblas64 and FLEXIBLAS is replaced by FLEXIBLAS64 in all names of configuration files, environment variable, etc.

OPTIONS

  Commands

help
    Print information about the tool and its usage.

print
    Print the whole BLAS related configuration including search paths, default settings, etc.

list
    List all available BLAS libraries from the configuration files.

default BLASNAME
    Sets the default BLAS backend in the selected configuration file.

default
    Removes the default setting from the selected configuration file.

add BLASNAME sharedlibrary.so ["comment string"]
    Add a new BLAS backend called "BLASNAME" to the selected configuration file. This will create a section like
      [BLASNAME]
      library=sharedlibrary.so
      comment="comment string"
    in the selected configuration file. The comment string is optional.

remove NAME
    Remove a BLAS backed called "NAME" from the selected configuration file.

set property [value]
    Set a property in the configuration file. If the value is not given the property is reset to its default. The available properties are listed below.

  Hook commands:
Hooks are additional plugins that integrate in the call of a BLAS or LAPACK function. They are used for debugging or profiling purpose.

hook list
    List all available hooks. The hooks are automatically found in the FlexiBLAS library directories.

hook show hook-name
    Show details about a specific hook. This includes the name, the authors, a short description, and the list of configurable options.

hook enable hook-name
    Enable a hook. If more than one hook is enabled they are executed in the order they got enabled.

hook disable hook-name
    Disable a hook.

hook disableall
    Disable all hooks in a configuration and remove the setting from the configuration. This is necessary if, i.e., hooks are enabled in the user configuration and the host configuration file has an empty hook_enabled field. In this case the FlexiBLAS does not use a hook since the host configuration overwrites the user configuration. Then hook disableall is used to remove the hook_enabled from the host configuration.

hook enabled
    Show all enabled hooks in the configuration files.

hook active
    Show the currently active hooks and from which configuration file they are loaded.

hook set hook-name option-name value
    Set an option for a hook to the given value. All available options for a hook can be shown with the hook show command. ook-name option-name Unset an option for a hook.

  General Options:

-u, --user
    Edit the user's flexiblasrc configuration (default options, except of executing as root).

-g, --global
    Edit the global flexiblasrc configuration (default in case of executing as root).

-H, --host
    Edit the host configuration file.

-E, --environment
    Edit the configuration file given by the environment variable FLEXIBLAS_CONFIG.

-p, --pipe
    Make the output of some commands, like list pipe compatible to use them in scripts.

-h, --help
    Print this information and exit.

-v, --version
    Print the versionformation and exit.

  Properties

verbose integer
    Change the verbosity level of FlexiBLAS. The default verbosity level is 0 which only displays critical errors. If a level larger than is specified, FlexiBLAS will produce many debug information on stderr.

nolapack integer
    If the value is non zero, FlexiBLAS does not load the LAPACK functions from the backend. That means that only the internal LAPACK routines are used.

FILES

/etc/flexiblasrc
    System-wide FlexiBLAS configuration file.

/etc/flexiblasrc.d/*.conf
    Additional system-wide configuration files. Read-only, Installed by BLAS library to be included in FlexiBLAS.

~/.flexiblasrc
    User FlexiBLAS configuration file.

~/.flexiblasrc.$(hostname)
    User FlexiBLAS configuration file for a specific host.

ENVIRONMENT VARIABLES

FLEXIBLAS_CONFIG
    Using the FLEXIBLAS_CONFIG environment variable an additional configuration can be set. This can be used for per-project settings.

FLEXIBLAS
    Select a BLAS implementation ignoring the configuration settings. If the content of the variable is a path to a shared object containing a BLAS library, this is used as BLAS implementation. It is not required that this BLAS library is configured in any of the configuration files.

FLEXIBLAS_HOOK
    The FLEXIBLAS_HOOK variable contains a colon separated list of hooks which should be loaded. If a hook is a path to a shared object instead of a name of an available hook, FlexiBLAS tries to load this library as a hook,

FLEXIBLAS_LIBRARY_PATH
    The FLEXIBLAS_LIBRARY_PATH variable contains a colon separated list of addtional search paths for FlexiBLAS. The paths are used to find BLAS implementations and hooks.

REPORTING BUGS
The current information about the developers and reporting bugs can be found on the FlexiBLAS homepage. FlexiBLAS Homepage: <http://www.mpi-magdeburg.mpg.de/projects/flexiblas>

AUTHORS
 Martin Koehler, Jens Saak

SEE ALSO
 M. Koehler and J. Saak, FlexiBLAS - A flexible BLAS library with runtime exchangeable backends,
 LAPACK Working Note 284, 2013

COPYRIGHT
Copyright (C) 2013-2020 Martin Koehler

LICENSE
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.