blis/INSTALL

BLIS framework
INSTALL
---

INTRODUCTION

This file is contains an abbreiviated description of how to configure,
compile, and install a BLIS library on your local system. It is mainly for
those of us who are impatient! PLEASE check the BLIS homepage for a wiki
page that describes the build process in much more detail.

The BLIS build system was designed for use with GNU/Linux (or some other
sane UNIX). Other requirements are:

 - GNU/Linux or some other sane UNIX
 - bash (2.0 or later)
 - GNU make
 - a working C compiler

We also require various other shell utilities that are so ubiquitous that
they are not worth mentioning (such as 'mv', 'mkdir', 'find', and so forth).
If you are missing these utilities, then you have much bigger problems than
not being able to build BLIS.


STEP 1: FRAMEWORK CONFIGURATION

The first step is to create a BLIS configuration. This will take the form of
a subdirectory of the 'config' directory. Be sure and give the configuration
some meaningful name, such as "x86-64opt" to indicate that it will be used for
an x86_64 architecture and employ optimizations.

When creating your configuration sub-directory, you can use the reference
configuration as a template:

  > ls config/reference
  bl2_arch.h  bl2_config.h  bl2_kernel.h  make_defs.mk
  > cp -r config/reference config/x86-64opt
  > ls config/x86-64opt
  bl2_arch.h  bl2_config.h  bl2_kernel.h  make_defs.mk

Now edit each of these four files. Here are some special notes about each
file:

  o bl2_arch.h
    - This is where you specify architectural details such as register and
      cache blocksizes.

  o bl2_config.h
    - This file is where you could place C preprocessor macros that would
      typically be defined by autoconf/configure. It contains just a few
      basic definitions such as whether to use memory alignment and, if so,
      what boundary multiple to use.

  o bl2_kernel.h
    - This file defines various kernels and micro-kernels. The reference
      configuration defines all kernels to use reference implementations
      (which are provided as part of the framework). If you end up
      writing your own optimized kernel for some operation, be sure and
      set it here. Notice that you only have to set ONE definition for
      each operation, as BLIS appends s,d,c,z (as well as 'bl2_') to the
      names to create the actual datatype instances. IMPORTANT: If you
      add your own kernels, OR if you use kernels provided with the BLIS
      distribution (i.e., in the 'kernels' directory), you MUST add a
      symbolic link to those kernels to the configuration sub-directory.
      So, for example, if you were going to use kernels for the x86-64
      architecture that are included with BLIS, you would run:

        > pwd
        /home/field/google_code/blis/config/x86-64opt
        > ls
        bl2_arch.h  bl2_config.h  bl2_kernel.h  make_defs.mk
        > ln -s ../../kernels/x86_64
        > ls bl2_arch.h  bl2_config.h  bl2_kernel.h  kernels  make_defs.mk
        > ls -l kernels
        lrwxrwxrwx 1 field dept 20 Dec  1 18:13 kernels -> ../../kernels/x86_64

      If you are building new/custom kernels, nothing stops you from
      storing your source code in an actual directory inside your
      configuration sub-directory (rather than somewhere else that is then
      symbolically linked to). But if you do that, it might get a little
      confusing if you create *new* configurations that use the *same*
      kernels. Wherever you choose to store your kernels, make sure that
      it makes sense for your workflow!

  o make_defs.mk
    - This file contains general make definitions. To specify things such
      as your C compiler and which compiler options to use, edit this
      file.

Once you have you configuration sub-directory in-place, you are done
configuring the framework!


STEP 2: MAKE CONFIGURATION

This step should be familiar to many in the open source software community.
Simply run:

  > ./configure <configname>

where <configname> is the configuration sub-directory name you chose in
step 1. If <configname> is not given, it defaults to 'reference'.

Upon running configure, you will get output similar to the following:

  configure: starting configuration of BLIS 0.1.0.
  configure: no configuration sub-directory given; defaulting to 'reference'.
  configure: no install prefix given; defaulting to /home/field/blis.
  configure: creating ./config.mk from build/config.mk.in
  configure: creating ./obj/reference
  configure: creating ./obj/reference/config
  configure: creating ./obj/reference/frame
  configure: creating ./lib/reference
  configure: mirroring ./config/reference to ./obj/reference/config
  configure: mirroring ./frame to ./obj/reference/frame
  configure: creating makefile fragment in ./config/reference
  configure: creating makefile fragment in ./frame
  configure: creating makefile fragment in ./frame/1
  configure: creating makefile fragment in ./frame/1/axpyv

By default, BLIS is configured so that later on, when you run 'make install',
the library and header files will be installed in $(HOME)/blis. If you want
them to be installed somewhere else, use the '-p <PREFIX>' option, where
<PREFIX> is the path to which you want to install:

  > ./configure -p /some/other/path <configname>

Note that 'configure' will create a 'lib' and 'include-<id>' directory inside
<PREFIX> if they do not already exist, as well as some symbolic links for
convenient references in application makefiles. (Here, <id> is an identifier
consisting of the BLIS distribution's version number and the configuration
name you chose in step 1.)

For more help information, run 'configure' with the '-h' option:

  > ./configure -h



STEP 3: COMPILATION

Now your BLIS configuration is ready to be compiled into a library:

  > make

Running make will result in output similar to:

  Compiling frame/1/axpyv/bl2_axpyv.c
  Compiling frame/1/axpyv/bl2_axpyv_check.c
  Compiling frame/1/axpyv/bl2_axpyv_unb_var1.c
  Compiling frame/1/copynzv/bl2_copynzv.c
  Compiling frame/1/copynzv/bl2_copynzv_check.c
  Compiling frame/1/copynzv/bl2_copynzv_unb_var1.c
  Compiling frame/1/copyv/bl2_copyv.c
  Compiling frame/1/copyv/bl2_copyv_check.c

If you want to see the individual compiler invocations, edit your
configuration's make_defs.mk to contain:

  BLIS_ENABLE_VERBOSE_MAKE_OUTPUT=yes

or, you can override that value from the command line:

  > make BLIS_ENABLE_VERBOSE_MAKE_OUTPUT=yes

Also, if you are compiling on a multicore system, you can get parallelism
via:

  > make -j<n>

where <n> is the number of parallel jobs to run. You should typically limit
<n> to p+1, where p is the number of processor cores on your system.



STEP 4: INSTALLATION

Toward the end of compilation, you should get output similar to:

  Compiling frame/util/randv/bl2_randv.c
  Compiling frame/util/randv/bl2_randv_unb_var1.c
  Compiling frame/util/sets/bl2_sets.c
  Compiling frame/base/noopt/bl2_dlamch.c (NOTE: optimizations disabled)
  Compiling frame/base/noopt/bl2_lsame.c (NOTE: optimizations disabled)
  Compiling frame/base/noopt/bl2_slamch.c (NOTE: optimizations disabled)
  Archiving lib/reference/libblis.a

Now you have a BLIS library sitting in 'lib/<configname>/'. To install it and
the header files associated with it, simply execute:

  > make install

This not only installs copies of the library and header files, but also
creates convenient symbolic links:

  Installing libblis-0.1.0-reference.a into /home/field/blis/lib/
  Installing C header files into /home/field/blis/include-0.1.0-reference
  Installing symlink libblis.a into /home/field/blis/lib/
  Installing symlink include into /home/field/blis/

This results in your <PREFIX> directory looking like:

  > ls -l /home/field/blis
  lrwxrwxrwx 1 field dept    29 Dec  6 14:19 include -> include-0.1.0-reference
  drwxr-xr-x 2 field dept 32768 Dec  6 14:19 include-0.1.0-reference
  drwxr-xr-x 2 field dept  4096 Dec  6 14:19 lib
  > ls -l /home/field/blis/lib
  -rw-r--r-- 1 field dept 3919726 Dec  6 14:19 libblis-0.1.0-reference.a
  lrwxrwxrwx 1 field dept      31 Dec  6 14:19 libblis.a -> libblis-0.1.0-reference.a

If you were to build a new configuration or version of BLIS and install that,
'make' would update your symbolic links automatically. This means that simply
you don't need to use unwieldy names such as 'libblis-0.1.0-reference.a'.
Linking to 'libblis.a' and including '<PREFIX>/include' in your application's
makefile will always pull in the BLIS library and headers that were most
recently installed.


CONCLUSION

That's it! The BLIS framework's build system adheres to the familiar
"./configure; make ; make install" build process that many of us are
used to.

If you have feedback, please consider keeping in touch with the project
maintainers, contributors, and other users by joining and participating
in the BLIS mailing lists (see the README for details).

Thanks for using BLIS!

Field Van Zee