coala Installation
==================

This document contains information on how to install coala. Supported
platforms are Linux and Windows. coala is known to work on OS X as well.
coala is tested against CPython 3.3, 3.4 and 3.5.

In order to run coala you need to install Python. It is recommended,
that you install Python3 >= 3.3 from http://www.python.org.

The easiest way to install coala is using pip (Pip Installs Packages).
If you don't already have pip, you can install it like described on
https://pip.pypa.io/en/stable/installing.html. Note that pip is shipped
with recent python versions by default.

System wide installation
------------------------

The simplest way to install coala is to do it system-wide. But, This is
generally discouraged in favor or using a virtualenv.

To install the latest most stable version of coala and supported bears
system-wide, use:

::

    $ pip3 install coala-bears

.. note::

    For this and all future steps, some steps require root access
    (also known as administrative privileges in Windows).

    **Unix based** (Mac, Linux) - This can be achieved by using ``sudo``
    in front of the command ``sudo command_name`` instead of
    ``command_name``

    **Windows** - The easiest way on windows is to start a
    command prompt as an administrator and start ``setup.py``.

To install the nightly build from our master branch, you can do:

::

    $ pip3 install coala-bears --pre

To install only coala (without any bears), you can do:

::

    $ pip3 install coala

With ``--pre`` you can install the nightly build of the coala base
without bears.

Installing inside a virtualenv
------------------------------

Virtualenv is probably what you want to use during development,
you’ll probably want to use it there, too. You can read more about
it at their documentation - http://virtualenv.readthedocs.org

First, we need to install virtualenv to the system. This can be done
with ``pip3`` easily:

::

    pip3 install virtualenv

Once you have virtualenv installed, just fire up a shell and create
your own environment. I usually create a project folder and a ``venv``
folder:

::

    $ virtualenv venv

Now, whenever you want to work on the project, you only have to activate
the corresponding environment.

    On **Unix based** systems (OSX and Linux) this can be done with:

    ::

        $ source venv/bin/activate

    And on **Windows** this is done with:

    ::

        $ venv\scripts\activate

Finally, you install coala and supported bears inside the activated
virtualenv with:

::

    $ pip3 install coala-bears

Installing coala from source
----------------------------

In order to install coala from source, it is recommended to install git.
See http://git-scm.com/ for further information and a downloadable
installer or use your package manager on linux to get it.

.. note::

    Again, here it is recommended to install coala inside a virtualenv.
    This can be done by creating a virtualenv and running the installation
    commands after the virtualenv has been activated.

After having git installed, you can download the source code of coala
with the following command:

::

    git clone https://github.com/coala-analyzer/coala-bears/
    cd coala-bears

You can now install coala with a simple:

::

    python3 setup.py install

For the above to work, you may also need to install `setuptools` which can be
installed by running

::

    pip3 install setuptools

You will have coala installed into your python scripts directory. On an
unixoid system it is probably already available on your command line
globally.

You may also install a development version of coala to test and make
changes easily. To do this run:

::

    $ python3 setup.py develop

This essentially lets you install coala in a way that allows you to make
changes to the code and see the changes take effect immediately.

Alternate installation
~~~~~~~~~~~~~~~~~~~~~~

If you want to install coala to an alternate location you can e.g. call
``python3 setup.py install --prefix=/your/prefix/location``. Other
options are documented on
https://docs.python.org/3.3/install/#alternate-installation.

.. note::

    If you are using a proxy, follow these steps:

    -  Set up your system-wide proxy.
    -  Use ``sudo -E pip3 install coala`` (the ``-E`` flag takes the
       existing environment variables into the ``sudo`` environment).

    You could also set your pip.conf file to use a proxy, to know more
    read
    http://stackoverflow.com/questions/14149422/using-pip-behind-a-proxy
    for further clarification.

Dependencies
------------

This section lists dependencies of coala that are not automatically
installed. On Windows, you can get many with ``nuget``
(https://www.nuget.org/), on Mac Homebrew will help you installing
dependencies (http://brew.sh/).

JS Dependencies
~~~~~~~~~~~~~~~

coala features a lot of bears that use linters written in JavaScript. In
order for them to be usable, you need to install them via ``npm``
(http://nodejs.org/):

::

    npm install -g jshint alex remark dockerfile_lint csslint coffeelint

If a bear still doesn't work for you, please make sure that you have a
recent version of ``npm`` installed. Many linux distributions ship a
very old one.

.. note::

    If using coala from source you can just do ``npm install`` or
    ``npm install -g`` to use the ``package.json`` which is shipped with
    coala.

Binary Dependencies
~~~~~~~~~~~~~~~~~~~

Some bears need some dependencies available:

-  PHPLintBear: Install ``php``
-  IndentBear: Install ``indent`` (be sure to use GNU Indent, Mac ships
   a non-GNU version that lacks some functionality.)
-  CSharpLintBear: Install ``mono-mcs``

Clang
~~~~~

coala features some bears that make use of Clang. In order for them to
work, you need to install libclang:

-  Ubuntu: ``apt-get install libclang1``
-  Fedora: ``dnf install clang-libs`` (Use ``yum`` instead of ``dnf`` on
   Fedora 21 or lower.)
-  ArchLinux: ``pacman -Sy clang``
-  Windows: ``nuget install ClangSharp``
-  OSX: ``brew install llvm --with-clang``

If those do not help you, search for a package that contains
``libclang.so``.

On windows, you need to execute this command to add the libclang path to
the *PATH* variable permanently (you need to be an administrator):

``setx PATH "%PATH%;%cd%\ClangSharp.XXX\content\x86" \M``

For x86 python or for x64 python:

``setx PATH "%PATH%;%cd%\ClangSharp.XXX\content\x64" \M``

Replace "XXX" with the ClangSharp version you received from nuget.

Generating Documentation
~~~~~~~~~~~~~~~~~~~~~~~~

coala documentation can be generated by fetching the documentation
requirements. This can be achieved by

::

    pip3 install -r docs-requirements.txt

To generate the documentation coala uses `sphinx`. Documentation can be
generated by running the following command:

::

    python3 setup.py docs

You can then open ``docs\_build\html\index.html`` in your favourite
browser.

See :doc:`Writing Documentation <../Getting_Involved/Writing_Documentation>`
for more information.
