bug-gnulib
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Module with preprocessor utilities


From: Bruno Haible
Subject: Re: Module with preprocessor utilities
Date: Sun, 19 Jul 2020 17:43:12 +0200
User-agent: KMail/5.1.3 (Linux/4.4.0-179-generic; KDE/5.18.0; x86_64; ; )

Hi Marc,

> Besides modules to improve system compatibility, Gnulib contains a
> number of modules that provide "missing" functionality of the C
> standard library (like the gl_list module).
> 
> What would be the chances to include a module with sophisticated
> preprocessor macros like P99 ([1]) or the Boost Preprocessing library
> ([2])?

I can't speak for Paul, but I would go by these four criteria:

1) The module must be practically useful.

   To take an example from the P99 documentation:

   /** @brief Return a small prime number or 0 if @a x is too big **/
   P99_CHOICE_FUNCTION(uint8_t, p99_small_primes, 0,
                       2, 3, 5, 7, 11, 13, 17, 19, 23, 31, 37, 41, 43, 47,
                       53, 57, 59, 61, 67, 71);

   Any programmer can write such a function without macros.

2) Follow the principle "use the right tool for the job". If some code
   is better generated through m4 or through a template processor, do it
   that way, not through the C preprocessor.

3) Maintainability:

   * Limit the complexity.
     Since a user of such macro can only see the preprocessed (final)
     output of these macros, not the intermediate working, debugging a
     problem is hard. It is like with autoconf and m4: When something
     does not work as expected, the only way to proceed is to add or
     remove some tokens from the input and see what effects this has on
     the output. This is a tedious way of doing debugging.

   * Good documentation is a must. If you submit 100 lines of macros with
     150 lines of documentation, we'll reject it. For functions, it is OK
     to have suboptimal documentation, because the users can use a debugger.
     For macros this is not possible.

4) Portability.
   If there's a compiler that doesn't grok the code, you need to provide
   a reasonable workaround/fallback/replacement or drop the module entirely.

> It would be a header-only module and its functionality could grow over
> time.

A module should do one specific thing. If you want to add a different
functionality, add a new module.

> To allow for the latter in a backward compatible way, it would
> make sense to prefix all exported macros with GL_. The internal macros
> could be prefixed with _GL_.

Yes, this is OK; this is how we're doing it, and so far we have had very
few collisions with OpenGL.

> Such a module would have zero footprint in the library and could be
> used by other modules that  currently make use of ad-hoc definitions,
> for example the verify module, which defines _GL_CONCAT and
> _GL_COUNTER ([3]).

There is nothing wrong with these ad-hoc definitions. Generally it is wise
to use only as much macros as needed.

Bruno




reply via email to

[Prev in Thread] Current Thread [Next in Thread]