If FindDoxygen.cmake is to adhere to the naming conventions prescribed by cmake-developer, then...?

Code
1

Hello, CMake Team.

From the current built-in FindDoxygen.cmake, we can see that some of the related variables/import target names are as follows:

Click to expand 
#
# Version Variables
#
DOXYGEN_VERSION
#
# Executable variables
#
DOXYGEN_EXECUTABLE
DOXYGEN_DOT_EXECUTABLE
DOXYGEN_MSCGEN_EXECUTABLE
DOXYGEN_DIA_EXECUTABLE
#
# Whether the component/module is found
#
DOXYGEN_FOUND
DOXYGEN_doxygen_FOUND
DOXYGEN_dot_FOUND
DOXYGEN_mscgen_FOUND
DOXYGEN_dia_FOUND
#
# Imported Targets
#
Doxygen::doxygen
Doxygen::dot
Doxygen::mscgen
Doxygen::dia

According to the Standard Variable Names section in the cmake-developer manual, if we were to modify FindDoxygen.cmake today without considering backward compatibility, or say a user creates their own FindDoxygen.cmake for their project, should it be modified to the following form:

Click to expand 
#
# Version Variables
#
Doxygen_VERSION
Doxygen_VERSION_MAJOR
Doxygen_VERSION_MINOR
Doxygen_VERSION_PATCH
#
# Executable Variables 
# (Xxx_YYY_EXECUTABLE)
#
Doxygen_DOXYGEN_EXECUTABLE
Doxygen_DOT_EXECUTABLE
Doxygen_MSCGEN_EXECUTABLE
Doxygen_DIA_EXECUTABLE
#
# Whether the module/component is found
# (Xxx_FOUND and Xxx_Yyy_FOUND)
#
Doxygen_FOUND
Doxygen_Doxygen_FOUND
Doxygen_Dot_FOUND
Doxygen_Mscgen_FOUND
Doxygen_Dia_FOUND
#
# Imported Targets
#
Doxygen::Doxygen
Doxygen::Dot
Doxygen::Mscgen
Doxygen::Dia

And the way we include FindDoxygen.cmake with find_package() should be:

find_package(Doxygen
    REQUIRED
    COMPONENTS
        Doxygen 
    OPTIONAL_COMPONENTS
        Dot Mscgen Dia)

Am I correct?

2

Yes, that seems to be a much more modern API and variable set than the existing one.

1 Like
3

@ben.boeckel

Thanks for your replies!

However, there’s a derived question bothering me:

Should we capitalize the 1st character of the components?

To be more specific, should we name those components to:

  1. yyy (Keep the case as same as those executables)

    Doxygen::doxygen
Doxygen::dot
Doxygen::mscgen
Doxygen::dia

  2. Yyy (Capitalize the 1st character of those executables)

    Doxygen::Doxygen
Doxygen::Dot
Doxygen::Mscgen
Doxygen::Dia

Which one is recommended?

IMO, I prefer the Yyy one. However, I found a counterexample which deprecated the Yyy form and recommended the yyy form. That is, FindGTest.cmake.

4

I think matching the component names is best.

5

I think matching the component names is best.

Do you mean the 1st one, yyy? Just like what FindGTest does?

But I actually found some modern Find modules which adopted the 2nd one, Yyy:

What are your opinions on these?

6

I mean that if one does find_package(Foo COMPONENT COMP1 comp2), I think I would expect to see Foo::COMP1 and Foo::comp2 (assuming the components correspond to targets).

7

I mean that if one does find_package(Foo COMPONENT COMP1 comp2) , I think I would expect to see Foo::COMP1 and Foo::comp2 (assuming the components correspond to targets).

I totally agree this. But what confuses me now is that:

Take FindDoxygen.cmake and FindGettext.cmake for example. Their utilites’ names are all lowercase:

  • For FindDoxygen.cmake:

    doxgyen.exe
dot.exe
dia.exe
mscgen.exe

  • For FindGettext.cmake:

    xgettext.exe
msgcat.exe
msgmerge.exe
...etc

When we define its known components, should we intentionally capitalize those utilities’ 1st character as their corresponding components’ name? For example:

  • For FindDoxygen.cmake:

    # Call
find_package(Doxygen COMPONENTS Doxygen Dot Dia Mscgen)
# Get
Doxygen::Doxygen
Doxygen::Dot
Doxygen::Dia
Doxygen::Mscgen

  • For FindGettext.cmake:

    # Call
find_package(Gettext COMPONENTS Xgettext Msgcat Msgmerge)
# Get
Gettext::Xgettext
Gettext::Msgcat
Gettext::Msgmerge
8

I find the capitalization weird myself.

9

Should we capitalize the 1st character of the components?

@ben.boeckel I want to make a conclusion on this derived question:

  1. It’s not required to capitalize the 1st character of the components.
  2. Whether it is Yyy or yyy should be fine.
  3. It depends on the code style that the author of a module prefers.

What do you think?

10

Yep, that sounds good to me.

1 Like