Installation

(Thanks to @wlevine, see #369) In each and every case, you might find a speedup in the compilation time by using more cores. Enable the following flag when using rake:

MAKE="make -j8" rake ...

Linux

Disable CPU throttling

It is necessary to disable CPU throttling to ensure the ATLAS installation goes smoothly. Most likely, you just need to disable any power saving feature. You can install cpupower (or similar) and:

cpupower frequency-set -g performance

Install it on Arch Linux via sudo pacman -Su cpupower.

Note: We should add instructions for more distros, shouldn't we?

Ubuntu

version 13.04 (raring) and NMatrix 0.0.9

sudo apt-get install libatlas-base-dev
sudo apt-get --purge remove liblapack-dev liblapack3 liblapack3gf
[sudo] gem install nmatrix

version 12.04 (precise) with any NMatrix or version 13.04 (raring) and NMatrix < 0.0.9

sudo apt-get install libatlas-base-dev
sudo apt-get --purge remove liblapack-dev liblapack3 liblapack3gf
export CPLUS_INCLUDE_PATH=/usr/include/atlas
export C_INCLUDE_PATH=/usr/include/atlas
[sudo] gem install nmatrix

The order here can make a difference if you have libraries that depend on liblapack installed (e.g. R or numpy). We install the atlas packages first because they will typically satisfy the dependencies of these packages. The environment variables are critical for compilation, but you only need them present during compilation.

If you are getting compile or runtime errors, you may want verify that you have no lapack libraries installed. Just run the following command (may need to install aptitude "sudo apt-get install aptitude"):

# this command should return *NOTHING*!  Uninstall any packages it may return
aptitude search lapack | grep '^i'

Explanation: If you have the liblapack or liblapack-dev packages installed then your compilation (or runtime) will fail because Ubuntu gives preference to clapack.h or the associated .so from liblapack and it doesn't have all the functions necessary for nmatrix to function. So, if you get an error related to clapack_dgetrf, then it's probably because you still have liblapack installed (both the dev and binary need to be uninstalled)!

Tuning your Blas/Lapack (optional)

Follow these instructions. Additional notes:

• You should be inside the outputatlas directory when you run the big configure command.
• 'make install' will fail, so you will need to manually copy over the lib files and make softlinks as directed in link.
• Make sure to adjust your CPLUS_INCLUDE_PATH and C_INCLUDE_PATH accordingly for compilation of nmatrix.
• Make sure you do not have liblapack deb packages installed, as discussed above.

Compiling from source

Assuming you have ATLAS installed (and no lapack packages) as shown above:

git clone https://github.com/SciRuby/nmatrix.git 
# or "git clone [email protected]:SciRuby/nmatrix.git" if you have push privileges
cd nmatrix
gem install bundler  # if you don't already have it
bundle install
export CPLUS_INCLUDE_PATH=/usr/include/atlas  # or wherever your atlas .h files are
export C_INCLUDE_PATH=/usr/include/atlas   # or wherever your atlas .h files are
bundle exec rake compile  # 'clobber' or 'clean' also useful # expect lots of warnings
bundle exec rake spec  # ... => 561 examples, 3 failures, 26 pending
bundle exec ruby -I lib -S irb  # to play around interactively

Validated on ruby 2.0.0-p195 and 1.9.3-p429, 2013-08-08 for nmatrix v0.0.5-37-g0651c75

Troubleshooting

The above instructions should work without fail. If they don't, email me and I'll update them for the current Ubuntu version and current nmatrix.

Advice that has been helpful in the past:

• Some errors may be squelched by setting your locale: LANG="en_US" gem install nmatrix
• If you have compile link head error, please check the libcblas.so, libatlas.so and cblas.h atlas.h file with apt-file tool:

apt-file search xxx.h

Then ln -s with proper path.

Archlinux

You should install the atlas-lapack package from AUR. If you use yaourt:

yaourt atlas-lapack

Or you can get the tarfile from [https://aur.archlinux.org/packages/atlas-lapack/ (https://aur.archlinux.org/packages/atlas-lapack/) and install it manually (untar it, makepkg, sudo pacman -U pkg.tar.xz).

A few notices

Installing atlas-lapack will require removing the packages blas, cblas and lapack, because they are integrated into atlas-lapack.

Mac OS X

Note: We should merge these tutorials into one. How much is really necessary? Is there something we can assume in order to simplify these steps?

Lion 10.7.4

Xcode

Download Xcode from the App Store and run Install Xcode. Run Xcode and open its Preferences pane. Go to the Downloads tab and install Command Line Tools.

Homebrew

You will need Homebrew. Make sure everything's OK with brew doctor.

Upgrade GCC

Check your version of GCC:

gcc -v

If it's less than 4.3, you need to upgrade. First, check the path to the Xcode directory:

xcode-select -print-path

Check if that directory exists. If not, you will need to run something like:

sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer

Otherwise, you will see the following error when compiling:

Error: No developer directory found at /Developer. Run /usr/bin/xcode-select to update the developer directory path.

You can now install a newer GCC using this script that's part of NMatrix, or use Homebrew below:

brew install https://raw.github.com/Homebrew/homebrew-dupes/master/gcc.rb

/usr/bin/gcc and /usr/bin/g++ should be symlinks. Point them to the newer version:

sudo ln -nfs /usr/local/bin/gcc-4.7 /usr/bin/gcc
sudo ln -nfs /usr/local/bin/g++-4.7 /usr/bin/g++

These are the paths where Homebrew installs gcc binaries. If you used the script included with NMatrix, the symlinks are as follows:

sudo ln -nfs /usr/gcc-4.7.2/bin/gcc-4.7.2 /usr/bin/gcc
sudo ln -nfs /usr/gcc-4.7.2/bin/g++-4.7.2 /usr/bin/g++

Compile NMatrix

Clean up any previous attempts to compile:

rake clean

We want to include cblas.h but not clapack.h. Both are in /System/Library/Frameworks/Accelerate.framework/Versions/Current/Frameworks/vecLib.framework/Versions/Current/Headers/, so we can't just set C_INCLUDE_PATH and CPLUS_INCLUDE_PATH. Instead, create a symlink:

sudo ln -s /System/Library/Frameworks/Accelerate.framework/Versions/Current/Frameworks/vecLib.framework/Versions/Current/Headers/cblas.h /usr/include/cblas.h

Unset environment variables, in case you had previously set them:

unset C_INCLUDE_PATH
unset CPLUS_INCLUDE_PATH

Now you can compile NMatrix:

git clone https://github.com/SciRuby/nmatrix.git
cd nmatrix
bundle
bundle exec rake compile

If that worked, you can install it (N is the current version number):

bundle exec rake repackage
gem install pkg/nmatrix-0.0.N.gem

If you receive an error similar to the following when trying to require the library:

$ irb
> require 'nmatrix'
LoadError: dlopen(...):
Symbol not found: _clapack_cgetrf

Try to compile and install the gem with the option --with-lapacklib:

bundle exec rake clean
bundle exec rake compile -- --with-lapacklib
bundle exec rake spec
bundle exec rake repackage
gem install pkg/nmatrix-0.0.N.gem -- --with-lapacklib

See #34 if you have any issues.

Mountain Lion 10.8.2

Follow the instructions below from 10.7.4, with the following alterations:

1. Change the last uncommented line in the script from make install to sudo make install. You will need to enter your password when prompted

2. You will need to recompile ruby with the new gcc. This is very important!

3. If you are using ruby-build or rbenv-install and you have errors recompiling ruby with the new compiler, you have two options:

4. One solution is found here.

5. Read this issue. You can work around it by commenting out the following lines in the ruby-build script:

if type clang &>/dev/null; then
  if "${CC:-clang}" -x c /dev/null -E -Wno-error=shorten-64-to-32 &>/dev/null; then
    RUBY_CFLAGS="$RUBY_CFLAGS -Wno-error=shorten-64-to-32"
  fi
fi

Now it should install fine!

Mavericks 10.9

The directions for Mavericks are basically the same as for other Mac OS X versions. It has been reported that you may also need to create a symbolic link to libatlas.dylib, liblapack.dylib and libclapack.dylib:

IMPORTANT: libatlas.dylib is present only in the Mac OSX SDK until version 10.8, not in 10.9+. Thus you might have to install XCode 5.1.1 if you have a newer model or if you updated XCode recently. After that, point your libatlas symlink to that other XCode installation.

ln -s /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk/usr/lib/libatlas.dylib /usr/lib/libatlas.dylib
ln -s /System/Library/Frameworks/Accelerate.framework/Versions/A/Frameworks/vecLib.framework/Versions/A/libLAPACK.dylib /usr/lib/liblapack.dylib
ln -s /System/Library/Frameworks/Accelerate.framework/Versions/A/Frameworks/vecLib.framework/Versions/A/libLAPACK.dylib /usr/lib/libclapack.dylib

Notes

• There is a bug with backports 3.6.0 and Ruby 2.1.x -- in close': Bad file descriptor @ fptr_finalize. The fix is to update the gem to 3.6.3+ via bundle update backports`.