Developer Setup
===============

The source code is hosted on GitHub. Fork the repository with the following
command::

  git clone https://github.com/mu-editor/mu.git

**Mu does not and never will use or support Python 2**. You should use Python
3.5 or above.

Windows, OSX, Linux
+++++++++++++++++++

Create a working development environment by installing all the dependencies
into your virtualenv with::

    pip install -e ".[dev]"

.. note::

    The Mu package distribution, as specified in ``setup.py``, declares
    both runtime and extra dependencies.

    The above mentioned ``pip install -e ".[dev]"`` installs all runtime
    dependencies and most development ones: it should serve nearly everyone.

    For the sake of completeness, however, here are a few additional details.
    The ``[dev]`` extra is actually the aggregation of the following extras:

    * ``[tests]`` specifies the testing dependencies, needed by ``make test``.
    * ``[docs]`` specifies the doc building dependencies, needed by ``make docs``.
    * ``[i18n]`` specifies the translation dependencies, needed by ``make translate_*``.
    * ``[package]`` specifies the packaging dependencies needed by ``make win32``,
      ``make win64``, ``make macos``, or ``make dist``.

    Additionally, the following extras are defined:

    * ``[utils]`` specifies the dependencies needed to run the utilities
      under the ``utils`` directory. It has been specifically excluded from
      the ``[dev]`` extra for two reasons: i) on the Windows platform, it
      requires a C compiler to be installed (as of this writing), and
      ii) running such utilities is seldom needed in Mu's development process.
    * ``[all]`` includes all the dependencies in all extras.


.. warning::

    Sometimes, having several different versions of PyQt installed on your
    machine can cause problems (see
    `this issue <https://github.com/mu-editor/mu/issues/297>`_ for example).

    Using a virtualenv will ensure your development environment is safely
    isolated from such problematic version conflicts.

    If in doubt, throw away your virtualenv and start again with a fresh
    install as per the instructions above.

    On Windows, use the venv module from the standard library to avoid an
    issue with the Qt modules missing a DLL::

        py -3 -mvenv .venv

    Virtual environment setup can vary depending on your operating system.
    To learn more about virtual environments, see this `in-depth guide from Real Python <https://realpython.com/python-virtual-environments-a-primer/>`_.


Running Development Mu
++++++++++++++++++++++

.. note:: From this point onwards, instructions assume that you're using
   a virtual environment.

To run the local development version of Mu, in the root of the repository type::

  python run.py

An alternative form is to type::

  python -m mu

Yet another one is typing::

  mu-editor

Raspberry Pi
++++++++++++

If you are working on a Raspberry Pi there are additional steps to create a
working development environment:

1. Install required dependencies from Raspbian repository::

    sudo apt-get install python3-pyqt5 python3-pyqt5.qsci python3-pyqt5.qtserialport python3-pyqt5.qtsvg python3-dev python3-gpiozero python3-pgzero libxmlsec1-dev libxml2 libxml2-dev

2. If you are running Raspbian Buster or newer you can also install this
   optional package::
   
    sudo apt-get install python3-pyqt5.qtchart

3. Create a virtualenv that uses Python 3 and allows the virtualenv access
   to the packages installed on your system via the ``--system-site-packages``
   flag::

    sudo pip3 install virtualenv
    virtualenv -p /usr/bin/python3 --system-site-packages ~/mu-venv

4. Activate the virtual environment ::

    source ~/mu-venv/bin/activate

5. Clone mu::

    (mu-venv) $ git clone https://github.com/mu-editor/mu.git ~/mu-source

6. With the virtualenv enabled, pip install the Python packages for the
   Raspberry Pi with::

    (mu-venv) $ cd ~/mu-source
    (mu-venv) $ pip install -e ".[dev]"

7. Run mu::

     python run.py

   An alternative form is to type::

     python -m mu

   Or even::

     mu-editor

.. warning::

    These instructions for Raspberry Pi only work with Raspbian version
    "Stretch".

    If you use ``pip`` to install Mu on a Raspberry Pi, then the PyQt related
    packages will not be automatically installed from PyPI. This is why you
    need to use ``apt-get`` to install them instead, as described in step 1,
    above.

Using ``make``
++++++++++++++

There is a Makefile that helps with most of the common workflows associated
with development. Typing ``make`` on its own will list the options thus::

    $ make

    There is no default Makefile target right now. Try:

    make run - run the local development version of Mu.
    make clean - reset the project and remove auto-generated assets.
    make pyflakes - run the PyFlakes code checker.
    make pycodestyle - run the PEP8 style checker.
    make test - run the test suite.
    make coverage - view a report on test coverage.
    make check - run all the checkers and tests.
    make dist - make a dist/wheel for the project.
    make publish-test - publish the project to PyPI test instance.
    make publish-live - publish the project to PyPI production.
    make docs - run sphinx to create project documentation.
    make translate - create a messages.pot file for translations.
    make translateall - as with translate but for all API strings.
    make win32 - create a 32bit Windows installer for Mu.
    make win64 - create a 64bit Windows installer for Mu.
    make macos - create a macOS native application for Mu.
    make video - create an mp4 video representing code commits.

Everything should be working if you can successfully run::

  make check

(You'll see the results from various code quality tools, the test suite and
code coverage.)

.. note::

    On Windows there is a ``make.cmd`` file that works in a similar way to the
    ``make`` command on Unix-like operating systems.

.. warning::

    In order to use the MicroPython REPL via USB serial you may need to add
    yourself to the ``dialout`` group on Linux.

Before Submitting
+++++++++++++++++

Before contributing code please make sure you've read :doc:`contributing` and
follow the checklist for contributing changes. We expect everyone participating
in the development of Mu to act in accordance with the PSF's
:doc:`code_of_conduct`.
