-
Notifications
You must be signed in to change notification settings - Fork 370
/
INSTALL
235 lines (170 loc) · 8.77 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
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