Addition of tables summarizing preprocessing macros and flags

[jvdp1]

As suggested by @jalvesz in his comment, here is a PR to introduce tables that summarize fypp and C-preprocessing flags and macros.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.69%. Comparing base (af58730) to head (afe8a59).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1083      +/-   ##
==========================================
+ Coverage   68.60%   68.69%   +0.08%     
==========================================
  Files         393      393              
  Lines       12710    12720      +10     
  Branches     1377     1376       -1     
==========================================
+ Hits         8720     8738      +18     
+ Misses       3990     3982       -8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jalvesz]

Thanks for adding the table @jvdp1, here a couple of minor edits

[perazz]

Thank you for this work @jvdp1. I guess this is more of a style comment rather than a content one. Regarding "optional" functionality either from "modularized" components or external libraries, some macros are affirmative and some are negative. I wonder if it is still early enough that this behavior could be standardized?

For example:

• only use affirmative version -> defined(STDLIB_BITSET) vs. !defined(STDLIB_BITSET)
• only use boolean formulation (I believe the C preprocessor treats boolean exactly in the same way as an integer 0/1, so this may just be different syntactic sugar - no need to change functionality).

[jvdp1]

..., some macros are affirmative and some are negative. I wonder if it is still early enough that this behavior could be standardized?

I think it is the right time to discuss about it ;) because we didn't communicate on most of them yet.
We discussed them in #1050 (and also a bit in #1049). However, I also don't feel comfortable with some of them yet (especially the negative versions in CMake).

Currently the default behaviour for stdlib is that everything is enabled/compiled, and that the user can disable some features/modules manually.

With CMake, this default behaviour can be easily implemented. Macros like STDLIB_NO_BITSETS could be easily changed to STDLIB_WITH_BITSETS or STDLIB_BITSETS.

The main issue is with fpm and the file macros.inc. To not modify the fpm.toml file of stdlib, and to keep affirmative macros in the source code, the file macros.inc was introduced (with negative macros) to define affirmative macros per default:

...
!Default: compile the bitset module
#ifdef STDLIB_NO_BITSET
#define STDLIB_BITSET 0
#else
#define STDLIB_BITSET 1
#endif
...

If I am correct, it was argued in #1050 to use #define STDLIB_BITSET 1 for readibility and flexibility, instead of boolean macros. I have no preferences; however, I agree this approach provides some flexibility that may be needed later.

\cc @jalvesz

[perazz]

I agree that the positive form is definitely superior @jvdp1, I also personally think the STDLIB_WITH_BITSETS is also more clear than STDLIB_WITH_BITSETS == 1, so my vote would definitely go for the boolean form

[jvdp1]

I agree that the positive form is definitely superior @jvdp1, I also personally think the STDLIB_WITH_BITSETS is also more clear than STDLIB_WITH_BITSETS == 1, so my vote would definitely go for the boolean form

Any ideas how we should deal with fpm and macros.inc such that the default is that all macros are defined?

[jalvesz]

If I'm not understanding correctly the discussion please let me know. Maybe one way to simplify things would be to unify in a single macro variable per library using only the positive version:

!--------- macro
#ifndef STDLIB_BITSET
#define STDLIB_BITSET 1
#endif

!--------- usage
#if STDLIB_BITSET
print *, "hello"
#else
print *, "goodbye"
#endif

end

• With -cpp gives hello
• With -cpp -DSTDLIB_BITSET=1 gives hello
• With -cpp -DSTDLIB_BITSET=0 gives goodbye

I think it would be less confusing as there is just one variable to manage.

[perazz]

Any ideas how we should deal with fpm and macros.inc such that the default is that all macros are defined?

With the positive form, I believe the deployment script should generate the macros.inc file from scratch every time - containing all relevant macro definitions.

If this is the case, perhaps it would be better (/more robust?) to just put them in fpm.toml?. The macros would then be defined across the whole stdlib package instead of being limited to the file where macros.inc is included.

[jalvesz]

I think the existence of the macro.inc file being self-contained is the most robust and simple solution. No need to change anything elsewhere. Either with CMake or FPM, one would just modify to change the default behavior.

[perazz]

Either with CMake or FPM, one would just modify to change the default behavior.

This was not possible with FPM as it did not parse macros, at least until recently

[jalvesz]

I see, so we need a solution that is simple and robust across: CMake, FPM (and pure make file?) build systems.

I thought about the .inc as a place-holder for all such definitions, which is Fortranic enough, the fpm.toml file solution is only useful for fpm.

Without an include file, the only alternative solution would be to have a centralized file with all macros as flags that can be added to the list of build time flags.

[jalvesz]

@perazz sorry if I don't get still the details of the issue, I had already used include files previously without any problems with fpm: https://github.com/jalvesz/fast_math/tree/main/src/utilities. Is the issue related to macros.inc being outside of the src folder? If such, it ought to be moved inside.