[BUG] Reasoning for FreeRTOS include policy

[swaldhoer]

Describe the bug

What's the rational for FreeRTOS - compared to other projects - different include
policy:

/* atomic.h */
#ifndef INC_FREERTOS_H
    #error "include FreeRTOS.h must appear in source files before include atomic.h"
#endif

Why not just include FreeRTOS.h? Include what you use is generally considered good pattern in C, which also makes sense.

If an analysis, unit testing tool (or what soever) needs to fake/mock something from FreeRTOS.h for e.g., when running on atomic.h, then the tool can just pass -DINC_FREERTOS_H as compiler argument.

Target

• Development board: any
• Instruction Set Architecture: any
• IDE and version: any
• Toolchain and version: any

Host

• Host OS: any
• Version: any

To Reproduce

• See the source code

Expected behavior
Just include what you use in source and header files.

[RichardBarry]

Many of the FreeRTOS coding conventions replicated a coding standard I was using in safety critical developments prior to writing FreeRTOS. In this case, don't include one header file from another to make sure developers and maintainers have a clear picture of exactly what is being brought into a C file, with no unseen dependencies. That is why FreeRTOS.h is included manually before the API header files such as queue.c (file name namespace clashes being another story) rather than included multiple times from each API header directly. My own experience of going down rabbit holes of trying to follow includes from includes from includes in other libraries shows, for myself at least, this to be a valuable policy. Unfortunately, the portability of FreeRTOS means some header files that define architecture specifics must be included in the right order ref header files that define configurations and configuration defaults - so the "don't include one header from another" rule is broken in places where getting it right is deemed to much of a burden for developers.

[aggarg]

As explained by @RichardBarry, this is a deliberate choice and we do not intend to change it as of now. I am closing this issue. Feel free to re-open or create a new one if you need anything else.