.. |major| replace:: 3
.. |minor| replace:: 3
.. |point| replace:: 0
.. |major_minor| replace:: \ |major|\ .\ |minor|\ 
.. |blender_major_minor| replace:: blender-\ |major|\ .\ |minor|\ .\ |point|\
.. |python_minor| replace:: 10
.. |tag| replace:: \ |release|\

..
    TODO: Replace |pyddg-gitlab| with the package name once the library is on PyPI.

.. |pyddg-gitlab| replace:: git+https://gitlab.discretization.de/python/pyddg@\ |tag|

.. _installation:

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

Windows
-------

.. note::
    If you prefer to work in a GNU/Linux environment directly on Windows, you can install `WSL <https://learn.microsoft.com/en-us/windows/wsl/install>`_. 
    You can then follow the instruction for :ref:`linux_installation`.

Make sure that you have Python 3.9 or 3.10.

Install Blender |major_minor| using the `official installer <https://www.blender.org/download/release/Blender3.3/blender-3.3.0-windows-x64.msi/>`_.
You can install it to a custom directory, but from now on we will assume
the default directory.
Then run

.. parsed-literal::

    "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\\ |major_minor|\ \\python\\bin\\python.exe" -m ensurepip
    "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\\ |major_minor|\ \\python\\bin\\python.exe" -m pip install |pyddg-gitlab|

.. warning::
   This modifies your Blender installation.
   Updating or installing another Blender version may result in problems.

Create a directory for your project and enter it. Create and enter a virtual environment with

.. parsed-literal::

    # create the virtual environment
    python -m venv .\\venv

    # enter it
    source venv\\Scripts\\activate

    # install the library
    pip install |pyddg-gitlab|

Exit the virtual environment with

.. code-block:: doscon

    deactivate

.. _linux_installation:

Linux, WSL and macOS
--------------------

.. warning::
    Don't install Blender using other methods unless you know what you are doing.

Install Blender |major_minor| to a directory of your choice, e.g. ``~/blender``, with the following command:

..
    TODO: Replace this with
        sh <(curl https://gitlab.discretization.de/python/pyddg/-/raw/develop/scripts/setup_blender) ~/blender |major| |minor| |point|
    once the repository is public.

.. parsed-literal::

    # Install Blender |major_minor|.\ |point| \ to ~/blender
    sh <(curl https://gitlab.discretization.de/pyddg/pyddg/-/raw/develop/scripts/setup_blender) ~/blender |major| |minor| |point|

.. warning::
    Blender is expected to crash if you attempt to run it now.

We don't support newer versions of Blender right now, though they are likely to work.

Create a directory for your project and enter it.
Create a virtual environment with

.. parsed-literal::

    ~/blender/\ |blender_major_minor|\ /\ |major_minor|\ /_python/bin/python3.\ |python_minor|\  -m venv venv

The following commands need to be run every time you want to work with the library: 

.. parsed-literal::
   
    export PATH="$HOME/blender/\ |blender_major_minor|\ :$PATH"
    export PYTHONPATH="venv/lib/python3.\ |python_minor|\ /site-packages/"
    source venv/bin/activate

.. warning::
	Blender won't work until you enter the virtual environment and set these environment variables.	
	
Install the library with
	
.. parsed-literal::
   
    pip install |pyddg-gitlab|
	
Verify that Blender finds the library with

.. code-block:: bash

    blender --background --python-expr 'import ddg; print("Successfully imported ddg!")'

Start Blender with

.. code-block:: bash

    blender

Deactivate the virtual environments with

.. code-block:: bash

    deactivate

Setting up display for interactive Blender on WSL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

While `WSL supports Linux GUI apps on Windows 11 <https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps>`_, the same cannot be said for Windows 10.

In this case, you need to set up an X Server to display graphical outputs of interactive Blender. 

`VcXsrv <https://sourceforge.net/projects/vcxsrv/>`_ is an open-source tool that can set up a Windows X Server. After installing VcXsrv, an X Server can be set up by running xlaunch.exe.

In Display settings, choose "Multiple windows", Display number 0.

.. image:: xlaunch_01.png
    :width: 400

Choose "Start no client" for client startup option.

.. image:: xlaunch_02.png
    :width: 400

In Extra settings, tick "Disable access control" to enable access from clients in WSL.

.. image:: xlaunch_03.png
    :width: 400

Finally, do not forget to save the configuration and finish. Next time you need to start an X Server, start the saved .xlaunch file to avoid setting it up all over again. 

You will know that VcXsrv is running when the XLaunch icon appears in the taskbar.

.. image:: xlaunch_04.png
    :width: 200


The next thing to do is to set the environment variable ``DISPLAY`` for our WSL instance. This can be done dynamically with:

.. code-block:: bash

    export DISPLAY="`sed -n 's/nameserver //p' /etc/resolv.conf`:0"

If you already added Blender to the ``$PATH`` in WSL, simply running ``blender`` will launch interactive Blender.

.. image:: blender_gui_01.png
    :width: 600