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

This guide walks you through the installation of two components:

1. DataQruiser App: our graphical user interface to visualize and interact with your data. You can download and install the application from :doc:`dataqruiser_releases`.
2. the qDrive Package: allow you to interact with your measurement data and synchronizing it with the DataQruiser app from python. This document details how to install the qDrive package.

.. contents:: Installation overview
   :local:
   :depth: 2

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

* The minimum Python version is Python 3.7.

It is highly recommended to install the qDrive package in a separate environment to prevent conflicts with other Python packages,
especially if older measurement software is in use.

Setting Up the Environment
--------------------------

To create a new environment and install the qDrive package, open the Anaconda prompt and run:

.. code-block:: console

   conda create -n qdrive_env python=3.11

If you wish to install qDrive in an existing environment, you can test its compatibility by cloning the environment:

.. code-block:: console

   conda create --name myclone --clone my_measurement_env

After installation, ensure compatibility by importing your commonly used packages.

.. note::

   Remember to activate the environment when you open a new terminal or prompt:

   .. code-block:: console

      conda activate qdrive_env

   **Spyder users** : Ensure Spyder is updated to use ``PyQt5 >= 5.15.0`` to avoid compatibility issues.

.. For Windows, macOS, and Linux (Python Installer)
.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. You can also create a virtual environment using virtualenv. If virtualenv is not installed, run:

.. .. code-block:: console

..    pip install virtualenv

.. The virtual environment can be created with the following commands:

.. .. code-block:: console

..    cd /path/to/your/preferred/location
..    python -m venv qdrive_env
..    source qdrive_env/bin/activate  # (or .\qdrive_env\Scripts\activate on Windows)

.. Now the creation of the virtual environment is complete. Proceed here to install the qDrive package.

.. .. tip:: 
..    Add the following alias to your ``.bashrc`` to simplify activating the environment:

..    .. code-block:: console

..       alias qdrive_env='source /path/to/your/preferred/location/qdrive_env/bin/activate'

..    Then, run ``qdrive_env`` to activate the environment.

Installing the qDrive package
-----------------------------

Once your environment is active, install the qDrive package by running:

.. code-block:: console

   pip install qdrive==0.2.42

.. note::
   If  you want to synchronize **core-tools** data, install both 
   `pulse-lib <https://github.com/stephanlphilips/pulse_lib/>`_ and
   `core-tools <https://github.com/stephanlphilips/core_tools/>`_ 
   in the qDrive environment by running:

   .. code-block:: console

      pip install git+https://github.com/stephanlphilips/pulse_lib
      pip install git+https://github.com/stephanlphilips/core_tools


After installation, you should be able to run qDrive. For example, to log in, run:

.. code-block:: console

   python -c "import qdrive; qdrive.launch_GUI()"

Updating the qDrive package
---------------------------

If the synchronization GUI is open, close it first.

To update qDrive, activate the environment where it was installed and run:

.. code-block:: console

   pip install qdrive --upgrade

We recommend restarting the synchronization agent to ensure it uses the latest version. Run the following commands:

.. code-block:: console

   python -c "import qdrive; qdrive.restart_sync_agent(); qdrive.launch_GUI()"


Troubleshooting Installation Errors
-----------------------------------

If you encounter errors during installation, it may be due to package dependencies.
To resolve these, update the relevant package by running:

.. code-block:: console

   pip install -U package_that_needs_an_update