xref: /aosp_15_r20/external/pigweed/pw_arduino_build/docs.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985)
1.. _module-pw_arduino_build:
2
3-----------------
4pw_arduino_build
5-----------------
6.. pigweed-module::
7   :name: pw_arduino_build
8
9The ``pw_arduino_build`` module contains both the `arduino_builder`_ command
10line utility and an `Arduino Main Wrapper`_.
11
12.. seealso::
13   See the :ref:`target-arduino` target documentation for a list of supported
14   hardware.
15
16Arduino Main Wrapper
17====================
18
19``arduino_main_wrapper.cc`` implements the standard ``setup()`` and ``loop()``
20functions [#f1]_ that are expected in Arduino sketches.
21
22Pigweed executables rely on being able to define the ``main()`` function. This
23is a problem for Arduino code as each core defines it's own ``main()``. To get
24around this the Pigweed Arduino target renames ``main()`` to ``ArduinoMain()``
25using a preprocessor macro: ``-Dmain(...)=ArduinoMain()``. This macro only
26applies when compiling Arduino core source files. That frees up ``main()`` to be
27used elsewhere.
28
29Most Arduino cores will do some internal initialization before calling
30``setup()`` followed by ``loop()``. To make sure Pigweed ``main()`` is started
31after that early init we run it within ``setup()``:
32
33.. code-block:: cpp
34
35   void setup() {
36     pw_arduino_Init();
37     // Start Pigweed main()
38     main();
39   }
40
41   void loop() {}
42
43.. note::
44   ``pw_arduino_Init()`` initializes the :ref:`module-pw_sys_io_arduino`
45   module.
46
47.. warning::
48   You may notice ``loop()`` is empty in ``arduino_main_wrapper.cc`` and never
49   called. This will cause any code appearing after ``loop()`` in an Arduino
50   core to never be executed. For most cores this should be ok but may cause
51   issues in some scenarios.
52
53arduino_builder
54===============
55
56``arduino_builder`` is utility that can extract compile and tooling information
57from an Arduino core. It's used within Pigweed to shovel compiler flags into
58the `GN <https://gn.googlesource.com/gn/>`_ build system. It will also work
59without Pigweed and can be used with other build systems.
60
61Full documentation is pending. For now run ``arduino_builder --help`` for
62details.
63
64.. rubric::
65   Footnotes
66
67.. [#f1]
68   See the Arduino Reference documentation on `setup()
69   <https://www.arduino.cc/reference/en/language/structure/sketch/setup/>`_, and
70   `loop()
71   <https://www.arduino.cc/reference/en/language/structure/sketch/loop/>`_.
72