Warning, /frameworks/kdelibs4support/cmake/modules/cmake-modules-styleguide.txt is written in an unsupported language. File is not indexed.
0001 This is a copy of the file CMake/Modules/readme.txt from cmake cvs. 0002 Please adhere to the guidelines given below when writing cmake modules 0003 for KDE. 0004 0005 Some additional guidelines for use in KDE: 0006 -indent using 2, 3 or 4 spaces, not tabs 0007 -use all-lower-case for commands, except if the rest of the file uses 0008 consistently all-upper-case for commands 0009 0010 Alex 0011 0012 ---------------------------------------------------------------------- 0013 0014 Note to authors of FindXXX.cmake files 0015 0016 We would like all FindXXX.cmake files to produce consistent variable names. 0017 0018 Please use the following consistent variable names for general use. 0019 0020 XXX_INCLUDE_DIRS The final set of include directories listed in one variable for use by client code. This should not be a cache entry. 0021 XXX_LIBRARIES The libraries to link against to use XXX. These should include full paths. This should not be a cache entry. 0022 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> 0023 XXX_EXECUTABLE Where to find the XXX tool. 0024 XXX_YYY_EXECUTABLE Where to find the YYY tool that comes with XXX. 0025 XXX_LIBRARY_DIRS Optionally, the final set of library directories listed in one variable for use by client code. This should not be a cache entry. 0026 XXX_ROOT_DIR Where to find the base directory of XXX. 0027 XXX_VERSION_YY Expect Version YY if true. Make sure at most one of these is ever true. 0028 XXX_WRAP_YY If False, do not try to use the relevent CMake wrapping command. 0029 XXX_YY_FOUND If False, optional YY part of XXX sytem is not available. 0030 XXX_FOUND Set to false, or undefined, if we haven't found, or don't want to use XXX. 0031 XXX_RUNTIME_LIBRARY_DIRS Optionally, the runtime library search path for use when running an executable linked to shared libraries. 0032 The list should be used by user code to create the PATH on windows or LD_LIBRARY_PATH on unix. 0033 This should not be a cache entry. 0034 XXX_VERSION_STRING A human-readable string containing the version of the package found, if any. 0035 XXX_VERSION_MAJOR The major version of the package found, if any. 0036 XXX_VERSION_MINOR The minor version of the package found, if any. 0037 XXX_VERSION_PATCH The patch version of the package found, if any. 0038 0039 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_DIRS should usually be defined (I guess libm.a might be an exception) 0040 0041 The following names should not usually be used in CMakeLists.txt files, but they may be usefully modified in users' CMake Caches to control stuff. 0042 0043 XXX_LIBRARY Name of XXX Library. A User may set this and XXX_INCLUDE_DIR to ignore to force non-use of XXX. 0044 XXX_YY_LIBRARY Name of YY library that is part of the XXX system. It may or may not be required to use XXX. 0045 XXX_INCLUDE_DIR Where to find xxx.h, etc. (XXX_INCLUDE_PATH was considered bad because a path includes an actual filename.) 0046 XXX_YY_INCLUDE_DIR Where to find xxx_yy.h, etc. 0047 0048 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. 0049 0050 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. 0051 0052 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. 0053 0054 To correctly document a module, create a comment block at the top with # comments. There are three types of comments that can be in the block: 0055 0056 1. The brief description of the module, this is done by: 0057 # - a small description 0058 0059 2. A paragraph of text. This is done with all text that has a single 0060 space between the # and the text. To create a new paragraph, just 0061 put a # with no text on the line. 0062 0063 3. A verbatim line. This is done with two spaces between the # and the text. 0064 0065 For example: 0066 0067 # - This is a cool module 0068 # This module does really cool stuff. 0069 # It can do even more than you think. 0070 # 0071 # It even needs to paragraphs to tell you about it. 0072 # And it defines the following variables: 0073 # VAR_COOL - this is great isn't it? 0074 # VAR_REALLY_COOL - cool right? 0075 # 0076 0077 To have a .cmake file in this directory NOT show up in the 0078 modules documentation, you should start the file with a blank 0079 line. 0080 0081 A FindXXX.cmake module will typically be loaded by the command 0082 0083 FIND_PACKAGE(XXX [major[.minor[.patch]]] [EXACT] 0084 [QUIET] [REQUIRED [components...]]) 0085 0086 If any version numbers are given to the command it will set the 0087 variable XXX_FIND_VERSION to contain the whole version. The variables 0088 XXX_FIND_VERSION_MAJOR, XXX_FIND_VERSION_MINOR, and 0089 XXX_FIND_VERSION_PATCH will be set to contain the corresponding 0090 portions of the version number. The variable XXX_FIND_VERSION_EXACT 0091 will indicate whether an exact version is requested. 0092 If the find module supports versioning it should locate a version of 0093 the package that is compatible with the version requested. If a 0094 compatible version of the package cannot be found the module should 0095 not report success. The version of the package found should be stored 0096 in the version variables named above. 0097 0098 If the QUIET option is given to the command it will set the variable 0099 XXX_FIND_QUIETLY to true before loading the FindXXX.cmake module. If 0100 this variable is set the module should not complain about not being 0101 able to find the package. If the 0102 REQUIRED option is given to the command it will set the variable 0103 XXX_FIND_REQUIRED to true before loading the FindXXX.cmake module. If 0104 this variable is set the module should issue a FATAL_ERROR if the 0105 package cannot be found. For each package-specific component, say 0106 YYY, listed after the REQUIRED option a variable XXX_FIND_REQUIRED_YYY 0107 to true. The set of components listed will also be specified in a 0108 XXX_FIND_COMPONENTS variable. This can be used by the FindXXX.cmake 0109 module to determine which sub-components of the package must be found. 0110 If neither the QUIET nor REQUIRED options are given then the 0111 FindXXX.cmake module should look for the package and complain without 0112 error if the module is not found. 0113 0114 To get this behaviour you can use the FIND_PACKAGE_HANDLE_STANDARD_ARGS() 0115 macro, as an example see FindJPEG.cmake.