.. include:: ../../substitutions

.. _developers_installation:

Installation
============

This is an installation guide for developers using Linux and macOS. On Windows, you can use WSL and follow the Linux instructions. See the :ref:`user's installation guide <pyddg_installation>` for information on how to run Blender from WSL.

.. contents::
   :local:
   :backlinks: none


Requirements
------------

To get started, install `Poetry <https://python-poetry.org/docs/#installation>`_.
Poetry is used to manage dependencies and so called Poetry shells, which are essentially virtual environments.

Make sure you have ``git`` and ``make``.

.. code-block:: bash
    :caption: Debian and Ubuntu (and derivatives)

    sudo apt install git make

On macOS, ``git`` and ``make`` come with Apple's Xcode Command Line Tools. You can just try to run one of the commands, for example ``git`` in a terminal and they will be installed automatically if necessary.


Getting the source code
-----------------------

Generate an SSH key pair following the
`gitlab instructions <https://docs.gitlab.com/ee/user/ssh.html#rsa-ssh-keys>`_.

Clone the repository into your favourite directory using:

.. code-block:: bash

    git clone git@gitlab.discretization.de:pyddg/pyddg.git

This will create a directory ``pyddg``.

To push local changes on git don't forget to tell git who you are by running

.. code-block:: bash

    git config --global user.email "you@example.com"
    git config --global user.name "Your Name"

If you want to use git blame, you should configure git to ignore non-relevant commits:

.. code-block:: bash

	git config blame.ignoreRevsFile .git-blame-ignore-revs


Installing the library and Blender
----------------------------------

Linux/WSL
~~~~~~~~~

.. warning::
    Don't install Blender using other methods unless you know what you are doing.
    The ``setup_blender`` script ensures that Blender can use virtual environments.
    For more details, consult the `Blender documentation <https://docs.blender.org/api/current/info_tips_and_tricks.html#bundled-python-extensions>`_ and the ``setup_blender`` source code.

Install Blender

.. parsed-literal::

    # Install Blender |major_minor|.\ |point| \ to ~/blender
    scripts/setup_blender ~/blender |major| |minor| |point|

.. warning::
    Blender is expected to crash if you attempt to run it now.
    Blender won't work until you enter the Poetry shell or virtual environment and set certain environment variables as described below.

Then run

.. parsed-literal::

    cd pyddg    # the project directory
    poetry env use ~/blender/\ |blender_major_minor|\ /\ |major_minor|\ /_python/bin/python3.\ |python_minor|
    poetry install \ |poetry_groups|

Enter the virtual environment with

.. parsed-literal::

    # poetry
    export PATH="$HOME/blender/\ |blender_major_minor|\ :$PATH"
    export PYTHONPATH="$(poetry env info -p)/lib/python3.\ |python_minor|\ /site-packages/"
    poetry shell

macOS
~~~~~

Install Blender |major_minor| for Apple Silicon with the following command. If you're running Intel, pass ``x64`` instead of ``arm64``. Note that it requires root privileges because Blender is installed to ``/Applications/``. It is installed under a new name, so it will not interfere with any existing Blender installation.

.. parsed-literal::

    # Install Blender |major_minor_point| \ to /Applications/
    sh <(curl https://gitlab.discretization.de/pyddg/pyddg/-/raw/develop/scripts/setup_blender_macos) arm64 |major| |minor| |point|

.. warning::

    Blender is expected to crash if you attempt to run it now.
    Blender won't work until you enter the Poetry shell or virtual environment and set certain environment variables as described below.

Then run

.. parsed-literal::

    cd pyddg    # the project directory
    poetry env use /Applications/Blender-\ |major_minor_point|\ -pyddg.app/Contents/Resources/\ |major_minor_point|\ /_python/bin/python3.\ |python_minor|
    poetry install \ |poetry_groups|

Enter the virtual environment with

.. parsed-literal::

    # poetry
    export PATH="/Applications/Blender-\ |major_minor_point|\ -pyddg.app/Contents/MacOS/:$PATH"
    export PYTHONPATH="$(poetry env info -p)/lib/python3.\ |python_minor|\ /site-packages/"
    poetry shell

Test your installation
----------------------

Run tests with

.. code-block:: bash

    python3 test.py

You can run tests selectively.
For all options, consult

.. code-block:: bash

    python3 test.py --help

Build documentation with

.. code-block:: bash
    :caption: Linux and macOS

    make -C docs/ docs

.. code-block:: doscon
    :caption: Windows

    docs\make.bat docs

and open ``docs/build/index.html`` in your favorite browser.

Clean the build artifacts with

.. code-block:: bash
    :caption: Linux and macOS

    make -C docs/ clean

.. code-block:: doscon
    :caption: Windows

    docs\make.bat clean

Exit the Poetry shell with

.. code-block:: bash

    exit