[Cmake] Making the cmake FindXXX.cmake files more consistent

[Ian Scott]

Correction

> -----Original Message-----
> From: Ian Scott 
> Sent: Friday, September 06, 2002 3:57 PM
> To: 'Sebastien BARRE'; Cmake at Public. Kitware. Com (E-mail)
> Subject: RE: [Cmake] Making the cmake FindXXX.cmake files more
> consistent
> 
> 
> Sebastien Barre wrote:
> > Would you mind summarizing the new modules guidelines and
> > post that to the
> > list ?
> > I guess it would help maintainers/contributors to keep these
> > modules in a
> > clean state, or add features while trying to be consistent.
> 
> Certainly. (I'll copy this into /Modules/readme.txt for the future.)
> 
> These are the rules I have tried used to modify many of the 
> FindXXX.cmake
> module files. I'm not aware of anywhere I've had to deviate from them.
> 
> If you want to disagree with any of them, feel free. But I'd 
> be grateful if
> you could upgrade the modified files to fit any changes. (In 
> retrospect, I
> wish I had just used XXX_EXE instead of XXX_EXECUTABLE.)
> 
> The general usefulness of consistency became apparent when 
> the VXL team
> started using CMake. We have to negotiate use of system or 
> VXL-provided
> version of JPEG, etc. We are now using copies in VXL, of the 
> files in the
> current CMake repository snapshot. We expect to switch over 
> to getting them
> from the CMake Modules directory at the 1.6 release.
> 
> Please use the following consistent variable names for general use.
> 
> XXX_INCLUDE_DIR      Where to find xxx.h, etc. If for some reason, you
> really need two paths, then that shouldn't be a problem - 
> however, consider
> if you really should have two different FindXXX.cmake files.
> (XXX_INCLUDE_PATH was considered bad because a path includes an actual
> filename.)
> XXX_LIBRARIES        The libraries to link against to use 
> XXX. These should
> include full paths.
> XXX_DEFINITIONS      Definitions to use when compiling code 
> that uses XXX.
> This really shouldn't include options such as 
> (-DHAS_JPEG)that a client
> source-code file uses to decide whether to #include <jpeg.h>
> XXX_EXECUTABLE       Where to find the XXX tool.
> XXX_YYY_EXECUTABLE   Where to find the YYY tool that comes with XXX.
> XXX_ROOT_DIR         Where to find the base directory of XXX.
> XXX_VERSION_YY       Expect Version YY if true. Make sure at 
> most one of
> these is ever true.
> XXX_WRAP_YY	         If False, do not try to use the 
> relevent CMake wrapping
> command.
> XXX_YY_FOUND         If False, optional YY part of XXX sytem is not
> available.
> XXX_FOUND            Set to false, or undefined, if we 
> haven't found, or
> don't want to use XXX.
> 
> You do not have to provide all of the above variables. You 
> should provide
> XXX_FOUND under most circumstances. If XXX is a library, then
> XXX_LIBRARIES, should also be defined, and XXX_INCLUDE_DIR 
> should usually be
> defined (I guess libm.a might be an exception)
> 
> 
> The following names should not usually be used in CMakeLists.txt 
                             ^^^
> files, but they
> may be usefully modified in users CMake Cache to control stuff.
> 
> XXX_LIBRARY       Name of XXX Library. A User may set this and
> XXX_INCLUDE_DIR to ignore to force non-use of XXX.
> XXX_YY_LIBRARY    Name of YY library that is part of the XXX 
> system. It may
> or may not be required to use XXX.
> 
> 
> For tidiness's sake, try to keep as many options as possible 
> out of the
> cache, leaving at least one option which can be used to 
> disable use of the
> module, or locate a not-found library (e.g. XXX_ROOT_DIR). 
> For the same
> reason, mark most cache options as advanced.
> 
> If you need other commands to do special things then it 
> should still begin
> with XXX_. This gives a sort of namespace effect and keeps 
> things tidy for
> the user. You should put comments describing all the exported 
> settings, plus
> descriptions of any the users can use to control stuff.
> 
> You really should also provide backwards compatibility any 
> old settings that
> were actually in use. Make sure you comment them as 
> deprecated, so that
> no-one starts using them. Also useful would be a deprecation 
> mechanism ( eg
> IF(CMAKE_PROVIDE_1.4_VARIABLES) ) to help with the removal of the old
> values - however I haven't done this.
> 
> Ian.
> 
> 
> _______________________________________________
> Cmake mailing list
> Cmake at public.kitware.com
> http://public.kitware.com/mailman/listinfo/cmake
>