Aidge Setup and Installation
============================

System Requirements
-------------------

- ``Python >= 3.10``

Additional requirements vary by module. Refer to each module's documentation for details.


.. _installation:

Installation
------------

Aidge is built on a core library that interfaces with multiple modules, each binded to Python libraries.
Each module must be installed independently, ``aidge_core`` included.

.. tip::
  We recommend creating a Python environment to work with Aidge:

  .. code-block:: bash

      # Using the virtualenv package, for example:
      virtualenv -p python3.10 py_env_aidge

.. hint::
  You can also use `Dev Containers <https://containers.dev>`_ if your IDE support it (VScode for example).
  This is a Docker-based development environment with minimal required tools preinstalled, enabling a separate development environment from your computer.
  See :ref:`dev-container-configuration` section.


1. Install via pip (recommended, Linux only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Install the full bundle of default modules:

.. code-block:: bash

  # Activate your virtual env:
  source py_env_aidge/bin/activate
  
  pip install -r default_module_install.txt
  # - `aidge_core`
  # - `aidge_backend_cpu`
  # - `aidge_backend_cuda`
  # - `aidge_backend_opencv`
  # - `aidge_export_cpp`
  # - `aidge_export_arm_cortexm`
  # - `aidge_learning`
  # - `aidge_onnx`
  # - `aidge_quantization`

Alternatively, install only the modules you need:

.. code-block:: bash

  # Activate your virtual env:
  source py_env_aidge/bin/activate
  
  pip install aidge-core aidge-backend-cpu aidge-learning aidge-export-cpp aidge-onnx aidge-quantization

You can install additional modules from the  
`list of available submodules <https://gitlab.eclipse.org/eclipse/aidge>`_ as needed.

2. Build from source
~~~~~~~~~~~~~~~~~~~~

**System Requirements**

- ``CMake >= 3.18``
- ``Git``

Build on Linux & macOS
^^^^^^^^^^^^^^^^^^^^^^

1. Create and activate your virtual environment:

.. code-block:: bash

   virtualenv -p python3.10 py_env_aidge
   source py_env_aidge/bin/activate

2. Clone the full repository (with submodules), and move to its root directory:

.. code-block:: bash

   git clone --recursive https://gitlab.eclipse.org/eclipse/aidge/aidge.git
   cd aidge

3. Install the package based on your specific requirements:

**For Python development:**

.. code-block:: bash

   # Install all modules
   ./setup.sh --all --release --python

   # Alternatively, install only specific modules
   ./setup.sh -m core -m backend_cpu -m onnx --release --python

**For C++ development:**

.. code-block:: bash

   # Install all modules
   ./setup.sh --all --release

   # Alternatively, install only specific modules, in debug or release mode
   ./setup.sh -m core -m backend_cpu --release
   ./setup.sh -m core -m backend_cpu --debug --tests

.. tip::
   Run ``./setup.sh -h`` to view all installation options.

Build on Windows
^^^^^^^^^^^^^^^^

1. Create and activate your virtual environment:

.. code-block:: bash

   virtualenv -p python3.10 py_env_aidge
   source py_env_aidge/bin/activate

2. Clone the full repository (with submodules), and move to its root directory:

.. code-block:: bash

   git clone --recursive https://gitlab.eclipse.org/eclipse/aidge/aidge.git
   cd aidge

3. Install the package based on your specific requirements:

**Python development:**

.. code-block:: powershell

   .\setup.ps1 -All -Release -Python
   .\setup.ps1 -Modules core,backend_cpu,onnx -Release -Python

**C++ development:**

.. code-block:: powershell

   .\setup.ps1 -All -Release
   .\setup.ps1 -Modules core,backend_cpu,onnx -Debug -Tests

.. tip::
   Run ``.\ setup.ps1 -h`` to view all installation options.


Verify installation
-------------------

.. code-block:: bash

   python -c "import aidge_core; import aidge_backend_cpu; print(aidge_core.Tensor.get_available_backends())"

Expected output:

.. code-block:: text

   {'cpu'}

.. _dev-container-configuration:

Dev container configuration
---------------------------

.. important::

   Supported IDE are listed on `official website <https://containers.dev/supporting>`_.

To use with Visual Studio Code:

1. Make sure that the ``Remote-Containers`` and ``Docker`` extensions are installed in VSCode.

2. If using podman instead of docker, edit the setting ``dev.containers.dockerPath`` for the Docker extension, and set its value to ``podman``, as per below:

   .. code-block:: js

         "dev.containers.dockerPath": "podman",

   Optionally, you can also modify the ``dev.containers.socketPath`` to:

   .. code-block::

         /run/podman/podman.sock

   This will allow the 'Remote Explorer' tab to work, providing information about running containers.
   (Note: the path to the podman socket was found by querying the podman.socket service using
   ``systemctl status podman.socket``).

3. Setup sharing git credentials as explained in
   `documentation <https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials>`_.

4. Open the project folder and use the ``Remote-Containers: Reopen Folder in Container`` command
   from the VS Code command palette (or with :kbd:`F1` key).

5. In the terminal, make sure to source the python virtual env with:

   .. code-block:: bash

         source /workspaces/aidge/env_aidge/bin/python

6. In the terminal, make sure all git lfs object has been pulled:

   .. code-block:: bash

         git lfs install
         git lfs pull

7. Continue Aidge installation as explained in :ref:`installation` section.