From fd53a080ee670dfc973d44c584b2d0385987790e Mon Sep 17 00:00:00 2001 From: Max Prokhorov Date: Tue, 22 Feb 2022 13:42:26 +0300 Subject: [PATCH] Add documentation entry about compiler warnings (#8492) per #8421 and #8475 after checking HW, suggest to check SW as well by at least by enabling some or all compiler warnings (and also note of the IDE weirdest defaults causing issues we expected to stay solved) --- doc/faq/a02-my-esp-crashes.rst | 38 ++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/faq/a02-my-esp-crashes.rst b/doc/faq/a02-my-esp-crashes.rst index a000bd0f7..1fcc2cbaa 100644 --- a/doc/faq/a02-my-esp-crashes.rst +++ b/doc/faq/a02-my-esp-crashes.rst @@ -6,6 +6,7 @@ My ESP crashes running some code. How to troubleshoot it? - `Introduction <#introduction>`__ - `What ESP has to Say <#what-esp-has-to-say>`__ - `Get Your H/W Right <#get-your-hw-right>`__ +- `Enable compilation warnings <#enable-compilation-warnings>`__ - `What is the Cause of Restart? <#what-is-the-cause-of-restart>`__ - `Exception <#exception>`__ - `Watchdog <#watchdog>`__ @@ -73,6 +74,43 @@ In any case, make sure that your module is able to stably run standard example sketches that establish Wi-Fi connection like, e.g., `HelloServer.ino `__. +Enable compilation warnings +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most common issues may be resolved by enabling compilation warnings and fixing them. + +For Arduino IDE, select ``File -> Preferences``: + +- Make sure ``Show verbose output during: compilation`` is enabled +- Set ``Compiler warnings`` to ``More`` or ``All`` + +For PlatformIO, all warnings should already be enabled by default. + +Notice that the default configuration of Arduino IDE inhibits **all** compilation warnings. +For the ESP8266 platform, some warnings should be treated as errors, otherwise it may cause unexpected issues at runtime: + +.. code:: cpp + + int func() { + } + + int other() { + return func(); + } + +Should fail to build with the following message: + +.. code:: console + + return-value.cpp: In function ‘int func()’: + return-value.cpp:2:1: error: no return statement in function returning non-void [-Werror=return-type] + 2 | } + | ^ + compilation terminated due to -Wfatal-errors. + cc1plus: some warnings being treated as errors + +Notice that ``-Werror=return-type`` is the default starting with Core 3.0.2 w/ GCC 10.3 + What is the Cause of Restart? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~