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

.. _installation:

MAxPy is a Python based application, and it is meant to run on Linux systems.

Prior using MAxPy, you need to install the :ref:`install_system` and the :ref:`install_maxpy` itself.

.. _install_system:

System packages
---------------

As MAxPy relies on other open-source tools, you need first to install them in your system prior to using it.

.. note::
   The following instructions will consider the **APT (Advanced Packaging Tool)** for installing the desired packages in your Debian based (``apt-get`` command). However, depending on your system, other package managers can be used, such as ``pacman`` for Arch based systems.

Before installing the tools, it is recommended to install some basic system packages used for *building packages from source*:

    .. code:: bash

        sudo apt-get install make cmake clang gcc tcl tcl-dev tcllib swig bison flex python3-pip ninja-build help2man

#. Install **Yosys**

    Yosys is the default *logic synthesis tool* used by MAxPy. You can either install it from source following the guidelines available at the `Yosys official repository <https://github.com/YosysHQ/yosys>`_, or you can use the ``apt`` package manager.

    .. code:: bash

        sudo apt-get install yosys

    In principle any version available in the repositories should work. If you have any trouble, please let us know.


#. Install **OpenSTA**

    OpenSTA is the tool used for static timing analysis and power estimations based on the get-level netlists. As OpenSTA may not be available at the package manager in every Linux distribution, it is advised to build it STA from source. Please check the build instructions at the `OpenSTA official repository <https://github.com/The-OpenROAD-Project/OpenSTA>`_.

    For short, you can use the following commands, but in case of any trouble, please the check the full install instruction at their repository.

    .. code:: bash

        git clone https://github.com/The-OpenROAD-Project/OpenSTA.git
        cd OpenSTA
        mkdir build
        cd build
        cmake ..
        make
        sudo make install

#. Install **Verilator**

    Verilator is the simulation tool which allows Verilog circuits to be simulated as a computer program.  Despite Verilator being available at the ``apt`` package manager, you should check its version. MAxPy currently works with Verilator version ``v5.002``.

    .. code:: bash

        sudo apt-get install verilator

    However, Verilator can be built from source aswell. You can the instruction available at their `Installation page <https://verilator.org/guide/latest/install.html>`_. Also, you can check the `Verilator official repository <https://github.com/verilator/verilator>`_.

#. Install `pybind11 <https://pybind11.readthedocs.io/>`_

    Pybind11 is a header only library that allows the C++ model generated by Verilator to be translated to Python. As it is very simple, the default ``apt`` package manager installation should do it:

    .. code:: bash

        sudo apt-get install pybind11-dev

.. _install_maxpy:

MAxPy package
-------------

You have two options for installing MaxPy:

#. Via ``pip``

    Just type the following command in the terminal and it's done:

    .. code:: bash

        pip install MAxPy

#. Via ``wheel`` file

    Download the ``wheel`` file available from MAxPy's `latest release on Github <https://github.com/MAxPy-Project/MAxPy/releases/latest>`_. The file is in the ``MAxPy-x.x.x-py3-none-any.whl`` format, where the ``x.x.x`` sequence represents the release version. Then just run the following command on the terminal:

    .. code:: bash

        pip install [path_to_the_wheel_file]/MAxPy-x.x.x-py3-none-any.whl