Permalink
Find file
0e77aef Nov 25, 2016
188 lines (127 sloc) 7.76 KB

Installing Shogun

For certain systems, we offer pre-built packages of Shogun. This is the easiest way to start using it. For other cases, we describe how to build Shogun from source code.

Quicklinks

Ready-to-install packages

Ubuntu ppa

We are working on integrating Shogun with Debian. In the meantime, we offer a our prepackaged ppa. Add this to your system as

$ sudo add-apt-repository ppa:shogun-toolbox/stable
$ sudo apt-get update

Then, install as

$ sudo apt-get install libshogun17

In addition to the latest stable release, we offer nightly builds of our development branch.

Fedora

Shogun is part of Fedora 25. Install as

$ sudo dnf install shogun

Mac

Shogun is part of homebrew-science. Install the latest stable version as

$ sudo brew install shogun

Windows

Shogun natively compiles under Windows using MSVC (experimental). We currently do not support a binary installer. If you are interesting in packaging, documenting, or contributing otherwise, please contact us.

Docker images

You can run Shogun in our own cloud or set up your own using our Docker images as:

$ sudo docker pull shogun/shogun
$ sudo docker run -it shogun/shogun bash

We offer images for both the latest release and nightly development builds.

Sometimes mounting a local folder into the docker image is useful. You can do this via passing an additional option

-v /your/local/folder:/same/folder/in/docker

See the Docker documentation for further details.

Integration with interface language build systems

Shogun is can be automatically built from source from the following langauges.

Python pypi

You can install from pipy. There is limited control over options and it might take a long time as everything is done from scratch.

$ pip install shogun-ml

We do not reccomend this option and suggest to rather compile by hand as described below.

Compiling manually

In case none of the binary packages listed on our website work for your system, or you want to modify Shogun, you will need to build it from source.

Requirements

The standard GNU/Linux tools and Python are minimal requirements to compile Shogun. To compile the interfaces, in addition to swig itself, you will need language specific development packages installed, see interfaces below.

There is a larger number of optional requirements. The output of cmake output lists optional dependencies that were found and not found. If a particular Shogun class is unavailable, this is likely due to an unmet dependency. See our docker configuration file for an example configuration used in our test builds.

You need at least 1GB free disk space. If you compile any interface, roughly 4 GB RAM are need (we are working on reducing this). CCache will massively speed up the compilation process and is enabled by default if installed.

Basics

Shogun uses CMake for its build. The general workflow is now explained. For further details on testing etc, see DEVELOPING.md.

Download the latest stable release source code, or (as demonstrated here) clone the latest develop code. Potentially update submodules

$ git clone https://github.com/shogun-toolbox/shogun.git
$ git submodule update --init

Create the build directory in the source tree root

$ cd shogun
$ mkdir build

Configure cmake, from the build directory, passing the Shogun source root as argument. It is recommended to use any of CMake GUIs (e.g. replace cmake .. with ccmake ..), in particular if you feel unsure about possible parameters and configurations. Note that all cmake options read as -DOPTION=VALUE.

$ cd build
$ cmake [options] ..

Compile

$ make

Install (prepend sudo if installing system wide). Done.

$ make install

Sometimes you might need to clean up your build (e.g. in case of some major changes). First, try

$ make clean

If that does not help, try removing the build directory and starting from scratch afterwards

$ rm -rf build

If you prefer to not run the sudo make install command system wide, you can either install Shogun to a custom location (-DCMAKE_INSTALL_PREFIX=/custom/path, defaults to /usr/local), or even skip make install at all. In both cases, it is necessary to set a number of system libraries for using Shogun, see INTERFACES.md.

Interfaces

The native C++ interface is always included. The cmake options for building interfaces are -DPythonModular -DOctaveModular -DRModular -DJavaModular -DRubyModular -DLuaModular -DCSharpModular etc. For example, replace the cmake step above by

cmake -DPythonModular=ON [potentially more options] ..

The required packages (here debian/Ubuntu package names) for each interface are

  • Python
    • python-dev python-numpy
  • Octave
    • octave liboctave-dev
  • R
    • r-base-core
  • Java
    • oracle-java8-installer, non-standard, e.g. https://launchpad.net/~webupd8team/+archive/ubuntu/java
    • jblas, a standard third party library, https://mikiobraun.github.io/jblas/
  • Ruby
    • ruby ruby-dev, and narray a non-standard third party library, http://masa16.github.io/narray/, install with gem install narray
  • Lua
    • lua5.1 liblua5.1-0-dev
  • C-Sharp
    • mono-devel mono-gmcs cli-common-dev

To use the interfaces, in particular if not installing to the default system-wide location, see INTERFACES.md. See examples below for how to create the examples from the website locally.

Generating examples

All Shogun examples at our website are automatically generated code. You can generate them (plus additional ones) locally (needs cmake switch -DBUILD_META_EXAMPLES=ON)

$ make meta_examples

This requires PLY for Python, package python-ply, and ctags, package ctags. Both source code and potential executables (C++, Java, C-Sharp) are created in build/examples/meta/ when running make.

See INTERFACES.md to run the generated examples and see EXAMPLES.md for more details on their mechanics. See DEVELOPING.md for how the examples are used as tests.

Problems? Got stuck? Found a bug? Help?

In case you have a problem building Shogun, please open an issue on github with your system details, exact commands used, and logs posted as a gist.