[CMake] Canonical use of FindPackageHandleStandardArgs

[Ryan Pavlik]

I took a quick look at your MySQL script and can offer these suggestions:

- The idiom that follows is outdated and unnecessary (no "if-else" 
needed because find_whatever won't run if the variable it's given 
already has a valid value, and find_package_handle... takes care of the 
silent bit.):

if(MYSQL_INCLUDE_DIR AND MYSQL_LIBRARY)
   # Already in cache, be silent
   set(MYSQL_FIND_QUIETLY TRUE)
else()

as is this (as above, the find_package_handle_standard_args takes care 
of it):
if(MYSQL_INCLUDE_DIR AND MYSQL_LIBRARY_DIR)
     set(MYSQL_FOUND TRUE)

- You probably don't want the find_library calls for the optional libs 
inside any sort of conditional - it's not necessary.

- Don't call include_directories or link_directories from your find 
script - let the user do that since you don't know what else they're 
using and you can't know if order for those is important - it might be.

- Search for dependent libraries like zlib (is there a stock find 
script?), yassl, taocrypt before the find_package_handle... call, and if 
they're needed, pass their variable name into that call.

- Be sure to set the plural versions of the variables (INCLUDE_DIRS, 
LIBRARIES) to include the dependencies (these should not be cached), and 
leave the singular version for just a single path/file (these should be 
cached, as by default

- Mark all variables as advanced except for a single variable that 
specifies a root to search, traditionally called something like 
MYSQL_ROOT_DIR.  If MYSQL_FOUND is true after the find_package_handle... 
call, then mark MYSQL_ROOT_DIR as advanced as well.  A good rule of 
thumb is to look at the simple view in ccmake or cmake-gui: if there's 
anything showing that doesn't require user attention (project build-time 
options, root_dir variables for missing dependencies), it should be 
advanced.


In your emailed example:
I presume the mylib in step 2 is different than the mylib in step 1 and 
3/4, because otherwise you have an infinitely-recursive find script. 
Please clarify, preferably with an actual example.

If the lib in step 2 is a dependency, convention varies, but it seems 
prudent to me to always find dependencies quietly: this prevents them 
from showing up in lists from FeatureSummary, etc.  Anything you require 
in that dependency package should be passed to your 
find_package_handle_standard_args call which will make the appropriate 
noises if it shouldn't be quiet and it can't be found.

If you're not doing find scripts that depend on other find scripts, then 
look in the archives from a month or so ago: I posted some "sample" find 
scripts that are modern and clean in style.  You can also take a peek at 
everything except FindDirectShow.cmake (I didn't write that one or 
rewrite it beyond running my cleanup app on it, and it's sorely in need 
of work) here: http://github.com/rpavlik/vrpn/tree/master/vrpn/cmake/

Hope this helps!

Ryan

On 03/03/2010 05:06 PM, Mateusz Loskot wrote:
> Hi,
>
> I'm writing some FindXXX.cmake macros [1] and I'd like to master some
> best practices I use and I'm having troubles with picturing what should
> canonical use of FindPackageHandleStandardArgs look like.
> I'm aware I've used it incorrectly in many places.
>
> I'm looking for confirmation if it should be something along
> these
>
> 1) Set lookup mode to quiet if user explicitly asked to find MYLIB
> quietly or if it's already found:
>
> if(MYLIB_FIND_QUIETLY OR MYLIB_FOUND)
>    set(FIND_MYLIB_QUIET_ARG QUIET)
> endif()
>
> 2) Call find passing selected lookup mode
>
> find_package(MYLIB ${FIND_MYLIB_QUIET_ARG})
>
> 3) Perform other checks, but do not call message() if
> MYLIB_FIND_QUIETLY is requested, otherwise lookup will not be really quiet
>
> 4) Check and report results
>
> find_package_handle_standard_args(MYLIB
>    DEFAULT_MSG MYLIB_LIBRARY MY_INCLUDE_DIR)
>
>
> Have I missed anything?
>
> [1] http://github.com/mloskot/workshop/blob/master/cmake/modules/
>
> Best regards,
>    

-- 
Ryan Pavlik
HCI Graduate Student
Virtual Reality Applications Center
Iowa State University

rpavlik at iastate.edu
http://academic.cleardefinition.com
Internal VRAC/HCI Site: http://tinyurl.com/rpavlik