Installation
============
.. _installation:

.. tip::
    You will find the latest released version at pypi:  
    https://pypi.python.org/pypi/pymunk

Install Pymunk
--------------

Pymunk can be installed with pip install::

    > pip install pymunk

On non-Windows OS such as OSX and Linux you need to have a GCC-compatible 
compiler installed. 

On OSX you can install one with::

    > xcode-select --install

On Linux you can install one with the package manager, for example on Ubuntu 
with::

    > sudo apt-get install build-essential


Examples & Documentation
------------------------

Because of their size are the examples and documentation available in the 
source distribution of Pymunk, but not the wheels. The source distribution is 
available from PyPI at https://pypi.org/project/pymunk/#files (Named
pymunk-x.y.z.zip)


Advanced install
----------------

Another option is to use the standard setup.py way, in case you have downloaded
the source distribution::

    > python setup.py install

Note that this require a GCC compiler, which can be a bit tricky on Windows. 
If you are on Mac OS X or Linux you will probably need to run as a privileged 
user; for example using sudo::
    
    > sudo python setup.py install
    
Once installed you should be able to to import pymunk just as any other 
installed library. pymunk should also work just fine with virtualenv in case 
you want it installed in a contained environment.
 

.. _compile-chipmunk:

Compile Chipmunk
----------------
If a compiled binary library of Chipmunk that works on your platform is not 
included in the release you will need to compile Chipmunk yourself. Another 
reason to compile chipmunk is if you want to run it in release mode to get 
rid of the debug prints it generates. If you just use pip install the 
compilation will happen automatically given that a compiler is available. You 
can also specifically compile Chipmunk as described below.

To compile Chipmunk::

    > python setup.py build_ext 

If you got the source and just want to use it directly you probably want to 
compile Chipmunk in-place, that way the output is put directly into the correct
place in the source folder::

    > python setup.py build_ext --inplace

On Windows you will need to use a gcc-compatible compiler. The pre-built version
distributed with pymunk were compiled with the mingwpy GCC compiler at 
https://mingwpy.github.io/ 
  
.. seealso:: 

    Module :py:mod:`pymunkoptions` 
        Options module that control runtime options of Pymunk such as debug 
        settings. Use pymunkoptions together with release mode compilation to 
        remove all debugs prints.


CFFI Installation
-----------------
Sometimes you need to manually install the (non-python) dependencies of CFFI. 
Usually you will notice this as a installation failure when pip tries to 
install CFFI since CFFI is a dependency of Pymunk. This is not really part of 
Pymunk, but a brief description is available for your convenience. 

You need to install two extra dependencies for CFFI to install properly. This 
can be handled by the package manager. The dependencies are `python-dev` and 
`libffi-dev`. Note that they might have slightly different names depending on 
the distribution, this is for Debian/Ubuntu. Just install them the normal way, 
for example like this if you use apt and Pip should be able to install CFFI 
properly::

    > sudo apt-get install python-dev libffi-dev
