scimakeCodingConventions

scimake Coding Conventions

Committee included: Roopa Pundaleeka, David Alexander, Nanbor Wang, Steve Goldhaber, Matt Koch, Marc Durant & Anne Hammond

Objectives

• Ease and standardize coding of CMakeLists.txt and Module files
• Avoid having updates to scimake repo break builds of products
• Resource for getting started using scimake
• Recommendations that will help developers create and manage a new project using scimake

Recommended resources and best sources of help

• cmake --help and cmake --help-{feature name}
• http://cmake.org/cmake/help/cmake-2-8-docs.html
• Search for specific issues in mailing list (kitware mailing list for CMake, may list bugs with workaround)

CMake versions

• 2.8.6 is the currently used version on Tech-X systems; bilder builds 2.8.6 if not found by bilder
• The top CMakeLists.txt files SHOULD list the minimum version of CMake required by the build.
• The scimake repo trunk SHOULD follow the latest release of CMake, and other versions SHOULD be branched.

Module Conventions in scimake

• By default, use the standard module files available.
• From scratch: In the case where there is no module file available for package "xyz" from cmake.org, create a new file called "FindSciXyz.cmake" under scimake/Modules/
• If there is a module file available from cmake.org, but is missing some functionalities (to make it Tech-X standards compliant: add SUPRA_SEARCH_PATH additional directories, or define additional variables, etc.) that may be required by Tech-X projects, create a new file called "FindSciXyz.cmake" to add the functionality and include the FindXyz.cmake. In other words, reuse the standard module file as much as possible.
  • The reason for extending the stock cmake module MUST be provided at the top of the file.
  • If you decide not to include the stock cmake module into your module, a detailed explanation of the reason MUST be documented at the top of the new module file created.
• Modules SHOULD be able to make effective use of the SUPRA_SEARCH_PATH as a path holding directories under which to look for the headers and libraries or for the root. The search order SHOULD be XXX_DIR defined on the cmake invocation line, then XXX_DIR defined in the environment, then the appropriate sub directories of SUPRA_SEARCH_PATH and then the SUPRA_SEARCH_PATH itself.
• Extra diagnostic information SHOULD be made available when DEBUG_CMAKE is true.
• Incorporate documentation/notes into your module file so that the "cmake --help -module" will give help information for the module including the reasons for developing a new or extended scimake module.

Module File Naming Convention

• All modules created under scimake/Modules MUST have a "Sci" prefix irrespective of whether they are created from scratch or an extension to an existing cmake module. This convention will help a developer figure out if a project is using the cmake stock module or a scimake module.
• The package name MUST be camel cased irrespective of what it is in cmake:
  For example:
  

    If the file name is FindGIF.cmake in cmake, the corresponding file name
    for a Tech-X extension SHOULD be FindSciGif.cmake.
    The call to find the GIF package using the new module file will now be 
    "find_package(SciGif ...)"

• If both cmake module and the scimake extension to it are available, then the scimake extension MUST be used, as there would have been a really good reason to extend it in the first place.

CMakeLists.txt Conventions

• All Tech-X standard coding standards apply.
• All commands in lower case.

    Ex:
      if (...)
        ...
      else ()
        ...
      endif ()

• All keywords are upper case.
• Variable names - Package name followed by underscore followed by all caps.

    Ex:
    For package XyZ, the variable names SHOULD be something like Xyz_ALL_CAPS

CMake Coding Conventions

• Consistent variable names as described in the CMake conventions:
  XXX_INCLUDE_DIRS, XXX_LIBRARIES, XXX_LIBRARY_DIRS, XXX_FOUND, etc.
• Additional Tech-X variables:
  • ENABLE_XXX: Defaults to true. If set to false, then do not look for XXX.
  • HAVE_XXX : If XXX is found, this is set to true so that config-cmake.h can be created.
  • XXX_DLLS : (Windows) the absolute paths to any dlls found.
  • XXX_STLIBS: Contains the static libraries of a package, as needed for linking on some LCFs and/or to simplify distribution of applications. SciGetStaticLibs is a useful macro for this purpose.
• All .cmake and .txt files SHOULD have svn:eol-style set and SHOULD have svn:keywords set to "Author Date Id Revision" in ~/.subversion/config. This can be done easily with the Tech-X standards for the ~/.subversion/config. All files SHOULD have the id string near the top:

    *.cmake = svn:eol-style=native; svn:keywords=Author Date Id Revision
    *.txt = svn:eol-style=native; svn:keywords=Author Date Id Revision

• Files SHOULD NOT use tabs, only spaces. Indent by two spaces.
• Temporary variables SHOULD be unset and made sure they don't show up in the CMakeCache.txt file.

Recommendations and Good Practices

• You SHOULD NOT commit a change to the scimake repo trunk that works only with the latest release of CMake, without creating a branch for the previous version of CMake.
• Out of source build is recommended: create a new directory, cd to that directory, and run cmake with the path to the source directory.
• rm -rf CMakeFiles CMakeCache.txt (similar to config/cleanconf) SHOULD be enough to rebuild.
• It is not recommended to change CMake's default policies, as it is possible to modify CMake behaviour by modifying its policies.
• Create config files in each project using CMake like {package}config.cmake.in with information about external packages used, versions, etc.
  • This, when installed, can be used by other projects using this project as an external project to figure out correct dependencies automatically by CMake.
  • Use a flag to suppress using FindSciPackage.cmake to find this package if a config file is available.
  • Would be helpful for projects like txbase and txphysics.

Warnings / Developer Notes

• CMake by default does not give error messages when a variable that is not set is being used.
• When performing a string comparison where one of the operands is a variable, that variable SHOULD be enclosed in quotation marks.

    Ex: 
     if (${X} == "test") -- Will crash CMake if variable X is the empty string

     Instead use:[[br]]
     if ("${X}" == "test")

Fortran and CMake

• If a module relies on fortran, it should locate the fortran-mod files.