← Back to branch summary

~ubuntu-branches/ubuntu/vivid/atlas/vivid

« back to all changes in this revision

Viewing changes to INSTALL.txt

  • Committer: Package Import Robot
  • Author(s): Sébastien Villemot, Sylvestre Ledru, Sébastien Villemot
  • Date: 2013-06-11 15:58:16 UTC
  • mfrom: (1.1.4) (25 sid)
  • mto: This revision was merged to the branch mainline in revision 26.
  • Revision ID: package-import@ubuntu.com-20130611155816-8xeeiziu1iml040c
Tags: 3.10.1-1
http://bugs.debian.org/609287
http://bugs.debian.org/602524
http://bugs.debian.org/701921
http://bugs.debian.org/666203
http://bugs.debian.org/701068
http://bugs.debian.org/697431
[ Sylvestre Ledru ]
* New upstream release (Closes: #609287)

[ Sébastien Villemot ]
* Provide architectural defaults (i.e. precomputed timings) for all
  release archs (except armel and mips for the time being, due to slow
  porterboxes). This will make the package build much faster and should
  eliminate transient build failures due to excessive variance in the
  timings.
* Move symlinks for lib{cblas,f77blas,atlas,lapack_atlas} out of the
  libblas.so.3 alternative and make them always present, so that
  software relying on these libs do not break when another alternative
  is selected for BLAS
* ATLAS now has improved ARM support with native asm constructs. This required
  the following tunes:
  + armel-is-v4t.diff: new patch, prevents FTBFS on armel; otherwise,
    ATLAS uses asm constructs too recent for the platform (armel is only v4t)
  + debian/rules: on armhf, define the ATL_ARM_HARDFP flag; otherwise the asm
    constructs use the soft-float ABI for passing floating points
  + on armhf, ensure that -mfloat-abi=softfp and -mcpu=vfpv3 flags are never
    used; this is implemented via a patch (armhf.diff) and by the use of fixed
    archdefs
* The generic package is now built without multi-threading, because otherwise
  the package fails to build on some single-processor machines (this required
  the introduction of a patch: fix-non-threaded-build.diff). As a side effect,
  the build of the custom package gracefully handles non-threaded
  builds. (Closes: #602524)
* Add libblas.a as slave in the libblas.so alternative (Closes: #701921)
* Add symlinks for lib{f77blas,atlas}.a in /usr/lib (Closes: #666203)
* Modify shlibs file of libatlas3-base, such that packages using
  libblas/liblapack depend on any BLAS/LAPACK alternative, while packages
  depending on ATLAS-specific libraries (e.g. libatlas.so) depend specifically
  on libatlas3-base.
* corei1.diff: remove patch, applied upstream
* Use my @debian.org email address
* Remove obsolete DM-Upload-Allowed flag
* Switch VCS to git
* Remove Conflicts/Replaces against pre-squeeze packages
* libatlas-base-dev now provides libblas.so, as libblas-dev
* No longer use -Wa,--noexecstack in CFLAGS, it makes the package FTBFS
* Do not use POWER3 arch for powerpcspe port (Closes: #701068)
* Bump to debhelper compat level 9
* README.Debian: mention that devscripts is needed to compile the custom
  package (Closes: #697431)
* Bump Standards-Version to 3.9.4. As a consequence, add Built-Using
  fields because the package embeds stuff from liblapack-pic

Show diffs side-by-side

added added

removed removed

Lines of Context:
INSTALL.txt
13
13
 
14
14
If you are a Windows user please read ATLAS/doc/Windows.txt before proceeding.
15
15
 
16
 
If you are used to the old build process, note that ATLAS's build mechanism
17
 
changed significantly starting with ATLAS3.7.12, to make it more like gnu
18
 
configure.
19
 
 
20
16
There are two mandatory steps to ATLAS installation (config & build), as
21
17
well as three optional steps (test, time, install) and these steps are
22
18
described in detail below.  For the impatient, here is the basic outline:
37
33
                   NOTE ON BUILDING A FULL LAPACK LIBRARY
38
34
 
39
35
********** Important Install Information: CPU THROTTLING ***********
40
 
Most OSes (including Linux) now turn on CPU throttling for power managment
 
36
Most OSes (including Linux) now turn on CPU throttling for power management
41
37
**even if you are using a desktop**.  CPU throttling makes pretty much all
42
38
timings completely random, and so any ATLAS install will be junk.  Therefore,
43
39
before installing ATLAS, turn off CPU throttling.  For most PCs, you can
50
46
regardless if which cpu you specify.  I suspect this is a bug, because on
51
47
earlier systems, the remaining CPUs were controlled via a logical link to
52
48
/sys/devices/system/cpu/cpu0/.  In this case, the only way I found to force
53
 
the second processor to also run at its peak frequence was to issue the
 
49
the second processor to also run at its peak frequency was to issue the
54
50
following as root after setting CPU0 to performance:
55
51
   cp /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor \
56
52
      /sys/devices/system/cpu/cpu1/cpufreq/scaling_governor
 
53
 
 
54
For non-broken systems, you instead issue the above command with -c <#> appended
 
55
to change the performance of each core in turn.  For example, to speedup both
 
56
processors of a dual system you would issue:
 
57
     /usr/bin/cpufreq-selector -g performance -c 0
 
58
     /usr/bin/cpufreq-selector -g performance -c 1
 
59
 
 
60
On Kubuntu, I had problems with this not working because scaling_max_freq
 
61
was set to the minimal speed.  To fix, I had to first increase the max scaling
 
62
frequency, which you can do (as root) by (where <#> below is replaced by each processor
 
63
number eg., 0 and 1 for dual processor system):
 
64
   cd /sys/devices/system/cpu/cpu<#>/cpufreq
 
65
   cp cpuinfo_max_freq scaling_max_freq
 
66
 
 
67
In Kubuntu 9.10, the only fix I found was to issue:
 
68
   sudo echo "performance" > \
 
69
        /sys/devices/system/cpu/cpuX/cpufreq/scaling_governor
 
70
Where 'X' is replaced by each of your cpu numbers in turn (eg., if you have
 
71
a quad processor, you would issue this command four times, using X=[0,1,2,3]).
 
72
 
57
73
Under MacOS or Windows, you may be able to change this under the power settings.
 
74
I have reports that issuing "powercfg /q" in cmd.exe under windows will tell
 
75
you whether windows is throttling or not.
58
76
 
59
77
ATLAS config tries to detect if CPU throttling is enabled, but it may not
60
78
always detect it, and sometimes may detect it after you have disabled it.
81
99
to force 64 bit libraries (must be using a 64 bit-capable compiler on a
82
100
64-bit Operating System).
83
101
 
 
102
If the machine you are using is not heavily loaded, then you can vastly
 
103
improve the accuracy of ATLAS's timings by using the wall timer rather
 
104
than the CPU timer.  If you are on a x86, you can get cycle accurate timings
 
105
by throwing the flag:
 
106
   -D c -DPentiumCPS=<your Mhz>
 
107
 
 
108
So, for my 2.4Ghz machine, I would specify:
 
109
   -D c -DPentiumCPS=2400
 
110
 
 
111
Under Linux, you can find a decent estimate of your clock rate by
 
112
   cat /proc/cpuinfo
 
113
 
 
114
If you can't use the cycle-accurate wall timer, the normal WALL timer
 
115
is still much more accurate than the CPU timer, and you can use it by
 
116
adding this to configure:
 
117
   -D c -DWALL
 
118
 
84
119
************ Important Compiler Advice **************
85
120
For most systems, ATLAS defaults to using the Gnu compiler collection for
86
 
its ATLAS install.  This means configure will automotically search for
 
121
its ATLAS install.  This means configure will automatically search for
87
122
either g77/gcc or gfortran/gcc.  If it can't find them, it will typically
88
123
stop with an error message.  For some platforms, ATLAS knows good flags
89
124
to use for multiple compilers, and so you may get good flags by simply
98
133
instead.  Note that the fortran interface to BLAS and LAPACK cannot be built
99
134
without a fortran compiler.
100
135
 
101
 
You typically must build ATLAS's interface routines with the compiler that
102
 
you use to do the linking, so that the proper libraries can be found.  We
103
 
just discussed how to override the fortran choice; if you use a C compiler
104
 
that does not seamlessly interoperate with gcc, you may need to override
105
 
the C compiler as well.  Overriding all of ATLAS's C compilers will typically
106
 
mean you can't use the architectural defaults, which will greatly increase
107
 
your install time and will potentially decrease your performance by a large
108
 
amount.  Therefore, it is usually advised to only override the C interface
109
 
compiler, leaving the kernel routines to be compiled by the default C compiler
110
 
(usually gnu gcc).  To override the C interface compiler, simply add these
111
 
flags to your configure invocation:
112
 
   -C ic <C compiler with path>  -F ic 'C compiler flags'
113
 
 
114
136
Note that all compilers used in an ATLAS install must be able to interoperate.
115
137
For more compiler-controlling flags, add --help to the configure command.
116
138
 
117
 
*********** Important x86 Compiler Advice ***********
118
 
If you are on an x86 and are using gcc 4.1, you should be aware that gcc 4.1
119
 
produces x87 code that gets performance of between 56-75% of the code produced
120
 
by gcc 3 (i.e. gcc3-produced code is almost twice as fast as gcc4's) depending
121
 
on the architecture.  From our own timings, gcc 4.2 is superior to either
122
 
4.1 or 3.  Gcc 4.1 produces adequate performance only on Intel Core
123
 
machines.  See ATLAS/doc/atlas_install.pdf for further details.
 
139
*********** Important CLANG Compiler Advice ***********
 
140
I have never succesfully built ATLAS with clang.  Clang produces the wrong
 
141
answer on many kernels, and poorer performance than gcc on every kernel
 
142
I've timed.  I strongly recommend GNU gcc over Clang/LLVM.
124
143
 
125
144
********************************** BUILD **************************************
126
145
If config finishes without error, start the build/tuning process by:
130
149
Install times vary widely, depending on whether ATLAS has architectural
131
150
defaults for your platform, and the speed of your compiler and computer.
132
151
Under gcc/linux, an install may take as little as 15 minutes for all four
133
 
types/precisions.  Under IRIX using SGI's rather slow (but high performance)
134
 
compilers, the install might take as long as four hours.  1-2 hours is probably
135
 
fairly typical.  However, the user is not required to enter any input during
136
 
the install phase, and all operations are logged, so it is safe to start the
 
152
types/precisions.  On a slow machine lacking architectural defaults, it
 
153
However, the user is not required to enter any input during
 
154
the build phase, and all operations are logged, so it is safe to start the
137
155
install and ignore it until completion.
138
156
 
139
157
If you experience problems, read the TROUBLESHOOTING section in
195
213
Note that the "Error 1 (ignored)" is coming from grepping for failure, and
196
214
grep is saying it doesn't find any . . .
197
215
 
 
216
Assuming you have a fortran compiler, you can also run the full ATLAS
 
217
testing scripts, which may take over a day to run.  If you have
 
218
installed a full LAPACK library, you can also run the standard LAPACK
 
219
testers.  Please see "EXTENDED ATLAS TESTING" below for more information.
198
220
 
199
221
******************* INSTALLING ATLAS FOR MULTIPLE ARCHITECTURES ***************
200
222
You can install ATLAS from the same source tree on multiple machines at once
204
226
ATLAS natively builds to a static library (i.e. libs that usually end in
205
227
".a" under unix and ".lib" under windows).  ATLAS always builds such a library,
206
228
but it can also optionally be requested to build a dynamic/shared library
207
 
(typically ending in .so for unix or .dll windows).  In order to do so, you
208
 
must tell ATLAS up front to compile with the proper flags  (the same is
209
 
true when building netlib's LAPACK, see the LAPACK note below).  Assuming
210
 
you are using the gnu C and Fortran compilers, you can add the following
211
 
commands to your configure command:
212
 
   -Fa alg -fPIC
213
 
to force ATLAS to be built using position independent code (required for a
214
 
dynamic lib).  If you use non-gnu compilers, you'll need to use -Fa to
 
229
(typically ending in .so for unix or .dll windows and .dylib for OS X).
 
230
To do this for GNU compilers, you typically just need to add
 
231
   --shared
 
232
flag to your configure line.
 
233
If you use non-gnu compilers, you'll need to use -Fa to
215
234
pass the correct flag(s) to append to force position independent code for
216
235
each compiler (don't forget the gcc compiler used in the index files).
217
236
NOTE: Since gcc uses one less int register when compiling with this flag, this
218
237
      could potentially impact performance of the architectural defaults,
219
238
      but we have not seen it so far.
220
239
 
221
 
After you build is complete, you can cd to the OBJdir/lib directory, and
222
 
ask ATLAS to build the .so you want.  If you want all libraries, including
223
 
the Fortran77 routines, the target choices are :
224
 
   shared    : Create shared versions of ATLAS's sequential libs
225
 
   ptshared  : Create shared versions of ATLAS's threaded libs
226
 
If you want only the C routines (eg. you don't have a fortran compiler):
227
 
   cshared   : Create shared versions of ATLAS's sequential libs
228
 
   cptshared : Create shared versions of ATLAS's threaded libs
229
 
 
230
240
****************** NOTE ON BUILDING A FULL LAPACK LIBRARY *********************
231
 
If you want to build a full LAPACK library, you must obtain and build
232
 
netlib's LAPACK library (ATLAS provides only a few lapack routines natively).
233
 
For the routines ATLAS does not provide natively, you will therefore only have
234
 
the Fortran77 interface (ATLAS's native lapack routines have both F77 and C
235
 
interfaces).  Install LAPACK first (minimally, doing a "make lib" after
236
 
editing the make.inc for your system).
237
 
  IMPORTANT NOTE: if you wish to build a dynamic library, remember to specify
238
 
    -fPIC (assuming gfortran/g77) for both the OPTS and NOOPT macros of
239
 
    lapack's make.inc!!
240
 
 
241
 
Once the library is built, you have to tell ATLAS to use it during the
242
 
configure, which you do by adding the following flag to configure:
243
 
   --with-netlib-lapack=<path to lapack>
244
 
(eg. --with-netlib-lapack=/home/whaley/LAPACK3.0/lapack_LINUX.a).
245
 
 
246
 
If you want to add lapack symbols to a previously built ATLAS, see
247
 
ATLAS/doc/LibReadme.txt for further info.
 
241
To build lapack, first download the lapack tarfile from
 
242
   www.netlib.org/lapack
 
243
Then, pass the flag to configure:
 
244
   --with-netlib-lapack-tarfile=/path/to/downloaded/tarfile
 
245
 
 
246
***************************** EXTENDED ATLAS TESTING **************************
 
247
ATLAS has two extended testers beyond the sanity checks that can be
 
248
automatically invoked from the BLDdir.  These tests are longer running and
 
249
more complex to interpret than the sanity tests, and so not every user will
 
250
want to run them.  They are particularly recommended for installers who wish
 
251
to use a developer release for production code.
 
252
 
 
253
--------------------------------- full_test -----------------------------------
 
254
The first is a set of testing scripts written by Antoine Petitet, that
 
255
randomly generate testcases for a host of ATLAS's testers.  This testing
 
256
phase may take as long as two days to complete (and almost always takes
 
257
at least 4 hours).  To perform this long-running test, simply issue:
 
258
   make full_test
 
259
If you are logged into the host machine remotely, chances are good your
 
260
connection will go down before the install completes.  Therefore, you
 
261
should consider running the above command with nohup.
 
262
 
 
263
At the completion of the tests, the extensive output files will be searched
 
264
for errors (much as with the sanity tests), and the output sent to the screen.
 
265
If you have lost this screen of data, you can regenerate it with the command:
 
266
   make scope_full_test
 
267
 
 
268
Running these tests will create a directory BLDdir/bin/AtlasTest where the
 
269
tester resides, and your output files will be stored a $(ARCH) subdir.
 
270
If you want to rerun the testers from scratch (rather than just searching
 
271
old output), you can simply delete the entire BLDdir/bin/AtlasTest
 
272
directory tree, and do "make full_test" again.
 
273
 
 
274
----------------------------- lapack_test -------------------------------------
 
275
If you have installed the full LAPACK library, then you can run the standard
 
276
lapack testers as well.  The command you give is:
 
277
   make lapack_test_[a,s,f]l_[ab,sb,fb,pt]
 
278
The first choice (choose one of three) controls which LAPACK library macro is
 
279
used in the link for testing:
 
280
 
 
281
   _l    LINK FOR LAPACK       Make.inc MACRO
 
282
   ==    ===================   ==============
 
283
   a     ATLAS's LAPACK        $(LAPACKlib)
 
284
   s     system LAPACK         $(SLAPACKlib)
 
285
   f     F77 reference LAPACK  $(FLAPACKlib)
 
286
 
 
287
The second choice (choose one of three) controls which BLAS macros are
 
288
used in the link for testing:
 
289
  _b/pt  LINK FOR BLAS           Make.inc MACRO
 
290
  ====   =====================   =========================================
 
291
  ab     ATLAS BLAS              $(F77BLASlib) $(CBLASlib) $(ATLASlib)
 
292
  sb     system BLAS             $(BLASlib)
 
293
  fb     F77 reference BLAS      $(FBLASlib)
 
294
  pt     ATLAS' threaded BLAS    $(PTF77BLASlib) $(PTCBLASlib) $(ATLASlib)
 
295
 
 
296
Not all of these combinations will work without user modification of Make.inc.
 
297
You will need to fill in values for
 
298
   $(BLASlib)
 
299
   $(SLAPACKlib)
 
300
   $(FLAPACKlib)
 
301
if you want to run the lapack tester against these libraries.
 
302
 
 
303
Usually, you will want to test your newly install ATLAS LAPACK & BLAS:
 
304
   make lapack_test_al_ab
 
305
 
 
306
As before, once the testing is complete, you will get the output of a search
 
307
for errors though all output files, and you can search them again with:
 
308
   make scope_lapack_test_al_ab
 
309
 
 
310
Unfortunately, the lapack testers always show errors on almost all platforms.
 
311
So, how do you know if you have a real error?  Real errors will usually
 
312
have residuals in the 10^6 range, rather than O(1) (smaller residuals mean
 
313
less error).  If you are unsure, the best way is to contrast ATLAS with an
 
314
all-F77 install:
 
315
   make lapack_test_fl_fb
 
316
(To run this test, you will have to build a stock netlib LAPACK library,
 
317
and fill out Make.inc's FLAPACKlib macro appropriately.)  You can then see
 
318
how the errors reported by ATLAS stack up against the all-F77 version:
 
319
if they  are roughly the same, then you are usually OK.
 
320
 
 
321
All the lapack testers create a directory BLDdir/bin/LAPACK_TEST.  For
 
322
each test you run there will be a subdirectory
 
323
   LAOUT_[A,S,F]L_[AB,SB,FB,PT]
 
324
where all your output files will be located.  Additionally, the results
 
325
of the scope (search for error) will be stored in
 
326
   BLDdir/bin/LAPACK_TEST/SUMMARY_<lapack>_<blas>
 
327
 
 
328
Therefore, a typical round of testing might be:
 
329
   make lapack_test_al_ab
 
330
   make lapack_test_fl_fb
 
331
   # compare SUMMARY_al_ab with SUMMARY_fl_fb to check for error
 
332
   make lapack_test_al_pt
 
333
   # compare SUMMARY_al_pt with SUMMARY_fl_fb to check for error in parallel lib
 
334
 
 
335
If you had an error, you might want to be sure the error was in ATLAS's BLAS
 
336
and not lapack, so you could do "make lapack_test_fl_ab", and see if the
 
337
error went away.  If you filled in the GotoBLAS for the SLAPACKlib & BLASlib
 
338
macros, you could scope the error properties of Goto's BLAS and LAPACK.
 
339
Many system/vendor LAPACK/BLAS do not provide all of the routines required
 
340
to run the LAPACK testers, and some ATLAS testers call ATLAS internal
 
341
routines.  Therefore, the safest thing if you have missing symbol errors
 
342
when building system/vendor tests, is to use ATLAS to pick up any missing
 
343
symbols.  For instance, here is an example Make.inc output that makes all of
 
344
ATLAS testers work with the GotoBLAS on my Athlon-64 workstation:
 
345
   BLASlib = /opt/lib/libgoto_opteronp-r1.26.a \
 
346
             $(F77BLASlib) $(CBLASlib) $(ATLASlib)
 
347
   SLAPACKlib = /opt/lib/libgoto_opteronp-r1.26.a $(FLAPACKlib)
 
348
 
248
349