-
Notifications
You must be signed in to change notification settings - Fork 370
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
235 additions
and
9 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,9 +1,235 @@ | ||
| To be written. | ||
|
|
||
| discuss: | ||
| - build requirements | ||
| - configuration | ||
| - kernel creation (if applicable) | ||
| - compilation | ||
| - installation | ||
| - linking | ||
|
|
||
| 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 | ||
|
|
||
|
|