Installation¶
Installation Contents¶
Compiling O2scl on Ubuntu with Snap¶
The easiest way to install on Ubuntu is with snap (see https://snapcraft.io/o2scl). Use:
sudo snap install (--edge or --beta) --devmode o2scl
The snap installation includes HDF5 support, the O2scl_part and O2scl_eos sub-libraries, readline support, and uses the GSL CBLAS.
Using the command-line utility acol
may require you to set the
environment variable LD_LIBRARY_PATH
. For example, on machines
where I use snap to install in my .bashrc
, I use:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/snap/o2scl/current/usr/lib/x86_64-linux-gnu:/snap/o2scl/current/lib/x86_64-linux-gnu
Compiling O2scl on Mac OSX with Homebrew¶
The easiest way to install on Mac OSX is with homebrew. Use:
brew tap awsteiner/science
brew install o2scl
to install O2scl. There are a few options for brew
install
. The option --with-check
performs the build-time tests
and the option --with-examples
double checks that the examples can
also be compiled and executed. The homebrew recipe for O2scl uses the Mac OS X compiler clang. Homebrew also supports the
installation of the current version directly from the repository using
the --HEAD
option to brew install
. The homebrew installation
includes the O2scl_part and O2scl_eos
sub-libraries and readline support. The O2scl homebrew
recipes are stored at the
https://github.com/awsteiner/homebrew-science repository.
(By default, a homebrew installation of O2scl uses the OSX LLVM
compiler. However, a homebrew installation of O2scl will also
install gcc
because O2scl requires hdf5
, and the homebrew
hdf5
package requires gcc
. The homebrew installation of
O2scl is tested by Travis CI.)
Compiling O2scl from a release distribution¶
O2scl installation is generally similar to that for
GNU-style libraries. The file INSTALL
has some details on this
procedure. Once the dependencies are installed you should be able to
run ./configure
and then type make
and make install
. More
information on the configure
command can also be obtained from
./configure --help
. O2scl assumes some C++11 support,
so compilation may be more difficult on compilers released before
about 2018. The ./configure
script attempts to determine the
proper compiler flags for C++11 support, e.g. -std=gnu++11
. If
this fails, you may have to add the proper C++11 flag to the
CXXFLAGS
environment variable manually before the ./configure
script. The documentation is included in the O2scl release
distribution and automatically installed by make install
.
Note
If you are trying to install O2scl with a version of
HDF5 earlier than 1.12 you will need to compile with
-DO2SCL_HDF5_PRE_1_12
.
O2scl requires the Boost (any relatively recent version)
and the GSL libraries (version 2.0 or later). If the
configure
script cannot find Boost or GSL, you may have to
specify their location for the associated header files in the
CXXFLAGS
variable and the associated libraries in the
LDFLAGS
environment variable. Running ./configure
--help
shows some information on this. For example, in a bash
shell, you could do something like:
CXX="g++" CXXFLAGS="-I/dir/to/gsl/include" LDFLAGS="-L/dir/to/gsl/libs" ./configure --prefix=="/dir/to/destination_directory
Along with GSL, a CBLAS library is also required, and ./configure
will look for libcblas
first, and if not found then it will look
for libgslcblas
. If neither is present, then you may have to
manually specify a CBLAS library using the LIBS
and LDFLAGS
environment variables.
Compiling with the readline, ncurses, and HDF5 libraries is optional,
but they are assumed to be present by default. To compile without
these libraries, you will need to use the arguments
--disable-readline
, --disable-ncurses
or --disable-hdf
to
./configure
, respectively. Note that HDF5 is currently required
for the physics sub-libraries, so --disable-hdf
should be
accompanied by the --disable-eoslib
and --disable-partlib
flags.
After make install
, you may test the library with make check
or make o2scl-test
. At the end, the phrase "All O2scl tests
passed"
indicates that the testing was successful. You may also run
make o2scl-test
in the individual subdirectories of the src
directory to individually test the classes and functions in that part
of O2scl. The testing code in
src/base/lib_settings_ts.cpp
can be useful in finding out how O2scl was compiled. After make o2scl-test
, running
src/base/lib_settings_ts
will output several of the installation
settings. If HDF5 is enabled, acol -v
also outputs the
installation settings.
O2scl uses Travis CI (see https://travis-ci.org/awsteiner/o2scl ) to ensure that compilation and testing works on standard Ubuntu and Mac OS X environments.
Compiling O2scl from a release on Linux¶
For example, to install O2scl on Ubuntu, begin by
installing g++ and make (the g++
and make
packages),
GSL (the libgsl-dev
package), Boost (the
libboost-all-dev
package), GNU readline (the libreadline-dev
package), ncurses (the libncurses-dev
packages), and HDF5 the
libhdf5-dev
package). You can then install O2scl from
one of the release distributions by using the standard GNU
./configure
script and then invoking make
and make install
(which sometimes requires sudo
). This installation method is
tested by the Travis CI script.
The HDF5 package for Ubuntu and many other Linux systems is
installed in hdf5/serial/hdf5.h
instead of
hdf5.h
, so O2scl presumes that Linux systems are arranged
that way. If HDF5 include statements should not have the
hdf5/serial/
prefix, then you can use
-DO2SCL_HDF5_PLAIN_HEADER
, i.e.:
CXXFLAGS="-DO2SCL_PLAIN_HDF5_HEADER" ./configure
to instruct O2scl to look for them there (for example, on bridges at
the PSC). On many systems, one can use a parallel HDF5 library
using -DO2SCL_HDF5_PLAIN_HEADER
and a -I
option
to select the proper location for the parallel HDF5 header files.
Finally, if your version of HDF5 is earlier than 1.12,
you will need to let O2scl know, using:
CXXFLAGS="-DO2SCL_HDF5_PRE_1_12" ./configure
Other Linux distributions are similar. For example, in OpenSUSE, you
will need to use zypper
to install gcc-c++, make, gsl-devel,
hdf5-devel, ncurses-devel, readline-devel
, and boost-devel
.
Compiling O2scl from the source code¶
If you want to install from source (without generating the
documentation), then you must first install g++
, make
,
automake
, autoconf
, and libtool
packages. Then you can use
something along the lines of:
git clone https://github.com/awsteiner/o2scl
cd o2scl
mkdir m4
autoreconf -i
./configure
Then, you will either need to generate the documentation from doxygen
using make o2scl-doc
or use make blank-doc
to create blank
documentation. Then you can proceed using make
and make
install
(which may require sudo
depending on your
configuration). For a full installation with parallelism, I
typically also install libopenmpi-dev
and then use
./configure --enable-openmp
Compiling O2scl on Docker¶
There are also some experimental dockerfiles which you can use to install O2scl which can be found at https://github.com/awsteiner/o2scl/tree/main/docker . For those on MacOS, I recommend the guide at https://medium.com/crowdbotics/a-complete-one-by-one-guide-to-install-docker-on-your-mac-os-using-homebrew-e818eb4cfc3 to installing docker.
Optional linear algebra libraries¶
Most classes and functions which require linear algebra can be used
with the Eigen (http://eigen.tuxfamily.org) or Armadillo
(http://arma.sourceforge.net) vector and matrix objects. This can be
specified in the configure
command with --enable-armadillo
or
--enable-eigen
. Note that the O2scl classes which use
Armadillo use matrix decompositions so Armadillo must be compiled with
LAPACK support, and you may need to specify the location of the LAPACK
libraries manually. If you are installing on Mac OS X with homebrew,
the options --with-eigen
and with-armadillo
can be used.
Range-checking¶
Some extra range-checking for vectors and matrices is turned on by default. You can disable range-checking by defining -DO2SCL_NO_RANGE_CHECK, e.g.:
CXXFLAGS="-DO2SCL_NO_RANGE_CHECK" ./configure
Optional physics libraries¶
The separate libraries O2scl_eos and O2scl_part
are installed by default. To disable the installation of these
libraries and their associated documentation, run ./configure
with
the flags --disable-eoslib
or --disable-partlib
. Note that O2scl_eos depends on O2scl_part so using
--disable-partlib
without --disable-eoslib
will not work. Note
also that both O2scl_part and O2scl_eos require
HDF5 support.
More configure flags¶
There are several warning flags that are useful when configuring
and compiling with O2scl. See the GSL documentation for an
excellent discussion, and also see the generic installation
documentation in the file INSTALL
in the O2scl top-level
directory. For running configure
, for example, if you do
not have privileges to write to /usr/local
:
CPPFLAGS="-O3 -I/home/asteiner/install/include" \
LDFLAGS="-L/home/asteiner/install/lib" ./configure \
--prefix=/home/asteiner/install
In this example, specifying -I/home/asteiner/install/include
and
-L/home/asteiner/install/lib
above ensures that the GSL libraries
can be found. The --prefix=/home/asteiner/install
argument to
./configure
ensures that O2scl is installed there as
well.
Generation of documentation¶
The O2scl documentation is generated with doxygen
,
sphinx
, breathe
, and alabaster
and packaged in with every
release file. In principle, the documentation can be regenerated by
the end-user, but this is not supported and requires several external
applications not included in the distribution.
The most recent release documentation is available at
https://neutronstars.utk.edu/code/o2scl/html/index.html and the
current development version documentation is available at
https://neutronstars.utk.edu/code/o2scl-dev/html/index.html . The
documentation for previous releases is not on the web, but is still
stored in the release .tar.gz
file.
Uninstallation¶
While there is no explicit “uninstall” makefile target, there are only
a couple places to check. Installation creates directories named
o2scl
in the include, doc and shared files directory (which
default to /usr/local/include
, /usr/local/share/doc/
, and
/usr/local/share
) which can be removed. The acol
command-line
utility is installed to /usr/local/bin
. Finally, all of the
libraries are named with the prefix libo2scl
and are created by
default in /usr/local/lib
.