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 `_ 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 `_. 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`.