# Installing VariKN

## Table of contents

- [Requirements for source installs](#requirements-for-source-installs)
  - [How to install MacOsX requirements](#how-to-install-macosx-requirements)
  - [How to install Linux requirements](#how-to-install-linux-requirements)  
- [Install Python tools only](#install-python-tools-only)
  - [Install from PyPI wheel](#install-from-pypi-wheel)
  - [Install from source](#install-from-source)
- [Full build](#full-build)
  - [Build flags and debugging](#build-flags-and-debugging)
  - [Builds fod IDE toolchains](#builds-fod-ide-toolchains)
    - [XCode](#xcode)
    - [Note on Eclipse CDT](#note-on-eclipse-cdt)
  - [Installing python](#installing-python)
  - [Testing](#testing)

## Requirements for source installs

If you are on Linux and only need Python tools, you can jump to
[Install from PYPI wheel](#install-from-pypi-wheel). For other install
methods, you need a compiler, CMake, and Boost. For building the
Python tools, also SWIG is required.

### How to install MacOsX requirements

You need a compiler, for example in XCode Command Line
Tools that can be installed with

```sh
xcode-select --install
```

Boost, CMake and SWIG can be installed for with Homebrew with the
following command.

```sh
brew install boost cmake swig
```

### How to install Linux requirements

Check the [Dockerfile](Dockerfile) for an example.

## Install Python tools only

### Install from PyPI wheel

In Linux you should be able to just run the following command to
install the Python library from [PyPI](https://pypi.org/):

```sh
python -m pip install varikn
```

If this for some reason fails, try the next section

### Install from source

You need to have the [required
tools](#requirements-for-source-installs) to proceed.

```sh
# Install from the latest source distribution on PyPI:
python -m pip install varikn --no-binary :all:
# Install from local source (e.g. cloned Git repository):
python -m pip install .
```

## Full build

You need to have the [required
tools](#requirements-for-source-installs) to proceed.

CMake is a makefile generator (like Autoconf). The build script is in
CMakeLists.txt.  The convention for CMake is to build "out-of-source",
where all the work is done in a separate directory from your source
directory.  First, we configure the build (we only need to do this
once):

```sh
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
```

Note that this will build the Python wrapper under `lib/python`, but
will not install it. See [Install from source](#install-from-source)
for simple Python installation. You can explicitly disable building
of the wrapper by passing `-DENABLE_PYTHON_WRAPPER=0` to
cmake.

### Build flags and debugging

By default, the makefiles generated by CMake are 'quiet'. To make
them verbose (so you can see what's being passed to gcc, etc) use
the VERBOSE variable like this: `make VERBOSE=1`

You can make a debug build with

```sh
cmake .. -DCMAKE_BUILD_TYPE=Debug
```

If you're experimenting with alternate build flags, you can define
them as environment variables before configuring.  For example:

```sh
cd build
export CXXFLAGS=-fmudflap
cmake ..
make
```

If you are reconfiguring CMake with very different settings (for
example, switching from Debug to Release), you should start in a
new build folder or delete everything in your current build folder.

### Builds fod IDE toolchains

CMake also supports generating IDE project files (MSVC, XCode,
etc). To get a list of what it supports, do `cmake -h`.

#### XCode

For example, to create an MSVC project:

```sh
mkdir .build
cd .build
cmake .. -G "Visual Studio 9 2008"
start Project.sln
```

or to create an XCode project:

```sh
mkdir .build
cd .build
cmake .. -G Xcode
open Project.xcodeproj
```

#### Note on Eclipse CDT

Eclipse is finicky about the way its projects are laid out.  Instead
of creating a "build" folder as a child of your source dir you'll need
to create it as a *sibling*.  You'll also need to tell CMake to link
the build dir to the source dir in the Eclipse project. (See
[here](https://gitlab.kitware.com/cmake/community/-/wikis/doc/editors/Eclipse-CDT4-Generator)
for more info. For example:

```sh
cd trunk
mkdir ../.build-trunk
cd ../.build-trunk
cmake ../trunk/ -G "Eclipse CDT4 - Unix Makefiles" -DECLIPSE_CDT4_GENERATE_SOURCE_PROJECT=TRUE
```

Then in Eclipse you'll do File->Import the project in .trunk-build.
Inside this project you'll see a link to "[Source Directory]".
### Testing

Building Unit tests can be enabled with `-DENABLE_TESTING=1`. The tests
do not work on Windows yet. Unit tests can be run with `make test` or
`ctest --verbose`. Unit tests require the unit test library from Boost.