From b0ecd0ff52fa6ffc9e1d9eb44c365f7f009a6204 Mon Sep 17 00:00:00 2001 From: "Field G. Van Zee" Date: Thu, 6 Dec 2012 14:27:11 -0600 Subject: [PATCH] Wrote first draft of INSTALL file. --- INSTALL | 244 +++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 235 insertions(+), 9 deletions(-) diff --git a/INSTALL b/INSTALL index f7422377c0..2c194042cd 100644 --- a/INSTALL +++ b/INSTALL @@ -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 + +where is the configuration sub-directory name you chose in +step 1. If 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 ' option, where + is the path to which you want to install: + + > ./configure -p /some/other/path + +Note that 'configure' will create a 'lib' and 'include-' directory inside + if they do not already exist, as well as some symbolic links for +convenient references in application makefiles. (Here, 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 + +where is the number of parallel jobs to run. You should typically limit + 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//'. 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 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 '/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 + +