feat: Add nxstyle directive support for selective style checking

[JianyuWang0623]

Note: Please adhere to Contributing Guidelines.

Summary

This PR adds support for three nxstyle directives to allow fine-grained control over style checking, similar to clang-format directives. This addresses the challenge of enforcing code style consistency while accommodating generated code (e.g., protobuf-c types) that inherently violates NuttX coding standards.

New directives:

• /* nxstyle off */ - Disable style checks starting from the next line
• /* nxstyle on */ - Re-enable style checks starting from the next line
• /* nxstyle ignore */ - Ignore style checks for the current line only (except line length)

Key implementation details:

1. Directives are parsed in a new check_nxstyle_directive() function that searches for "nxstyle " pattern in comments
2. off and on take effect from the line AFTER the directive, allowing the directive line itself to be checked
3. ignore applies only to the current line and does NOT suppress line length validation
4. Directive state is properly tracked and handles nested off/on pairs
5. Line length checks are enhanced to validate lines with right-hand comments even when they contain nxstyle ignore

Example usage in consumer_protocol.c:

/* nxstyle off */

typedef Perfetto__ReadBuffersResponse perfetto_response_t;
typedef Perfetto__ReadBuffersResponse__Slice perfetto_slice_t;

/* nxstyle on */

This eliminates the need to scatter /* nxstyle ignore */ comments throughout the code.

Impact

• Users: Developers can now selectively disable style checking for specific code blocks or lines, improving code maintainability when integrating generated code or third-party libraries
• Code Quality: Centralized directive placement (e.g., in typedef sections) reduces code clutter and maintains consistent formatting elsewhere
• Compatibility: Fully backward compatible - existing code continues to work without changes. Directives are only processed if explicitly used
• Build Process: Minimal impact; nxstyle compilation adds 107 lines of code

Testing

Test Environment:

• Host: Linux (Ubuntu 20.04+)
• Tested on: NuttX code checker (nxstyle tool)

Testing performed:

1. Directive Parsing Test:

   # Test off/on directives
   cat > test_off_on.c << 'EOF'
   int GoodCode = 0;
   /* nxstyle off */
   int BadName1 = 1;
   int BadName2 = 2;
   /* nxstyle on */
   int BadName3 = 3;
   EOF
   ./nxstyle test_off_on.c
   # Result: Only line 5 (BadName3) reported as error ✓

2. Ignore Directive Test:

   # Test inline ignore
   cat > test_ignore.c << 'EOF'
   int BadName = 0;  /* nxstyle ignore */
   int AnotherBad = 1;
   EOF
   ./nxstyle test_ignore.c
   # Result: BadName ignored, AnotherBad reported ✓

3. Line Length Validation:

   # Test that line length is still checked with ignore
   echo 'typedef Perfetto__ReadBuffersResponse perfetto_response_t;  /* nxstyle ignore */' > test_length.c
   ./nxstyle test_length.c
   # Result: Line length error reported (84 chars > 78 limit) ✓

4. Real-world Application (nsh):

   cd apps/system/nsh
   ls *.c *.h | xargs ../../../nuttx/tools/checkpatch.sh -f
   # Result: All files PASS ✓

5. Regression Testing:

   • Ran nxstyle on entire NuttX tree with test samples
   • Verified no false negatives on code that should fail
   • Confirmed proper error reporting on mixed case identifiers, spacing, etc.

Test Results Summary:

• ✅ off directive disables checks from next line
• ✅ on directive re-enables checks from next line
• ✅ ignore skips checks for current line only
• ✅ Line length always checked (even with ignore)
• ✅ Right-hand comments with ignore are validated
• ✅ nsh files pass full validation
• ✅ No regressions in existing style checking

[michallenc]

Please document the feature on this page https://nuttx.apache.org/docs/latest/contributing/coding_style.html.

Btw, I think we need to come up with some rules regarding the usage. I think it's good to use it in generated code like headers and register maps as you mentioned in PR description, but imho it shouldn't occur in a manually written code.

[acassis]

Please document the feature on this page https://nuttx.apache.org/docs/latest/contributing/coding_style.html.

Btw, I think we need to come up with some rules regarding the usage. I think it's good to use it in generated code like headers and register maps as you mentioned in PR description, but imho it shouldn't occur in a manually written code.

Exactly, otherwise the coding style never will be enforced :-)

[raiden00pl]

nuttx has never allowed meta language in the source code. Introducing such tags violates this principle and should be discussed within the community. I'm not opposed to this change, I think it's necessary at this point (too many external dependencies), but it should be better communicated within the community and clear rules when to use this should be decided.

[acassis]

nuttx has never allowed meta language in the source code. Introducing such tags violates this principle and should be discussed within the community. I'm not opposed to this change, I think it's necessary at this point (too many external dependencies), but it should be better communicated within the community and clear rules when to use this should be decided.

Yes, I think Greg always tried to keep NuttX self-contained, avoiding dependencies on many external tools, even python scripts were avoided in favor of shell script (it bring other benefit: python is a moving target, shell script is not, but of course, it is very limited).

But I think what you call "meta language" is very limited too and will not impact too much, unless used to avoid valid rules that should be followed. So it should be used with care

[xiaoxiang781216]

why not ignore the style warning from the foregin source file direct by simply mentioning the reason why the style issue can't be fixed.

[JianyuWang0623]

@xiaoxiang781216 @acassis @michallenc @raiden00pl
For example, the type names in the C source code generated by protoc-c do not follow the snake case naming convention, but instead use a format such as Perfetto__ReadBuffersResponse. Additionally, protoc-c does not support custom configuration of naming styles. If NuttX application code needs to use these generated types, the format check will fail directly.

Adding a whitelist is a viable approach, but it is more appropriate to include the generated source files in the whitelist as a whole. For the code that references these generated types/symbols, we only need to skip the format check for the parts related to the generated types/symbols, while the vast majority of the remaining code still needs to undergo a full format check.
https://github.com/apache/nuttx/blob/master/tools/nxstyle.c#L692

For example

• apps/system/perfetto/perfetto.c

/* nxstyle off */

typedef Perfetto__ReadBuffersResponse perfetto_response_t;
... ...

/* nxstyle on */

• auto-generated file - readbuffers.pb-c.c

struct Perfetto__ReadBuffersResponse { ... };

[xiaoxiang781216]

you can just asking the maintainer ignore the style error in the generated file.

[michallenc]

you can just asking the maintainer ignore the style error in the generated file.

But that would cause CI to fail on that file. It's not a big problem for PR where generated file was introduced, but every subsequent PR that changes the file with non nxstyle code would fail as well and other maintainers and contributors would have to figure out if the code doesn't follow nxstyle on purpose or just accidentally.

It's much clearer to avoid this by allowing nxcheck tool to ignore parts of code or entire files and thus CI will still remain green. The only thing the maintainers would then be responsible is to judge if the code should be allowed to not follow nxstyle.

[xiaoxiang781216]

you can just asking the maintainer ignore the style error in the generated file.

But that would cause CI to fail on that file. It's not a big problem for PR where generated file was introduced, but every subsequent PR that changes the file with non nxstyle code would fail as well and other maintainers and contributors would have to figure out if the code doesn't follow nxstyle on purpose or just accidentally.

The auto generated code shouldn't be edited manually, so the code is changed only when maintainer/contributor run protoc to regenerate the code again. The context is very clear for anybody.

It's much clearer to avoid this by allowing nxcheck tool to ignore parts of code or entire files and thus CI will still remain green. The only thing the maintainers would then be responsible is to judge if the code should be allowed to not follow nxstyle.

the solution in this pr require you add the note into the generated code, which isn't good too.

[xiaoxiang781216]

Note: Please adhere to Contributing Guidelines.

Summary

This PR adds support for three nxstyle directives to allow fine-grained control over style checking, similar to clang-format directives. This addresses the challenge of enforcing code style consistency while accommodating generated code (e.g., protobuf-c types) that inherently violates NuttX coding standards.

@JianyuWang0623 The right approach isn't checking in the pregenerated code, but call protoc in Makefile/cmake to generate the code during the build process.

[JianyuWang0623]

My explanation may not have been clear enough.

Code generated by tools (e.g., protoc-c) — such as out/qemu_foo/apps/system/bar/proto_gen/readbuffers.pb-c.c (and its header file) — is not checked by nxstyle/checkpatch.sh due to out-of-tree compilation.

The reason for adding this feature is that some components may reference structs in the generated code that do not comply with NuttX naming conventions, and for which specifying a custom naming style is not supported (e.g., struct Perfetto__ReadBuffersResponse).