.. _build:

Building
========

If not stated otherwise, you can obtain a copy of the code at 
https://github.com/anabrid/lucidac-firmware/. Building the code is as simple
as typing ``pio run`` in your shell at the root directory of the
repository. PlatformIO automatically installs all the dependencies.
The following section will introduce into PlatformIO.

.. _pio:

Working with PlatformIO
-----------------------

This code is using the `PlatformIO <https://platformio.org/>`_ ecosystem
(in short *pio*)
and is based on the Arduino API port for the Teensy Microcontroller,
called `Teensyduino <https://www.pjrc.com/teensy/teensyduino.html>`_.
Thanks to PlatformIO, it is *not* neccessary to install Arduino or Teensy
tools manually. All this is done by PlatformIO and this way works the same,
regardless whether you work on Mac, Windows or Linux, in a terminal or in
your favourite IDE.

There are many ways to install PlatformIO. Generally, it is suggested not
to use theversion bundled with your systems package repository
(such as ``apt install platformio``) but installing the most recent version
with ``pip install platformio``.
You can also follow the official reference at
at ttps://docs.platformio.org/en/latest/core/installation/methods/installer-script.html#installation-installer-script. For the VSCode IDE integration, see
https://docs.platformio.org/en/latest/integration/ide/vscode.html

.. note::

   If you are using old versions of PlatformIO, spurious errors messages 
   can occur such as ``error detected unknown package``. Updating the PlatformIO
   core can solve such problems.
   
   
When you start with ``pio``, make sure to *always* run it from the root directory of this repository,
otherwise you will get errors ("not a platformio project", ...)

.. _pioenv:

Environments
------------

PlatformIO supports different build configurations, which are called *environments*.
This concept is used in differnet ways: First and foremost, we differentiate between
``native`` and ``teensy41`` environments. The ``teensy41`` environment builds a proper
firmware image while the native environment builds the firmware
in the host CPU architecture which is only suitable for simulation and testing/debugging of certain
subsystems.

Furthermore, the environment concept can be used for choosing different firmware uploader
such as *tycmd* (https://koromix.dev/tytools).

.. note::

   Unfortunately, the environment concept is not orthogonal (independent) to other concepts.
   For instance, certain unit tests work only in the native environment or only in the 
   teensy environment.
   

Linux-relevant hints for Teensy via USB
---------------------------------------

See :ref:`udev`.

Sometimes this still doesn't work and you have to prepend ``pio`` calls that upload with ``sudo``. If this doesn't
work because you have PlatformIO installed as a user and not system-wide, you can use ``sudo -E env pio ...``
in order to export/expose your python environment to the sudo call.