|
1 | | -# SLICOT Software Installation and Updating |
| 1 | +SLICOT Software Installation and Updating |
| 2 | +========================================= |
2 | 3 |
|
3 | 4 | This file describes how to install and update the **SLICOT** Library, and how to run the example programs. |
4 | 5 |
|
5 | | -The essential source code and documentation for the **SLICOT** software is stored in the **SLICOT** Library root directory, **`slicot`**, and its subdirectories (**`benchmark_data`**, **`doc`**, **`examples`**, **`src`** and **`src_aux`**). |
| 6 | +Requirements |
| 7 | +------------ |
6 | 8 |
|
7 | | -The object and/or executable files can be built using the information given in this file. **SLICOT** routines make calls to subprograms from the state-of-the-art packages **LAPACK** (Linear Algebra Package) and **BLAS** (Basic Linear Algebra Subprograms). Fortran source code and prebuilt, Fortran-based **LAPACK** and **BLAS** libraries are freely downloadable from https://netlib.org. However, for maximum efficiency it is recommended to use machine-specific, optimized versions whenever possible. |
| 9 | +In order to build SLICOT you need: |
8 | 10 |
|
9 | | -Template make files are provided to help building the **SLICOT** Library object file, and to link and run the available example programs calling the **SLICOT** Library routines. In order to use these make files on a specific Unix-like or Windows platform, some changes might be needed in the files **`make*.inc`** and **`makefile*`** stored in the **SLICOT** (sub-)directories, **`slicot`**, **`examples`**, **`src`** and **`src_aux`**. The file named **`make.inc`** and the files **`makefile`** have been used on Windows platforms with Intel Fortran compilers. The files named **`make_Unix.inc`** and **`makefile_Unix`** are templates for Unix-like machines, including Linux, with gfortran compiler. Denote by <**slicotroot**> the path to the **`slicot`** directory, which can be, e.g., **`c:\slicot`**, on Windows platforms. (The last (sub)directory name in <**slicotroot**> is **`slicot`**.) |
| 11 | + * a F77 compatible Fortran compiler |
| 12 | + * cmake, at least 3.15 or 3.22 for the ILP64 build |
| 13 | + * a BLAS/LIBRARY |
10 | 14 |
|
11 | | -The changes in **`make*.inc`** might define the specific machine (platform) identifier, the compiler, linker, and archiver flags, and the location and names of the **LAPACK** and **BLAS** libraries, which the program files should be linked to. Some details are given in the **`make*.inc`** files. |
| 15 | +The following compilers are tested |
12 | 16 |
|
13 | | -After performing the necessary changes, as suggested in the comments of the make files, the other needed **SLICOT**-related files can be generated automatically with the command |
| 17 | + * gcc 9, 11, 13, 14 |
| 18 | + * clang/flang 20 |
14 | 19 |
|
15 | | -**`make`** (or **`nmake`**, for Windows platforms) |
| 20 | +We support Linux, Free/Net/OpenBSD, MacOSX (Intel and ARM), Windows with MSYS2. |
16 | 21 |
|
17 | | -issued from the directory **`slicot`** of <**slicotroot**>. |
| 22 | +For performance reasons, we suggest to use an optimized BLAS implementation |
| 23 | +like |
18 | 24 |
|
19 | | -The first execution of **`(n)make`** will create the following files |
| 25 | + * OpenBLAS, https://www.openblas.net |
| 26 | + * BLIS, https://github.com/flame/blis |
| 27 | + * Intel oneAPI MKL, https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html |
| 28 | + * FlexiBLAS, https://www.mpi-magdeburg.mpg.de/projects/flexiblas |
20 | 29 |
|
21 | | - - the **SLICOT** Library object files **`*.o`** (for Unix machines), or **`*.obj`** (for Windows machines), in the subdirectories **`src`** and **`src_aux`** of **`slicot`**; |
22 | | - - the library files **`slicot.a`** and **`lpkaux.a`**, or **`slicot.lib`** and **`lpkaux.lib`**, respectively, in the directory **`slicot`**; the libraries **`lpkaux.a`** or **`lpkaux.lib`** contain the object files for two **LAPACK** deprecated subroutines, **`dlatzm.f`** and **`zlatzm.f`**, which are called by few **SLICOT** routines. |
23 | | - - the example programs object and executable files, in the subdirectory **`examples`**; |
24 | | - - the files **`*.exa`**, with the results computed on the local machine, with the same name as for the files with data (**`*.dat`**) and reference results (**`*.res`**), also in the subdirectory **`examples`**. |
| 30 | +Installation |
| 31 | +------------ |
| 32 | +SLICOT requires an *out-of-source* build process. That means, the source code |
| 33 | +direcotry stays untouched during the build. |
25 | 34 |
|
26 | | -The subsequent executions of **`(n)make`** will update the files if changes have been performed (assuming that the object and executable files have been preserved on their subdirectories). |
| 35 | +The in order to configure and compile the source, use `cmake`: |
| 36 | +```shell |
| 37 | +cmake -S . -B build-dir <OPTIONS> |
| 38 | +cmake --build build-dir |
| 39 | +``` |
| 40 | +after building, SLICOT can be installed via |
| 41 | +```shell |
| 42 | +cmake --build build-dir --target install |
| 43 | +``` |
27 | 44 |
|
28 | | -The files **`*.exa`**, with the computed results may be compared with the reference results. Several types of differences could be noticed, including possible sign changes for some elements, or even different values in some columns and/or rows of the computed matrices. For instance, the matrices of similarity or equivalence transformations could differ from a platform/compiler to another. This does not usually mean that the computed results are wrong. |
| 45 | +The test suite is executed using |
| 46 | +```shell |
| 47 | +ctest --test-dir build-dir |
| 48 | +``` |
| 49 | + |
| 50 | +The following options to cmake are availble: |
| 51 | + |
| 52 | +| Option | Possible Values | Default Value | Description | |
| 53 | +|:-------|:----------------|:--------------|-------------| |
| 54 | +|`CMAKE_INSTALL_PREFIX` | valid path | `/usr/local` | Installation path | |
| 55 | +|`CMAKE_BUILD_TYPE` | `Debug`, `Release`, `MinSizeRel`, `RelWithDebInfo`, `Coverage` | `Release` | Specify the build type | |
| 56 | +|`BUILD_SHARED_LIBS` | `ON`, `OFF` | `OFF` | Build SLICOT as shared library | |
| 57 | +|`SLICOT_TESTING` | `ON`, `OFF` | `ON` | Build the examples and the test suite | |
| 58 | +|`SLICOT_DEBUG` | `ON`, `OFF` | `OFF` | Enable the debug build, equivalent to `CMAKE_BUILD_TYPE=Debug`| |
| 59 | +|`SLICOT_INTEGER8` | `ON`, `OFF` | `OFF` | Enable the ILP64 integer model, i.e. the Fortran `INTEGER` defaults to a 64-bit integer, requires cmake >= 3.22| |
| 60 | +|`BLA_VENDOR` | BLAS Vendor Name | empty | Specify the BLAS library to search for, see https://cmake.org/cmake/help/latest/module/FindBLAS.html for details | |
| 61 | + |
| 62 | +The options are passed as `-DOPTION=VALUE` to cmake. |
| 63 | + |
| 64 | +Issues |
| 65 | +------ |
| 66 | +A list of known issues can be found in [KNOWN_ISSUSES.md](./KNOWN_ISSUES.md) |
29 | 67 |
|
30 | | -More details for executing other tasks, e.g., cleaning the subdirectories **`src`** and **`examples`**, are given in the files **`makefile* included in directory **`slicot`** and in the subdirectories **`src`** and **`examples`**. |
31 | 68 |
|
0 commit comments