IMPORTANT NOTES

1) The present SlackBuild for ATLAS does by no means try to take into account
   all configuration/build issues of ATLAS. Nevertheless, any relevant patches
   mentioned in the ATLAS Errata are applied.

2) The script mostly assumes that you are installing on an x86 or x86_64
   platform and use gcc for compilation. If you decide to use other compilers or
   install on another platform, you are unfortunately on your own and welcome to
   suggest improvements or patches to this SlackBuild. There is one small
   exception to this: the USE_DWALL variable, see below.

3) There is no "post install" tuning performed by this script.

4) ATLAS does not conflict with the reference netlib BLAS. Nevertheless, if
   ATLAS got installed successfully you should consider removing netlib BLAS and
   (re)compiling every BLAS/LAPACK dependent package. Otherwise you may not have
   much gain from installing ATLAS.

5) There is a strong interaction between ATLAS and LAPACK. By default ATLAS
   implements an optimized subset of LAPACK and creates the corresponding static
   library. Nevertheles, provided that the full LAPACK source is available,
   ATLAS builds a complete LAPACK library linked against its optimized BLAS
   implementation. This is what the atlas SlackBuild does by default. You may
   decide that you don't what this, then make use of the LAPACK_SOURCE variable
   (see below).


INSTALLATION DETAILS

1) Make sure CPU throttling is off before starting the install. This is
   important, since ATLAS has to tune itself. As with Slackware 14.2 you
   can run /etc/rc.d/rc.cpufreq as root with "performance" as command line
   argument. To reset, run it again with what gets set at boot time (by
   default "ondemand") as command line argument.

2) For the same reason, keep the extra load on the system as low as possible
   while building ATLAS.


GENERIC SETUP VARIABLES

1) SYS_DESTDIR is set by default to "/usr" and is the system destination
   directory. When installing the package produced by this SlackBuild,
   ATLAS's and LAPACK's files will be written to $SYS_DESTDIR/include,
   $SYS_DESTDIR/include/atlas and $SYS_DESTDIR/lib (or lib64).
   Documentation files are written to /usr/doc/atlas-$VERSION if not
   otherwise stated (see below).
   You may want to change the value of SYS_DESTDIR to avoid conflicts. If
   you do so, you have to make sure that these libraries and corresponding
   headers are found by the compiler or the configuration software used
   to build code depending on them.
   IMPORTANT: SYS_DESTDIR has to have an absolute path as value.

2) DEFAULT_DOCS has the default value "yes", which means that docs go
   to /usr/doc/atlas-$VERSION, but you may want to let the docs go
   to $SYS_DESTDIR/doc/atlas-$VERSION. For this, just set this
   variable to "no".


SETUP VARIABLES FOR ATLAS

1) USE_ARCH_DEFAULTS defaults to "yes", which means that the library
   will be optimized by trying to take into account former builds done
   on a similar machine. Thus ATLAS will use predefined optimizations
   if available. This may reduce (much) the compilation time but may
   not give you the best result if you don't use the same gcc compiler
   version as the ATLAS author.
   Please note that with this variable set to "no", or if there are no
   known optimizations for your machine ATLAS compilation may last for
   many hours! Take a nap :-)
   NOTE: On the machine of this SlackBuild's author setting
         USE_ARCH_DEFAULTS to "no" provided libraries with definitely
         better performance. Compilation took about six hours.

2) ARCH_DEF_DIR has different meanings, depending on the value of
   USE_ARCH_DEFAULTS:
   a) If USE_ARCH_DEFAULTS is "yes" and you have some custom architectural
      defaults, then you may set this to the absolute path of the directory
      containing the file with your custom defaults.
   b) If USE_ARCH_DEFAULTS is "no" and you would like to create custom
      architectural defaults then set this to the absolute path of the
      directory which should contain the file with the custom defaults.
      NOTE: Since this file is supposed to survive an upgrade, it doesn't
            get included in the Slackware package. You have to remove it
            by hand, if needed. A file named "ARCH_DEF_DIR" gets written
            to the documentation directory, to remind you where the created
            architectural defaults are. Make a backup of it, since it may
            get deleted with an upgrade.
   ARCH_DEF_DIR defaults to the empty string, which means that neither your
   custom defaults are used nor custom defaults are created.

3) USE_DWALL defaults to "no" which should be OK for x86 or x86_64 and the gcc
   compiler. If you are on another architecture than x86 and/or don't use gcc
   you need to set it to "yes".

4) L2_CACHE_SIZE provides the size of the level 2 cache in bytes. By default it
   is deduced from /proc/cpuinfo but you can just set the value manually, if you
   wish or need so.

5) NUM_THREADS allows you to set the maximum number of threads. By default it
   is "-1", which means autodection. In this case it gets set equal to the
   number of available processors.

6) USE_PROCESSORS is by default the empty string, which means that any of the
   available processors may be used. Nevertheless, under some circumstances,
   one may want to specify the processor IDs, e.g. "0 2 4". Please consult
   atlas_install.pdf, p. 13 for more informations.
   NOTES: a) This is incompatible with the autodetection of the number of
             threads. Therefore NUM_THREADS must be greater than 1.
          b) Write just the processor IDs to this string, the script takes
             care of the rest. Take care to have NUM_THREADS equal to the
             amount of processor IDs.

7) SHARED_SWITCH is set by default to ask for building shared libs along with
   the static ones. Set this to the empty string, if you don't want to have
   shared libs.


SETUP VARIABLES FOR LAPACK

1) LAPACK_SOURCE set this variable to the empty string, if you don't want for a
   full LAPACK library to get build.

2) TEST_LAPACK set this variable to "yes" if you would like to run the LAPACK
   tests. You will find the results of the tests in the documentation directory.
   This has no relevance, if you didn't allow for a full LAPACK build.

3) LAPACK_TIMER sets the timer to be used for LAPACK. If you stay with
   gfortran, presently the default compiler on Slackware, you can leave the
   value as is. Otherwise, set it to "NONE" or read LAPACK's make.inc.example
   for more informations.
   This has no relevance, if you didn't allow for a full LAPACK build.


