Annotate functions with macros

824

Also as pointed out - these macro can't be expanded to something meaningful - for example if you write this macro couple of time it will affect nothing.

Another nice use can be - (useful in testing of code) from here

You can pass -DFLUTTER_EXPORT=SOMETHING while using gcc. This will be useful in running your code for testing purposes without touching the codebase. Also this can be used in providing different kind of expnasion based on the compile time passed parameter - which can be used in different ways.

Also a significant part of my answer boasts of the visibility using the empty macro, gcc also provides a way to realize the same thing as described here using __attribute__ ((visibility ("default"))) (as IharobAlAsimi/nemequ mentioned) (-fvisibility=hidden) etc for the macro FLUTTER_EXPORT. The name also gives us a idea that it might be necessary to add the attribute __declspec(dllimport) (which means it will be imported from a dll). An example regarding gcc's usage of visibility support over there will be helpful.


It can useful in associating some kind of debug operation like this (By this I mean that these empty macros can be used like this also - though the name suggests that this was not the intended use)

#ifdef FLUTTER_EXPORT
#define ...
#else
#define ...
#endif

Here #define here will specify some printing or logging macro. And if not defined then it will be replaced with something blank statement. do{}while(0) etc.

Share:
824
Author by

AdaShoelace

Updated on December 04, 2022

Comments

  • AdaShoelace 19 days

    I'm looking into Flutters embedder API because I might be calling it via Rust in an upcoming project and find this:

    FLUTTER_EXPORT
    FlutterResult FlutterEngineShutdown(FlutterEngine engine);
    

    The FLUTTER_EXPORT part is (from what I can see) a macro defined as:

    #ifndef FLUTTER_EXPORT
    #define FLUTTER_EXPORT
    #endif // FLUTTER_EXPORT
    

    I'm by no means a C guru but I have done my fair share of C programming but have never had the opportunity to use something like this. What is it? I've tried to Google it but don't really know what to call it other than "annotation" which doesn't really feel like a perfect fit.

    Flutter embedder.h

    • Pablo
      Pablo almost 5 years
      Is your question what is a macro or what does this macro lines do?
    • Some programmer dude
      Some programmer dude almost 5 years
      Depending on platform functions in a library might need compiler-specific qualifiers. By having a macro such as FLUTTER_EXPORT is a handy way to do that. If being build by a compiler that needs these special qualifiers, then the macro will be defined with a body that expands to them, otherwise it will expand as nothing.
    • Iharob Al Asimi
      Iharob Al Asimi almost 5 years
      This can be used with a static code analyzer. Or, the macro could actually expand to something else in different platforms, for instance on Windows you would need ad __declexport or something similar to export symbols from a dll.
    • AdaShoelace almost 5 years
      Excuse the ambiguity of the question. Since the macro does not take a value (is not a symbolic constant) or does not seem to contain any code, why is it called before every function declaration in the header?
    • Pablo
      Pablo almost 5 years
      Like IharobAlAsimi said, the macro might be set by another header file that is only included when compiling on windows where it's value could be __declexport. That's why your header file might first check if it's already defined and if not, it defines an "empty" one.
    • Jonathan Leffler
      Jonathan Leffler almost 5 years
      It is likely so that you can use something like __declspec(dllexport) (or perhaps __declspec(dllimport)) in a Windows DLL. There are a number of annotations that can be used to decorate functions in Windows (in particular; there are function attributes in GNU C, and even in standard C with things like _Noreturn; see also Visibility).
    • nemequ
      nemequ almost 5 years
      It's defined as __attribute__((visibility("default"))) at github.com/flutter/engine/blob/… . I'm not sure Flutter can be build on MSVC, but if it can there is probably somethnig which defines it to __declspec(dllexport).
  • Iharob Al Asimi
    Iharob Al Asimi almost 5 years
    Note that this macro cannot expand to a statement.
  • AdaShoelace almost 5 years
    It's the fact that the macro is "empty" that confused me.
  • user2736738
    user2736738 almost 5 years
    @MasterBait.: Well like I said - if you write it and you will see that this expands to no statement - the only use i can think of is mentioned.
  • Iharob Al Asimi
    Iharob Al Asimi almost 5 years
    @MasterBait The macro can be defined at compile time too, for instance with gcc you can do -DFLUTTER_EXPORT=SOMETHING and it might be used like that in this case.
  • user2736738
    user2736738 almost 5 years
    @IharobAlAsimi.: Hey thanks...this was interesting. I guess even I used it once and forgot. :)
  • Iharob Al Asimi
    Iharob Al Asimi almost 5 years
    Now your answer is a lot better. But point out, that given the name FLUTTER_EXPORT, perhaps it really means exactly that. There is a gcc way to control visibility of symbols and similar features are present in MS C/C++ compiler.
  • nemequ
    nemequ almost 5 years
    I think he's suggesting that FLUTTER_EXPORT may be defined to __declspec(dllexport) when building on MSVC, or __attribute__((visibility("default"))) on GCC. It may also be necessary to define it to __declspec(dllimport) (or maybe extern) sometimes when consuming the API, too… Based on the name, that would be my guess, too.
  • user2736738
    user2736738 almost 5 years
    @nemequ.: Yes it seems you are right..I was reading the link mentioned in my answer. Thanks a lot.
  • user2736738
    user2736738 almost 5 years
    @IharobAlAsimi.: I guess edit is making things clear.
  • nemequ
    nemequ almost 5 years
    dllexport isn't quite the same thing as default visibility (and dllimport is nothing like hidden visibility)… And, based on the name and usage, this macro has nothing to do with debugging statements.
  • user2736738
    user2736738 almost 5 years
    @nemequ.: Yes I am going really weird over the sleepy edge..I edited that's why "default"...but I don't get this with debugging statements? I have used the similar thing for debugging. That's why I mentioned it. The question was initially why these macros exist...I stated that's why.
  • user2736738
    user2736738 almost 5 years
    @nemequ.: I am open to your opinion...all i am saying is this similar thing can be used in testing ot debugging also (maybe it;s a stupid way - maybe there is much much better way to do it ) but there is a way to do it the way I mentioned like that too. What you said is much more relevant regarding dllimport in context of visibilty...You can let me know of your opinion.
  • user2736738
    user2736738 almost 5 years
    @nemequ.: I get your concern - you are saying that FLUTTER_EXPORT might not have direct correspondence with debugging like I said - but it can be used as one (I have seen similar to it used like that)...I have eduted my answer to clarify that.
  • Iharob Al Asimi
    Iharob Al Asimi almost 5 years
    @nemequ, You might be right. I only know that on a Windows system you need to export dll symbols. But I have never been interested in GNU's visibility, which I don't fully know. I am gonna read about it right now and learn about it.
  • user2736738
    user2736738 almost 5 years
    @nemequ.: Check the edit. I guess I get your earlier comment.
  • nemequ
    nemequ almost 5 years
    Okay, so my comments weren't going to fit in a… well, comment, so I banged out a quick answer. I think you mostly answered the original question, but a lot of stuff came up in the comments and in your answer that I wanted to address.
  • user2736738
    user2736738 almost 5 years
    @nemequ.: I will go through your answer when I get time. On the other hand, I guess somebody downvoted - like 3 edits earlier. The answer is modified after that. I guess I will go through my points again. Because I guess none of them is incorrect. Thanks for the comment.