Build from source

From Octave
Revision as of 16:20, 10 January 2012 by Crobar (talk | contribs) (→‎Dependencies: Began porting octave build docs to wiki)
Jump to navigation Jump to search

Compiling from source is probably the most effective way of installing Octave on your system. To do this you will require compilers for the following languages:

  • C
  • C++ (ISO)
  • Fortran

The best supported compilers for the job are the GNU Compiler Collection. You will require at least GCC 4.3 or later, although GCC 4.4 or later is recommended.

To compile Octave, you will also need a recent version of GNU Make. You must have GNU Make to compile octave. Octave's Makefiles use features of GNU Make that are not present in other versions of make. GNU Make is very portable and easy to install.

Introduction

Building Octave can be as simple as downloading the source and running the following three commands in your Linux shell:

./configure
make
make install

However, Octave is a complex program with many dependencies. This page details each of the steps, some issues that may arise with each step and the dependencies that Octave either requires, or will use if available.

Dependencies

Octave is a fairly large program with many build dependencies. You may be able to find pre-packaged versions of the dependencies distributed as part of your system, or you may have to build some or all of them yourself.

Tips for Specific Systems

The names of pre-compiled packages vary by system and do not always match exactly the names listed above.

You will usually need the development version of an external dependency so that you get the libraries and header files for building software, not just for running already compiled programs. These packages typically have names that end with the suffix -dev or -devel.

On systems with apt-get (Debian, Ubuntu, etc.), you may be able to install most of the tools and external packages using a command similar to

 apt-get build-dep octave

The specific package name may be octave3.2 or octave3.4, making the command

 apt-get build-dep octave3.2

for example). The set of required tools and external dependencies does not change frequently, so it is not important that the version match exactly, but you should use the most recent one available.

On systems with yum (Fedora, Red Hat, etc.), you may be able to install most of the tools and external packages using a command similar to

 yum-builddep octave

The yum-builddep utility is part of the yum-utils package.

For either type of system, the package name may include a version number. The set of required tools and external dependencies does not change frequently, so it is not important that the version exactly match the version you are installing, but you should use the most recent one available.

Build Tools

The following tools are required:

Tool Description
C++, C, and Fortran compilers The Octave sources are primarily written in C++, but some portions are also written in C and Fortran. The Octave sources are intended to be portable. Recent versions of the GNU compiler collection (GCC) should work ([1]). If you use GCC, you should avoid mixing versions. For example, be sure that you are not using the obsolete @code{g77} Fortran compiler with modern versions of gcc and g++.
GNU Make Tool for building software ([2]). Octave's build system requires GNU Make. Other versions of Make will not work. Fortunately, GNU Make is highly portable and easy to install.
AWK, sed, and other Unix utilities Basic Unix system utilities are required for building Octave. All will be available with any modern Unix system and also on Windows with either Cygwin or MinGW and MSYS.

Additionally, the following tools may be needed:

Tool Description
Bison Parser generator ([3]). You will need Bison if you modify the oct-parse.yy source file or if you delete the files that are generated from it.
Flex Lexer analyzer ([4]). You will need Flex if you modify the lex.ll source file or if you delete the files that are generated from it.
Autoconf Package for software configuration ([5]). Autoconf is required if

you modify Octave's configure.ac file or other files that it requires.

Automake Package for Makefile generation ([6]). Automake is required if you modify Octave's Makefile.am files or other files that they depend on.
Libtool Package for building software libraries ([7]). Libtool is required by Automake.

External Packages

Library Status Debian Package Name Comments
A version of BLAS and LAPACK, e.g. Atlas Required libatlas-base-dev Basic Linear Algebra Subroutine library ([8]). Accelerated BLAS libraries such as ATLAS ([9]) are recommended for better performance.
arpack Recommended libarpack2-dev Library for the solution of large-scale eigenvalue problems ([10]). ARPACK is required to provide the functions eigs and svds.
curl Recommended libcurl4-gnutls-dev Library for transferring data with URL syntax ([11]). cURL is required to provide the urlread and urlwrite functions and the ftp class.
fftw3 Recommended fftw3-dev Library for computing discrete Fourier transforms ([12]). FFTW3 is used to provide better performance for functions that compute discrete Fourier transforms (fft, ifft, fft2, etc.).
fltk Recommended libfltk1.1-dev Portable GUI toolkit ([13]). FLTK is currently used to provide windows for Octave's OpenGL-based graphics functions.
fontconfig Recommended libfontconfig1-dev Library for configuring and customizing font access ([14]). Fontconfig is used to manage fonts for Octave's OpenGL-based graphics functions.
FreeType Recommended Portable font engine ([15]). FreeType is used to perform font rendering for Octave's OpenGL-based graphics functions.
glpk Recommended libglpk-dev GNU Linear Programming Kit ([16]). GPLK is required for the function glpk.
gnuplot Recommended Interactive graphics program ([17]). gnuplot is currently the default graphics renderer for Octave.
GraphicsMagick++ Recommended libgraphicsmagick++1-dev Image processing library (@url{http://www.graphicsmagick.org}). GraphicsMagick++ is used to provide the imread and imwrite. functions.
hdf5 Recommended libhdf5-mpich-dev Library for manipulating portable data files ([18]). HDF5 is required for Octave's load and save commands to read and write HDF data files.
ncurses Recommended libncurses5-dev
OpenGL Recommended API for portable 2D and 3D graphics ([19]). An OpenGL implementation is required to provide Octave's OpenGL-based graphics functions. Octave's OpenGL-based graphics functions usually outperform the gnuplot-based graphics functions because plot data can be rendered directly instead of sending data and commands to gnuplot for interpretation and rendering.
PCRE Required libpcre3-dev The Perl Compatible Regular Expression library ([20]).
Qhull Recommended libqhull-dev Computational geometry library ([21]). Qhull is required to provide the functions convhull, convhulln, delaunay, delaunay3, delaunayn, voronoi, and voronoin.
qrupdate Recommended QR factorization updating library ([22]). QRUPDATE is used to provide improved performance for the functions qrdelete, qrinsert, qrshift, and qrupdate.
readline Strongly
Reccomended
libreadline5-dev If you wish to build Octave without GNU readline installed, you must use the --disable-readline option when running the configure script.
SuiteSparse Recommended libsuitesparse-dev Sparse matrix factorization library ([23]). SuiteSparse is required to provide sparse matrix factorizations and solution of linear equations for sparse systems.
zlib Recommended zlib1g-dev Data compression library ([24]). The zlib library is required for Octave's load and save commands to handle compressed data, including Matlab v5 MAT files.

Download

Released source tarballs are available at http://www.octave.org/download.html. You will normally want to use one of those.

The download page also contains instructions to download the development sources. If you are using the development sources, be sure to type the following command before configuring:

./autogen.sh

This builds the configure scripts that Octave uses. This requires a number of tools which are not needed if you download an octave release, such as recent versions of autoconf/automake, and tools such as bison, flex, gperf, perl, and maybe others.

Configure

Before compiling you must first configure the build system by running the configure script.

./configure

The configure script will display information about missing packages or any other issues that arise during the configuration run.

Octave has many configure options. For a complete list, see

./configure --help

If you are building a personal version, you will want to install it into your home directory, or perhaps a subdirectory. Add the following to your configure line:

--prefix=$HOME/octave

Be sure the $HOME/octave/bin is on your path, or symlink the binaries therein to $HOME/bin.

Troubleshooting

1. If you just type ./configure, you may get this error:

configure: WARNING: in order to build octave, you must have a compatible
configure: WARNING: Fortran compiler or f2c installed and in your path.
configure: error: See the file INSTALL for more information.

This means that you don't have a fortran compiler on your system. You can either install a fortran compiler or re-install gcc with its optional build-in fortran compiler g77. To do this you must download the g77 components of gcc before you build gcc. Alternatively there are various f2c programs you could install which convert fortran to C.

2. If you get this warning:

configure: WARNING: "FTGL headers not found. Native renderer will not have on-screen text"
configure: WARNING:
configure: WARNING: I didn't find the necessary libraries to compile native
configure: WARNING: graphics. It isn't necessary to have native graphics
configure: WARNING: but you will have to use gnuplot or you won't be able
configure: WARNING: to use any of Octave's plotting commands

It may help to call configure with CPPFLAGS=-I/usr/include/freetype2, please see Problems with FTGL building octave-3.1.51,Building ftgl backend with current tip. Note that from changeset 8269 onward, this workaround should no longer be needed, please see No FTGL, says configure script?

Build

After running configure simply run

make

Note that the compilation of Octave can take some time.

Troubleshooting

Another possible error occurs at the 'make' stage:

/usr/include/c++/3.3.1/bits/basic_string.h:228: undefined reference to 
    `std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_S_empty_rep_storage'
collect2: ld returned 1 exit status
make[2]: *** [octave] Error 1

This has something to do with the gcc configuration. Try compiling the following program using g++:

#include <string>
#include <iostream>
using namespace std;
int main (void)
{
  basic_string <char>a = "thing one";
  string b = "thing two";
  cout << a.c_str() << endl;
  return (a == b);
}

If it fails, then your compiler needs to be set-up differently (how?). On my machine I can compile that test program but still get the error making Octave -- how do we solve this? It has something to do with the shared C++ library versions, check for /usr/lib/libstdc++.so.6 and make sure the right version of that library is being used by gcc -- especially if you had to reinstall gcc to build the fortran support. If it still doesn't work, consider installing from the RPMs instead of compiling from source.

Test

To run all tests, change to the octave directory and type

make check

This requires dejagnu.

To run a specific set of tests, change to the directory test/octave.test/<part> and type

runtest <part>.exp

To run your own tests use the RunInPlace shell script.

Install

Finally, to install Octave on your system run

make install

System Specific Instructions

Distributed building

Requirements

distcc
ccache

Install distcc on all machines taking part in the compilation. List them in ~/.distcc/hosts:

localhost
pc1.mynet.org
pc2.mynet.org

The first machines listed are given higher priority -- place 'localhost' as you see fit.

Set the environment variables CCACHE_PREFIX, CXX and CC:

export CCACHE_PREFIX="distcc"
export CXX="ccache g++"
export CC="ccache gcc"
./configure <options>

Compile using the -j<simultaneous-jobs> flag, two jobs per CPU available, i.e. for 5 machines

make -j10