mirror of
https://github.com/amd/blis.git
synced 2026-05-11 09:39:59 +00:00
Updated INSTALL file (now redirects to website).
This commit is contained in:
Field G. Van Zee
354
INSTALL
354
INSTALL
@@ -3,354 +3,20 @@ BLIS framework
|
||||
INSTALL
|
||||
---
|
||||
|
||||
INTRODUCTION
|
||||
For a detailed description of how to configure, compile, install, and link
|
||||
to a BLIS library on your local system, please read the build system wiki
|
||||
located at the BLIS project's official website:
|
||||
|
||||
This file contains an abbreviated description of how to configure, compile,
|
||||
and install a BLIS library on your local system.
|
||||
http://code.google.com/p/blis/wiki/BuildSystem
|
||||
|
||||
NOTE: This file is mainly for those of us who are impatient! It is probably
|
||||
out-of-date. If you have time, PLEASE check the BLIS homepage for a wiki
|
||||
page that describes the build process. The BLIS homepage is located at:
|
||||
This document will always contain the most up-to-date information related
|
||||
to instantiating a BLIS library from the framework source code. If you
|
||||
have any further questions or wish to provide feedback, please contact the
|
||||
BLIS community by posting your message to the general user mailing list:
|
||||
|
||||
http://code.google.com/p/blis/
|
||||
https://groups.google.com/d/forum/blis-discuss
|
||||
|
||||
The BLIS build system was designed for use with GNU/Linux (or some other
|
||||
sane UNIX). Other requirements are:
|
||||
|
||||
- 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
|
||||
bli_config.h bli_kernel.h make_defs.mk
|
||||
> cp -r config/reference config/x86-64opt
|
||||
> ls config/x86-64opt
|
||||
bli_config.h bli_kernel.h make_defs.mk
|
||||
|
||||
Then you would edit each of these three files. Here are some special notes
|
||||
about each file:
|
||||
|
||||
o bli_config.h
|
||||
- This is where you specify most of the parameters of your BLIS
|
||||
configuration, including (but not limited to) such things as register
|
||||
and cache blocksizes used by the micro-kernel(s).
|
||||
|
||||
o bli_kernel.h
|
||||
- This file defines C preprocessor macros associated with various kernels
|
||||
and micro-kernels. The reference configuration defines all kernels to
|
||||
use reference implementations (which are provided as part of the BLIS
|
||||
framework). If you end up writing your own optimized kernel for some
|
||||
operation, be sure and enable its use here. Notice that you only have to
|
||||
set ONE definition for each operation, as BLIS prepends s,d,c,z (as well
|
||||
as the BLIS function prefix, currently 'bli_') 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 framework distribution (i.e., in the 'kernels' directory),
|
||||
you MUST add a symbolic link to those kernels to the configuration
|
||||
sub-directory so that 'make' can find and compile the source code. 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
|
||||
bli_config.h bli_kernel.h make_defs.mk
|
||||
> ls ../../kernels
|
||||
x86 x86_64
|
||||
> ln -s ../../kernels/x86_64 kernels
|
||||
> ls
|
||||
bli_config.h bli_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.
|
||||
- If you use the standalone test drivers in the 'test' directory, some of
|
||||
the definitions defined in make_defs.mk (i.e., those used for building
|
||||
the BLIS library instantiation) will also be used when building the
|
||||
test drivers. If you want to use different compilers and/or flags,
|
||||
simply edit test/Makefile so that the correct definitions are used.
|
||||
|
||||
Once you have your configuration sub-directory in place, you are done
|
||||
configuring the framework!
|
||||
|
||||
|
||||
STEP 2: MAKE CONFIGURATION
|
||||
|
||||
This step should be somewhat familiar to many people 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.
|
||||
The exact output will depend on whether you cloned BLIS from a 'git'
|
||||
repository or whether you obtained BLIS via a downloadable release
|
||||
from the BLIS website.
|
||||
|
||||
> ./configure
|
||||
configure: checking whether we need to update the version file.
|
||||
configure: checking version file './version'.
|
||||
configure: found .git directory; assuming git clone.
|
||||
configure: executing git describe --tags.
|
||||
configure: got back 0.1.3-2-g26cb659.
|
||||
configure: truncating to 0.1.3-2.
|
||||
configure: updating version file './version'.
|
||||
configure: starting configuration of BLIS 0.1.3-2.
|
||||
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-<versconf>' directory
|
||||
inside <PREFIX> if they do not already exist, as well as some symbolic links
|
||||
for convenient references in application makefiles. (Here, <versconf> is an
|
||||
identifier consisting of the BLIS distribution's version number and the
|
||||
configuration name you chose in step 1.)
|
||||
|
||||
On last note: for a complete list of supported 'configure' options and
|
||||
arguments, run 'configure' with the '-h' option:
|
||||
|
||||
> ./configure -h
|
||||
|
||||
The output from this invocation of 'configure' should give you an
|
||||
up-to-date list of options and their descriptions.
|
||||
|
||||
|
||||
STEP 3: COMPILATION
|
||||
|
||||
Once 'configure' is finished, you are ready to instantiate (compile) BLIS into
|
||||
a library by running 'make':
|
||||
|
||||
> make
|
||||
|
||||
Running 'make' will result in output similar to:
|
||||
|
||||
Compiling frame/1/axpyv/bli_axpyv.c
|
||||
Compiling frame/1/axpyv/bli_axpyv_check.c
|
||||
Compiling frame/1/axpyv/bli_axpyv_unb_var1.c
|
||||
Compiling frame/1/copynzv/bli_copynzv.c
|
||||
Compiling frame/1/copynzv/bli_copynzv_check.c
|
||||
Compiling frame/1/copynzv/bli_copynzv_unb_var1.c
|
||||
Compiling frame/1/copyv/bli_copyv.c
|
||||
Compiling frame/1/copyv/bli_copyv_check.c
|
||||
|
||||
If you want to see the individual command line invocations of the compiler,
|
||||
edit your configuration's make_defs.mk to contain:
|
||||
|
||||
BLIS_ENABLE_VERBOSE_MAKE_OUTPUT=yes
|
||||
|
||||
or, you can temporarily 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 jobs 'make' is allowed to run simultaneously.
|
||||
Generally, 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/bli_randv.c
|
||||
Compiling frame/util/randv/bli_randv_unb_var1.c
|
||||
Compiling frame/util/sets/bli_sets.c
|
||||
Compiling frame/base/noopt/bli_dlamch.c (NOTE: optimizations disabled)
|
||||
Compiling frame/base/noopt/bli_lsame.c (NOTE: optimizations disabled)
|
||||
Compiling frame/base/noopt/bli_slamch.c (NOTE: optimizations disabled)
|
||||
Archiving lib/reference/libblis.a
|
||||
|
||||
Now you have a BLIS library sitting in the 'lib/<configname>/' directory. To
|
||||
install the library 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.3-2-reference.a into /home/field/blis/lib/
|
||||
Installing C header files into /home/field/blis/include-0.1.3-2-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.3-2-reference
|
||||
drwxr-xr-x 2 field dept 32768 Dec 6 14:19 include-0.1.3-2-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.3-2-reference.a
|
||||
lrwxrwxrwx 1 field dept 31 Dec 6 14:19 libblis.a -> libblis-0.1.3-2-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.3-2-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.
|
||||
|
||||
|
||||
FURTHER DEVELOPMENT TOPCIS
|
||||
|
||||
-- Cleaning out build products --
|
||||
|
||||
If you want to remove various build products, you can use one of the 'make'
|
||||
targets already defined for you in the BLIS Makefile:
|
||||
|
||||
> make clean
|
||||
Removing .o files from ./obj/reference.
|
||||
Removing .a files from ./lib/reference.
|
||||
|
||||
Executing the 'clean' target will remove all binary object files and library
|
||||
builds from the 'obj' and 'lib' directories, respectively. Notice, though,
|
||||
that only object files for the current configuration are removed. Any other
|
||||
configurations' build products are left untouched.
|
||||
|
||||
> make cleanmk
|
||||
Removing makefile fragments from ./config/reference.
|
||||
Removing makefile fragments from ./frame.
|
||||
|
||||
The 'cleanmk' target results in removal of all makefile fragments from the
|
||||
framework source tree. Makefile fragments are also removed from the
|
||||
configuration sub-directory, since the build system also compiles any source
|
||||
code residing there.
|
||||
|
||||
> make distclean
|
||||
Removing makefile fragments from ./config/reference.
|
||||
Removing makefile fragments from ./frame.
|
||||
Removing .o files from ./obj/reference.
|
||||
Removing .a files from ./lib/reference.
|
||||
Removing ./config.mk.
|
||||
Removing ./obj.
|
||||
Removing ./lib.
|
||||
|
||||
Running the 'distclean' target is like saying, "Remove anything ever created
|
||||
by the build system." In addition to invoking 'clean' and 'cleanmk', the
|
||||
'distclean' target removes the 'config.mk' file as well as the top-level 'obj'
|
||||
and 'lib' directories.
|
||||
|
||||
-- Switching configurations --
|
||||
|
||||
The BLIS build system was designed to allow a developer to be working with
|
||||
multiple framework configurations simultaneously. For example, the build
|
||||
system allows you to create a configuration that is oriented towards
|
||||
debugging and then another similar configuration that requests a full slate
|
||||
of optimizations to be applied by the compiler. Or, you might have yet another
|
||||
configuration to test out a new kernel that you just wrote. All of these
|
||||
configurations can co-exist together in the 'config' directory. (The BLIS
|
||||
build system will NEVER delete any of these directories, not even when
|
||||
executing a full clean via 'make distclean'.) And switching between these
|
||||
configurations is easy; simply run './configure <configname>', where
|
||||
<configname> is the configuration you want to switch to. The script will
|
||||
prepare the build system for compiling for that configuration. If you are
|
||||
ever unsure which configuration is "active", simply run:
|
||||
|
||||
> make showconfig
|
||||
Current configuration is 'reference', located in './config/reference'
|
||||
|
||||
This will tell you which configuration is specified by the config.mk file.
|
||||
|
||||
Another benefit to configuration switching is that a previous configuration's
|
||||
object files are saved from the previous build. For example, suppose you
|
||||
configure a configuration named 'debug'. You run 'make' followed by 'make
|
||||
install'. You use that debug-enabled library for a while and then you create
|
||||
a configuration named 'opt', which is the same configuration in optimized
|
||||
form. You compile, install, and test that library. But then you want to return
|
||||
to developing with the 'debug' configuration. Simply run './configure debug'
|
||||
again to switch to the 'debug' configuration. If you haven't run any of the
|
||||
'clean' targets in the interim, the previously created object files for the
|
||||
'debug' configuration will still be there (inside './obj/debug'). If you
|
||||
change a .c source file (not a header file; see "Caveats" section below), you
|
||||
won't have to recompile the whole library. Rather, only the source files that
|
||||
changed since the previous configuration and compilation will need to be
|
||||
recompiled.
|
||||
|
||||
Now, while the object files are "remembered" from previous configurations,
|
||||
the library archives (and headers) are not. So, 'make install' will always
|
||||
re-install the build products after returning to a previous configuration,
|
||||
even if no source files (or header files) changed. We must re-install the
|
||||
libraries unconditionally after switching back to a previous configuration
|
||||
because while the configuration name (e.g., 'debug' or 'opt') might be the
|
||||
same, the installation prefix might have changed. Thus, we must install the
|
||||
build products just in case. But the installation itself is a relatively
|
||||
low overhead task, and so shouldn't be much of a burden to a developer who
|
||||
switches his or her configurations frequently.
|
||||
|
||||
-- Caveats --
|
||||
|
||||
Due to the way the BLIS framework handles header files, *any* change to *any*
|
||||
header file will result in the entire library being rebuilt. This policy is
|
||||
in place mostly out of an abundance of caution. If two or more files use
|
||||
definitions in a header that is modified, and one or more of those files
|
||||
somehow does not get recompiled to reflect the updated definitions, you could
|
||||
end up sinking hours of time trying to track down a bug that didn't ever need
|
||||
to be an issue to begin with. Thus, to prevent developers (including the
|
||||
framework developer(s)) from shooting themselves in the foot with this
|
||||
problem, the BLIS build system recompiles *all* object files if a header
|
||||
file--any header file--is touched.
|
||||
|
||||
|
||||
CONCLUSION
|
||||
|
||||
That's it! While the BLIS framework's build system has some nice features, it
|
||||
essentially 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!
|
||||
Thanks for your interest in the BLIS framework!
|
||||
|
||||
Field Van Zee
|
||||
|
||||
|
||||
Reference in New Issue
Block a user