diff options
| -rw-r--r-- | Docs/cmake-completion | 10 | ||||
| -rw-r--r-- | Modules/CPack.cmake | 89 | ||||
| -rw-r--r-- | Modules/CPackComponent.cmake | 12 | ||||
| -rw-r--r-- | Modules/CPackDeb.cmake | 38 | ||||
| -rw-r--r-- | Modules/CPackRPM.cmake | 109 | ||||
| -rw-r--r-- | Source/CMakeLists.txt | 2 | ||||
| -rw-r--r-- | Source/CPack/cmCPackDocumentMacros.cxx | 16 | ||||
| -rw-r--r-- | Source/CPack/cmCPackDocumentMacros.h | 21 | ||||
| -rw-r--r-- | Source/CPack/cmCPackDocumentVariables.cxx | 32 | ||||
| -rw-r--r-- | Source/CPack/cmCPackDocumentVariables.h | 21 | ||||
| -rw-r--r-- | Source/CPack/cpack.cxx | 95 | ||||
| -rw-r--r-- | Source/CursesDialog/ccmake.cxx | 1 | ||||
| -rw-r--r-- | Source/QtDialog/CMakeSetup.cxx | 1 | ||||
| -rw-r--r-- | Source/cmCommand.h | 11 | ||||
| -rw-r--r-- | Source/cmDocumentation.cxx | 457 | ||||
| -rw-r--r-- | Source/cmDocumentation.h | 68 | ||||
| -rw-r--r-- | Source/cmFunctionCommand.cxx | 11 | ||||
| -rw-r--r-- | Source/cmMacroCommand.cxx | 11 | ||||
| -rw-r--r-- | Source/cmake.cxx | 4 | ||||
| -rw-r--r-- | Source/cmakemain.cxx | 1 | ||||
| -rw-r--r-- | Source/ctest.cxx | 1 |
21 files changed, 911 insertions, 100 deletions
diff --git a/Docs/cmake-completion b/Docs/cmake-completion index d82d608..d70ac24 100644 --- a/Docs/cmake-completion +++ b/Docs/cmake-completion @@ -130,6 +130,16 @@ _cpack() COMPREPLY=( $(compgen -f ${cur}) ) return 0 ;; + --help-variable) + local running=$(for x in `cpack --help-variable-list | grep -v "cpack version" `; do echo ${x} ; done ) + COMPREPLY=( $(compgen -W "${running}" -- ${cur}) ) + return 0 + ;; + --help-command) + local running=$(for x in `cpack --help-command-list | grep -v "cpack version" `; do echo ${x} ; done ) + COMPREPLY=( $(compgen -W "${running}" -- ${cur}) ) + return 0 + ;; *) ;; esac diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake index 2cc27cf..8a44991 100644 --- a/Modules/CPack.cmake +++ b/Modules/CPack.cmake @@ -1,5 +1,7 @@ -# - Build binary and source package installers -# +##section Variables common to all CPack generators +##end +##module +# - Build binary and source package installers. # The CPack module generates binary and source installers in a variety # of formats using the cpack program. Inclusion of the CPack module # adds two new targets to the resulting makefiles, package and @@ -29,16 +31,16 @@ # on a per-generator basis. It only need contain overrides. # # Here's how it works: -# - cpack runs -# - it includes CPackConfig.cmake -# - it iterates over the generators listed in that file's -# CPACK_GENERATOR list variable (unless told to use just a -# specific one via -G on the command line...) +# - cpack runs +# - it includes CPackConfig.cmake +# - it iterates over the generators listed in that file's +# CPACK_GENERATOR list variable (unless told to use just a +# specific one via -G on the command line...) # -# - foreach generator, it then -# - sets CPACK_GENERATOR to the one currently being iterated -# - includes the CPACK_PROJECT_CONFIG_FILE -# - produces the package for that generator +# - foreach generator, it then +# - sets CPACK_GENERATOR to the one currently being iterated +# - includes the CPACK_PROJECT_CONFIG_FILE +# - produces the package for that generator # # This is the key: For each generator listed in CPACK_GENERATOR # in CPackConfig.cmake, cpack will *reset* CPACK_GENERATOR @@ -48,95 +50,142 @@ # Before including this CPack module in your CMakeLists.txt file, # there are a variety of variables that can be set to customize # the resulting installers. The most commonly-used variables are: +##end # +##variable # CPACK_PACKAGE_NAME - The name of the package (or application). If # not specified, defaults to the project name. +##end # -# CPACK_PACKAGE_VENDOR - The name of the package vendor (e.g., +##variable +# CPACK_PACKAGE_VENDOR - The name of the package vendor. (e.g., # "Kitware"). +##end # +##variable # CPACK_PACKAGE_VERSION_MAJOR - Package major Version +##end # +##variable # CPACK_PACKAGE_VERSION_MINOR - Package minor Version +##end # +##variable # CPACK_PACKAGE_VERSION_PATCH - Package patch Version +##end # +##variable # CPACK_PACKAGE_DESCRIPTION_FILE - A text file used to describe the # project. Used, for example, the introduction screen of a # CPack-generated Windows installer to describe the project. +##end # +##variable # CPACK_PACKAGE_DESCRIPTION_SUMMARY - Short description of the # project (only a few words). +##end # +##variable # CPACK_PACKAGE_FILE_NAME - The name of the package file to generate, # not including the extension. For example, cmake-2.6.1-Linux-i686. +##end # +##variable # CPACK_PACKAGE_INSTALL_DIRECTORY - Installation directory on the # target system, e.g., "CMake 2.5". +##end # +##variable # CPACK_PROJECT_CONFIG_FILE - File included at cpack time, once per # generator after setting CPACK_GENERATOR to the actual generator # being used. Allows per-generator setting of CPACK_* variables at # cpack time. +##end # +##variable # CPACK_RESOURCE_FILE_LICENSE - License file for the project, which # will typically be displayed to the user (often with an explicit # "Accept" button, for graphical installers) prior to installation. +##end # +##variable # CPACK_RESOURCE_FILE_README - ReadMe file for the project, which # typically describes in some detail +##end # +##variable # CPACK_RESOURCE_FILE_WELCOME - Welcome file for the project, which # welcomes users to this installer. Typically used in the graphical # installers on Windows and Mac OS X. +##end # +##variable # CPACK_MONOLITHIC_INSTALL - Disables the component-based # installation mechanism, so that all components are always installed. +##end # +##variable # CPACK_GENERATOR - List of CPack generators to use. If not # specified, CPack will create a set of options (e.g., # CPACK_BINARY_NSIS) allowing the user to enable/disable individual # generators. +##end # +##variable # CPACK_OUTPUT_CONFIG_FILE - The name of the CPack configuration file # for binary installers that will be generated by the CPack # module. Defaults to CPackConfig.cmake. +##end # +##variable # CPACK_PACKAGE_EXECUTABLES - Lists each of the executables along # with a text label, to be used to create Start Menu shortcuts on # Windows. For example, setting this to the list ccmake;CMake will # create a shortcut named "CMake" that will execute the installed # executable ccmake. +##end # +##variable # CPACK_STRIP_FILES - List of files to be stripped. Starting with # CMake 2.6.0 CPACK_STRIP_FILES will be a boolean variable which # enables stripping of all files (a list of files evaluates to TRUE # in CMake, so this change is compatible). +##end # # The following CPack variables are specific to source packages, and # will not affect binary packages: # +##variable # CPACK_SOURCE_PACKAGE_FILE_NAME - The name of the source package, # e.g., cmake-2.6.1 +##end # +##variable # CPACK_SOURCE_STRIP_FILES - List of files in the source tree that # will be stripped. Starting with CMake 2.6.0 # CPACK_SOURCE_STRIP_FILES will be a boolean variable which enables # stripping of all files (a list of files evaluates to TRUE in CMake, # so this change is compatible). +##end # +##variable # CPACK_SOURCE_GENERATOR - List of generators used for the source # packages. As with CPACK_GENERATOR, if this is not specified then # CPack will create a set of options (e.g., CPACK_SOURCE_ZIP) # allowing users to select which packages will be generated. +##end # +##variable # CPACK_SOURCE_OUTPUT_CONFIG_FILE - The name of the CPack # configuration file for source installers that will be generated by # the CPack module. Defaults to CPackSourceConfig.cmake. +##end # +##variable # CPACK_SOURCE_IGNORE_FILES - Pattern of files in the source tree # that won't be packaged when building a source package. This is a # list of patterns, e.g., /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.* +##end # # The following variables are specific to the DragNDrop installers # built on Mac OS X: @@ -195,27 +244,41 @@ # # The following variables are for advanced uses of CPack: # +##variable # CPACK_CMAKE_GENERATOR - What CMake generator should be used if the # project is CMake project. Defaults to the value of CMAKE_GENERATOR; # few users will want to change this setting. +##end # +##variable # CPACK_INSTALL_CMAKE_PROJECTS - List of four values that specify # what project to install. The four values are: Build directory, # Project Name, Project Component, Directory. If omitted, CPack will # build an installer that installers everything. +##end # +##variable # CPACK_SYSTEM_NAME - System name, defaults to the value of # ${CMAKE_SYSTEM_NAME}. +##end # +##variable # CPACK_PACKAGE_VERSION - Package full version, used internally. By # default, this is built from CPACK_PACKAGE_VERSION_MAJOR, # CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH. +##end # +##variable # CPACK_TOPLEVEL_TAG - Directory for the installed files. +##end # +##variable # CPACK_INSTALL_COMMANDS - Extra commands to install components. +##end # +##variable # CPACK_INSTALLED_DIRECTORIES - Extra directories to install. +##end # #============================================================================= @@ -259,7 +322,7 @@ MACRO(cpack_set_if_not_set name value) ENDIF(NOT DEFINED "${name}") ENDMACRO(cpack_set_if_not_set) -# Macro to encode variables for the configuration file +# cpack_encode_variables - Macro to encode variables for the configuration file # find any variable that starts with CPACK and create a variable # _CPACK_OTHER_VARIABLES_ that contains SET commands for # each cpack variable. _CPACK_OTHER_VARIABLES_ is then diff --git a/Modules/CPackComponent.cmake b/Modules/CPackComponent.cmake index 1c10372..016cb8c 100644 --- a/Modules/CPackComponent.cmake +++ b/Modules/CPackComponent.cmake @@ -1,3 +1,6 @@ +##section Variables common to all CPack generators +##end +##module # - Build binary and source package installers # # The CPackComponent module is the module which handles @@ -20,7 +23,9 @@ # components are identified by the COMPONENT argument of CMake's # INSTALL commands, and should be further described by the following # CPack commands: +##end # +##macro # cpack_add_component - Describes a CPack installation component # named by the COMPONENT argument to a CMake INSTALL command. # @@ -90,7 +95,9 @@ # create a file with some name based on CPACK_PACKAGE_FILE_NAME and # the name of the component. See cpack_configure_downloads for more # information. +##end # +##macro # cpack_add_component_group - Describes a group of related CPack # installation components. # @@ -134,7 +141,9 @@ # # BOLD_TITLE indicates that the group title should appear in bold, # to call the user's attention to the group. +##end # +##macro # cpack_add_install_type - Add a new installation type containing a # set of predefined component selections to the graphical installer. # @@ -153,7 +162,9 @@ # DISPLAY_NAME is the displayed name of the install type, which will # typically show up in a drop-down box within a graphical # installer. This value can be any string. +##end # +##macro # cpack_configure_downloads - Configure CPack to download selected # components on-the-fly as part of the installation process. # @@ -203,6 +214,7 @@ # that can be called from Windows' Add/Remove Programs dialog (via the # "Modify" button) to change the set of installed components. NO_ADD_REMOVE # turns off this behavior. This option is ignored on Mac OS X. +##endmacro #============================================================================= # Copyright 2006-2009 Kitware, Inc. diff --git a/Modules/CPackDeb.cmake b/Modules/CPackDeb.cmake index 26433bb..0916843 100644 --- a/Modules/CPackDeb.cmake +++ b/Modules/CPackDeb.cmake @@ -1,3 +1,6 @@ +##section Variables specific to a CPack generator +##end +##module # - The builtin (binary) CPack Deb generator (Unix only) # CPackDeb may be used to create Deb package using CPack. # CPackDeb is a CPack generator thus it uses the CPACK_XXX variables @@ -11,43 +14,63 @@ # the wiki: # http://www.cmake.org/Wiki/CMake:CPackPackageGenerators#DEB_.28UNIX_only.29 # However as a handy reminder here comes the list of specific variables: +##end # +##variable # CPACK_DEBIAN_PACKAGE_NAME # Mandatory : YES # Default : CPACK_PACKAGE_NAME (lower case) # The debian package summary +##end +##variable # CPACK_DEBIAN_PACKAGE_VERSION # Mandatory : YES # Default : CPACK_PACKAGE_VERSION # The debian package version +##end +##variable # CPACK_DEBIAN_PACKAGE_ARCHITECTURE # Mandatory : YES # Default : Output of dpkg --print-architecture (or i386 if dpkg is not found) # The debian package architecture +##end +##variable # CPACK_DEBIAN_PACKAGE_DEPENDS # Mandatory : NO # Default : - # May be used to set deb dependencies. +##end +##variable # CPACK_DEBIAN_PACKAGE_MAINTAINER # Mandatory : YES # Default : CPACK_PACKAGE_CONTACT # The debian package maintainer +##end +##variable # CPACK_DEBIAN_PACKAGE_DESCRIPTION # Mandatory : YES # Default : CPACK_PACKAGE_DESCRIPTION_SUMMARY # The debian package description +##end +##variable # CPACK_DEBIAN_PACKAGE_SECTION # Mandatory : YES # Default : 'devel' # The debian package section +##end +##variable # CPACK_DEBIAN_PACKAGE_PRIORITY # Mandatory : YES # Default : 'optional' # The debian package priority +##end +##variable # CPACK_DEBIAN_PACKAGE_HOMEPAGE # Mandatory : NO # Default : - # The URL of the web site for this package +##end +##variable # CPACK_DEBIAN_PACKAGE_SHLIBDEPS # Mandatory : NO # Default : OFF @@ -57,11 +80,15 @@ # if you use this feature, because if you don't dpkg-shlibdeps # may fail to find your own shared libs. # See http://www.cmake.org/Wiki/CMake_RPATH_handling. +##end +##variable # CPACK_DEBIAN_PACKAGE_DEBUG # Mandatory : NO # Default : - # May be set when invoking cpack in order to trace debug information # during CPackDeb run. +##end +##variable # CPACK_DEBIAN_PACKAGE_PREDEPENDS # Mandatory : NO # Default : - @@ -69,12 +96,16 @@ # This field is like Depends, except that it also forces dpkg to complete installation of # the packages named before even starting the installation of the package which declares # the pre-dependency. +##end +##variable # CPACK_DEBIAN_PACKAGE_ENHANCES # Mandatory : NO # Default : - # see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps # This field is similar to Suggests but works in the opposite direction. # It is used to declare that a package can enhance the functionality of another package. +##end +##variable # CPACK_DEBIAN_PACKAGE_BREAKS # Mandatory : NO # Default : - @@ -82,23 +113,30 @@ # When one binary package declares that it breaks another, dpkg will refuse to allow the # package which declares Breaks be installed unless the broken package is deconfigured first, # and it will refuse to allow the broken package to be reconfigured. +##end +##variable # CPACK_DEBIAN_PACKAGE_CONFLICTS # Mandatory : NO # Default : - # see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps # When one binary package declares a conflict with another using a Conflicts field, # dpkg will refuse to allow them to be installed on the system at the same time. +##end +##variable # CPACK_DEBIAN_PACKAGE_PROVIDES # Mandatory : NO # Default : - # see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps # A virtual package is one which appears in the Provides control field of another package. +##end +##variable # CPACK_DEBIAN_PACKAGE_REPLACES # Mandatory : NO # Default : - # see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps # Packages can declare in their control file that they should overwrite # files in certain other packages, or completely replace other packages. +##end #============================================================================= # Copyright 2007-2009 Kitware, Inc. diff --git a/Modules/CPackRPM.cmake b/Modules/CPackRPM.cmake index e1e76ed..f76e91e 100644 --- a/Modules/CPackRPM.cmake +++ b/Modules/CPackRPM.cmake @@ -1,3 +1,6 @@ +##section Variables specific to a CPack generator +##end +##module # - The builtin (binary) CPack RPM generator (Unix only) # CPackRPM may be used to create RPM package using CPack. # CPackRPM is a CPack generator thus it uses the CPACK_XXX variables @@ -15,52 +18,67 @@ # You'll find a detailed usage of CPackRPM on the wiki: # http://www.cmake.org/Wiki/CMake:CPackPackageGenerators#RPM_.28Unix_Only.29 # However as a handy reminder here comes the list of specific variables: +##end # -# CPACK_RPM_PACKAGE_SUMMARY +##variable +# CPACK_RPM_PACKAGE_SUMMARY - The RPM package summary. # Mandatory : YES # Default : CPACK_PACKAGE_DESCRIPTION_SUMMARY -# The RPM package summary -# CPACK_RPM_PACKAGE_NAME +##end +##variable +# CPACK_RPM_PACKAGE_NAME - The RPM package name. # Mandatory : YES # Default : CPACK_PACKAGE_NAME -# The RPM package name -# CPACK_RPM_PACKAGE_VERSION +##end +##variable +# CPACK_RPM_PACKAGE_VERSION - The RPM package version. # Mandatory : YES # Default : CPACK_PACKAGE_VERSION -# The RPM package version -# CPACK_RPM_PACKAGE_ARCHITECTURE +##end +##variable +# CPACK_RPM_PACKAGE_ARCHITECTURE - The RPM package architecture. # Mandatory : NO # Default : - -# The RPM package architecture. This may be set to "noarch" if you +# This may be set to "noarch" if you # know you are building a noarch package. -# CPACK_RPM_PACKAGE_RELEASE +##end +##variable +# CPACK_RPM_PACKAGE_RELEASE - The RPM package release. # Mandatory : YES # Default : 1 -# The RPM package release. This is the numbering of the RPM package +# This is the numbering of the RPM package # itself, i.e. the version of the packaging and not the version of the # content (see CPACK_RPM_PACKAGE_VERSION). One may change the default # value if the previous packaging was buggy and/or you want to put here # a fancy Linux distro specific numbering. -# CPACK_RPM_PACKAGE_LICENSE +##end +##variable +# CPACK_RPM_PACKAGE_LICENSE - The RPM package license policy. # Mandatory : YES # Default : "unknown" -# The RPM package license policy. -# CPACK_RPM_PACKAGE_GROUP +##end +##variable +# CPACK_RPM_PACKAGE_GROUP - The RPM package group. # Mandatory : YES # Default : "unknown" -# The RPM package group. -# CPACK_RPM_PACKAGE_VENDOR +##end +##variable +# CPACK_RPM_PACKAGE_VENDOR - The RPM package vendor. # Mandatory : YES # Default : CPACK_PACKAGE_VENDOR if set or "unknown" -# The RPM package vendor. -# CPACK_RPM_PACKAGE_URL +##end +##variable +# CPACK_RPM_PACKAGE_URL - The projects URL. # Mandatory : NO # Default : - -# The projects URL. -# CPACK_RPM_PACKAGE_DESCRIPTION +##end +##variable +# CPACK_RPM_PACKAGE_DESCRIPTION - RPM package description. # Mandatory : YES # Default : CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" -# CPACK_RPM_COMPRESSION_TYPE +##end +##variable +# CPACK_RPM_COMPRESSION_TYPE - RPM compression type. # Mandatory : NO # Default : - # May be used to override RPM compression type to be used @@ -68,7 +86,9 @@ # to lzma or xz compression whereas older cannot use such RPM. # Using this one can enforce compression type to be used. # Possible value are: lzma, xz, bzip2 and gzip. -# CPACK_RPM_PACKAGE_REQUIRES +##end +##variable +# CPACK_RPM_PACKAGE_REQUIRES - RPM spec requires field. # Mandatory : NO # Default : - # May be used to set RPM dependencies (requires). @@ -77,22 +97,30 @@ # set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8") # The required package list of an RPM file could be printed with # rpm -qp --requires file.rpm -# CPACK_RPM_PACKAGE_SUGGESTS +##end +##variable +# CPACK_RPM_PACKAGE_SUGGESTS - RPM spec suggest field. # Mandatory : NO # Default : - # May be used to set weak RPM dependencies (suggests). # Note that you must enclose the complete requires string between quotes. -# CPACK_RPM_PACKAGE_PROVIDES +##end +##variable +# CPACK_RPM_PACKAGE_PROVIDES - RPM spec provides field. # Mandatory : NO # Default : - # May be used to set RPM dependencies (provides). # The provided package list of an RPM file could be printed with # rpm -qp --provides file.rpm -# CPACK_RPM_PACKAGE_OBSOLETES +##end +##variable +# CPACK_RPM_PACKAGE_OBSOLETES - RPM spec obsoletes field. # Mandatory : NO # Default : - # May be used to set RPM packages that are obsoleted by this one. -# CPACK_RPM_PACKAGE_RELOCATABLE +##end +##variable +# CPACK_RPM_PACKAGE_RELOCATABLE - build a relocatable RPM. # Mandatory : NO # Default : CPACK_PACKAGE_RELOCATABLE # If this variable is set to TRUE or ON CPackRPM will try @@ -103,7 +131,9 @@ # If CPACK_SET_DESTDIR is set then you will get a warning message # but if there is file installed with absolute path you'll get # unexpected behavior. -# CPACK_RPM_SPEC_INSTALL_POST [deprecated] +##end +##variable +# CPACK_RPM_SPEC_INSTALL_POST - [deprecated]. # Mandatory : NO # Default : - # This way of specifying post-install script is deprecated use @@ -111,23 +141,31 @@ # May be used to set an RPM post-install command inside the spec file. # For example setting it to "/bin/true" may be used to prevent # rpmbuild to strip binaries. -# CPACK_RPM_SPEC_MORE_DEFINE +##end +##variable +# CPACK_RPM_SPEC_MORE_DEFINE - RPM extended spec definitions lines. # Mandatory : NO # Default : - # May be used to add any %define lines to the generated spec file. -# CPACK_RPM_PACKAGE_DEBUG +##end +##variable +# CPACK_RPM_PACKAGE_DEBUG - Toggle CPackRPM debug output. # Mandatory : NO # Default : - # May be set when invoking cpack in order to trace debug information # during CPack RPM run. For example you may launch CPack like this # cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM -# CPACK_RPM_USER_BINARY_SPECFILE +##end +##variable +# CPACK_RPM_USER_BINARY_SPECFILE - A user provided spec file. # Mandatory : NO # Default : - # May be set by the user in order to specify a USER binary spec file # to be used by CPackRPM instead of generating the file. # The specified file will be processed by CONFIGURE_FILE( @ONLY). -# CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE +##end +##variable +# CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE - Spec file template. # Mandatory : NO # Default : - # If set CPack will generate a template for USER specified binary @@ -135,6 +173,8 @@ # cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM # The user may then use this file in order to hand-craft is own # binary spec file which may be used with CPACK_RPM_USER_BINARY_SPECFILE. +##end +##variable # CPACK_RPM_PRE_INSTALL_SCRIPT_FILE # CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE # Mandatory : NO @@ -148,6 +188,8 @@ # CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE # One may verify which scriptlet has been included with # rpm -qp --scripts package.rpm +##end +##variable # CPACK_RPM_POST_INSTALL_SCRIPT_FILE # CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE # Mandatory : NO @@ -161,6 +203,8 @@ # CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE # One may verify which scriptlet has been included with # rpm -qp --scripts package.rpm +##end +##variable # CPACK_RPM_USER_FILELIST # CPACK_RPM_<COMPONENT>_USER_FILELIST # Mandatory : NO @@ -170,12 +214,15 @@ # that be found in the %files section. Since CPackRPM is generating # the list of files (and directories) the user specified files of # the CPACK_RPM_<COMPONENT>_USER_FILELIST list will be removed from the generated list. -# CPACK_RPM_CHANGELOG_FILE +##end +##variable +# CPACK_RPM_CHANGELOG_FILE - RPM changelog file. # Mandatory : NO # Default : - # May be used to embed a changelog in the spec file. # The refered file will be read and directly put after the %changelog # section. +##end #============================================================================= # Copyright 2007-2009 Kitware, Inc. diff --git a/Source/CMakeLists.txt b/Source/CMakeLists.txt index b5115b7..0c420b9 100644 --- a/Source/CMakeLists.txt +++ b/Source/CMakeLists.txt @@ -449,6 +449,8 @@ SET(CPACK_SRCS CPack/cmCPackTarBZip2Generator.cxx CPack/cmCPackTarCompressGenerator.cxx CPack/cmCPackZIPGenerator.cxx + CPack/cmCPackDocumentVariables.cxx + CPack/cmCPackDocumentMacros.cxx ) IF(CYGWIN) diff --git a/Source/CPack/cmCPackDocumentMacros.cxx b/Source/CPack/cmCPackDocumentMacros.cxx new file mode 100644 index 0000000..ddc75a4 --- /dev/null +++ b/Source/CPack/cmCPackDocumentMacros.cxx @@ -0,0 +1,16 @@ +#include "cmCPackDocumentMacros.h" + +void cmCPackDocumentMacros::GetMacrosDocumentation( + std::vector<cmDocumentationEntry>& ) +{ + // Commented-out example of use + // + // cmDocumentationEntry e("cpack_<macro>", + // "Brief Description" + // "which may be on several lines.", + // "Long description in pre-formatted format" + // " blah\n" + // " blah\n" + //); + //v.push_back(e); +} diff --git a/Source/CPack/cmCPackDocumentMacros.h b/Source/CPack/cmCPackDocumentMacros.h new file mode 100644 index 0000000..544f74f --- /dev/null +++ b/Source/CPack/cmCPackDocumentMacros.h @@ -0,0 +1,21 @@ +/*============================================================================ + CMake - Cross Platform Makefile Generator + Copyright 2000-2009 Kitware, Inc., Insight Software Consortium + + Distributed under the OSI-approved BSD License (the "License"); + see accompanying file Copyright.txt for details. + + This software is distributed WITHOUT ANY WARRANTY; without even the + implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the License for more information. +============================================================================*/ +#ifndef cmCPackDocumentMacros_h +#define cmCPackDocumentMacros_h +#include "cmStandardIncludes.h" +class cmCPackDocumentMacros +{ +public: + static void GetMacrosDocumentation(std::vector<cmDocumentationEntry>& v); +}; + +#endif diff --git a/Source/CPack/cmCPackDocumentVariables.cxx b/Source/CPack/cmCPackDocumentVariables.cxx new file mode 100644 index 0000000..68cde78 --- /dev/null +++ b/Source/CPack/cmCPackDocumentVariables.cxx @@ -0,0 +1,32 @@ +#include "cmCPackDocumentVariables.h" +#include "cmake.h" + +void cmCPackDocumentVariables::DefineVariables(cmake* cm) +{ + // Subsection: variables defined/used by cpack, + // which are common to all CPack generators + + cm->DefineProperty + ("CPACK_PACKAGING_INSTALL_PREFIX", cmProperty::VARIABLE, + "The prefix used in the built package.", + "Each CPack generator has a default value (like /usr)." + " This default value may" + " be overwritten from the CMakeLists.txt or the cpack command line" + " by setting an alternative value.\n" + "e.g. " + " set(CPACK_PACKAGING_INSTALL_PREFIX \"/opt\")\n" + "This is not the same purpose as CMAKE_INSTALL_PREFIX which" + " is used when installing from the build tree without building" + " a package." + "", false, + "Variables common to all CPack generators"); + + // Subsection: variables defined/used by cpack, + // which are specific to one CPack generator +// cm->DefineProperty +// ("CPACK_RPM_PACKAGE_NAME", cmProperty::VARIABLE, +// "RPM specific package name.", +// "If not specified, defaults to CPACK_PACKAGE_NAME." +// "", false, +// "Variables specific to a CPack generator"); +} diff --git a/Source/CPack/cmCPackDocumentVariables.h b/Source/CPack/cmCPackDocumentVariables.h new file mode 100644 index 0000000..e7971be --- /dev/null +++ b/Source/CPack/cmCPackDocumentVariables.h @@ -0,0 +1,21 @@ +/*============================================================================ + CMake - Cross Platform Makefile Generator + Copyright 2000-2009 Kitware, Inc., Insight Software Consortium + + Distributed under the OSI-approved BSD License (the "License"); + see accompanying file Copyright.txt for details. + + This software is distributed WITHOUT ANY WARRANTY; without even the + implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the License for more information. +============================================================================*/ +#ifndef cmCPackDocumentVariables_h +#define cmCPackDocumentVariables_h +class cmake; +class cmCPackDocumentVariables +{ +public: + static void DefineVariables(cmake* cm); +}; + +#endif diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx index 163f744..c541610 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -14,6 +14,8 @@ // Need these for documentation support. #include "cmake.h" #include "cmDocumentation.h" +#include "cmCPackDocumentVariables.h" +#include "cmCPackDocumentMacros.h" #include "cmCPackGeneratorFactory.h" #include "cmCPackGenerator.h" #include "cmake.h" @@ -24,6 +26,7 @@ #include "cmCPackLog.h" #include <cmsys/CommandLineArguments.hxx> +#include <cmsys/SystemTools.hxx> #include <memory> // auto_ptr //---------------------------------------------------------------------------- @@ -90,6 +93,40 @@ static const char * cmDocumentationOptions[][3] = "If vendor is not specified on cpack command line " "(or inside CMakeLists.txt) then" "CPack.cmake defines it with a default value"}, + {"--help-command cmd [file]", "Print help for a single command and exit.", + "Full documentation specific to the given command is displayed. " + "If a file is specified, the documentation is written into and the output " + "format is determined depending on the filename suffix. Supported are man " + "page, HTML, DocBook and plain text."}, + {"--help-command-list [file]", "List available commands and exit.", + "The list contains all commands for which help may be obtained by using " + "the --help-command argument followed by a command name. " + "If a file is specified, the documentation is written into and the output " + "format is determined depending on the filename suffix. Supported are man " + "page, HTML, DocBook and plain text."}, + {"--help-commands [file]", "Print help for all commands and exit.", + "Full documentation specific for all current command is displayed." + "If a file is specified, the documentation is written into and the output " + "format is determined depending on the filename suffix. Supported are man " + "page, HTML, DocBook and plain text."}, + {"--help-variable var [file]", + "Print help for a single variable and exit.", + "Full documentation specific to the given variable is displayed." + "If a file is specified, the documentation is written into and the output " + "format is determined depending on the filename suffix. Supported are man " + "page, HTML, DocBook and plain text."}, + {"--help-variable-list [file]", "List documented variables and exit.", + "The list contains all variables for which help may be obtained by using " + "the --help-variable argument followed by a variable name. If a file is " + "specified, the help is written into it." + "If a file is specified, the documentation is written into and the output " + "format is determined depending on the filename suffix. Supported are man " + "page, HTML, DocBook and plain text."}, + {"--help-variables [file]", "Print help for all variables and exit.", + "Full documentation for all variables is displayed." + "If a file is specified, the documentation is written into and the output " + "format is determined depending on the filename suffix. Supported are man " + "page, HTML, DocBook and plain text."}, {0,0,0} }; @@ -137,12 +174,15 @@ int cpackDefinitionArgument(const char* argument, const char* cValue, return 1; } + //---------------------------------------------------------------------------- // this is CPack. int main (int argc, char *argv[]) { cmSystemTools::FindExecutableDirectory(argv[0]); cmCPackLog log; + int nocwd = 0; + log.SetErrorPrefix("CPack Error: "); log.SetWarningPrefix("CPack Warning: "); log.SetOutputPrefix("CPack: "); @@ -154,6 +194,7 @@ int main (int argc, char *argv[]) { cmCPack_Log(&log, cmCPackLog::LOG_ERROR, "Current working directory cannot be established." << std::endl); + nocwd = 1; } std::string generator; @@ -179,7 +220,6 @@ int main (int argc, char *argv[]) cpackConfigFile = ""; - cmDocumentation doc; cmsys::CommandLineArguments arg; arg.Initialize(argc, argv); typedef cmsys::CommandLineArguments argT; @@ -252,17 +292,25 @@ int main (int argc, char *argv[]) generators.SetLogger(&log); cmCPackGenerator* cpackGenerator = 0; - if ( !helpFull.empty() || !helpMAN.empty() || - !helpHTML.empty() || helpVersion ) + cmDocumentation doc; + doc.addCPackStandardDocSections(); + /* Were we invoked to display doc or to do some work ? */ + if(doc.CheckOptions(argc, argv,"-G") || nocwd) { - help = true; + help = true; } + else + { + help = false; + } + + // This part is used for cpack documentation lookup as well. + cminst.AddCMakePaths(); if ( parsed && !help ) { // find out which system cpack is running on, so it can setup the search // paths, so FIND_XXX() commands can be used in scripts - cminst.AddCMakePaths(); std::string systemFile = globalMF->GetModulesFile("CMakeDetermineSystem.cmake"); if (!globalMF->ReadListFile(0, systemFile.c_str())) @@ -465,14 +513,49 @@ int main (int argc, char *argv[]) */ if ( help ) { - doc.CheckOptions(argc, argv); // Construct and print requested documentation. + std::vector<cmDocumentationEntry> variables; + doc.SetName("cpack"); doc.SetSection("Name",cmDocumentationName); doc.SetSection("Usage",cmDocumentationUsage); doc.SetSection("Description",cmDocumentationDescription); doc.PrependSection("Options",cmDocumentationOptions); + // statically (in C++ code) defined variables + cmCPackDocumentVariables::DefineVariables(&cminst); + + std::vector<cmDocumentationEntry> commands; + + std::string docedFile; + std::string docPath; + cmDocumentation::documentedModulesList_t docedModList; + + docedFile = globalMF->GetModulesFile("CPack.cmake"); + if (docedFile.length()!=0) + { + docPath = cmSystemTools::GetFilenamePath(docedFile.c_str()); + doc.getDocumentedModulesListInDir(docPath,"CPack*.cmake",docedModList); + } + + // parse the files for documentation. + cmDocumentation::documentedModulesList_t::iterator docedIt; + for (docedIt = docedModList.begin(); + docedIt!= docedModList.end(); ++docedIt) + { + doc.GetStructuredDocFromFile( + (docedIt->first).c_str(), + commands,&cminst,(docedIt->second).c_str()); + } + + std::map<std::string,cmDocumentationSection *> propDocs; + cminst.GetPropertiesDocumentation(propDocs); + doc.SetSections(propDocs); + cminst.GetCommandDocumentation(commands,true,false); + // statically (in C++ code) defined macros/commands + cmCPackDocumentMacros::GetMacrosDocumentation(commands); + doc.SetSection("Commands",commands); + std::vector<cmDocumentationEntry> v; cmCPackGeneratorFactory::DescriptionsMap::const_iterator generatorIt; for( generatorIt = generators.GetGeneratorsList().begin(); diff --git a/Source/CursesDialog/ccmake.cxx b/Source/CursesDialog/ccmake.cxx index b1a72af..623d7d3 100644 --- a/Source/CursesDialog/ccmake.cxx +++ b/Source/CursesDialog/ccmake.cxx @@ -102,6 +102,7 @@ int main(int argc, char** argv) { cmSystemTools::FindExecutableDirectory(argv[0]); cmDocumentation doc; + doc.addCMakeStandardDocSections(); if(doc.CheckOptions(argc, argv)) { cmake hcm; diff --git a/Source/QtDialog/CMakeSetup.cxx b/Source/QtDialog/CMakeSetup.cxx index 7ba7f51..b4f3d72 100644 --- a/Source/QtDialog/CMakeSetup.cxx +++ b/Source/QtDialog/CMakeSetup.cxx @@ -64,6 +64,7 @@ int main(int argc, char** argv) // check docs first so that X is not need to get docs // do docs, if args were given cmDocumentation doc; + doc.addCMakeStandardDocSections(); if(argc >1 && doc.CheckOptions(argc, argv)) { // Construct and print requested documentation. diff --git a/Source/cmCommand.h b/Source/cmCommand.h index 7817eb3..e046096 100644 --- a/Source/cmCommand.h +++ b/Source/cmCommand.h @@ -111,6 +111,17 @@ public: } /** + * This is used to avoid including this command + * in documentation. This is mainly used by + * cmMacroHelperCommand and cmFunctionHelperCommand + * which cannot provide appropriate documentation. + */ + virtual bool ShouldAppearInDocumentation() + { + return true; + } + + /** * The name of the command as specified in CMakeList.txt. */ virtual const char* GetName() = 0; diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 07683d0..02f69f1 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -14,6 +14,7 @@ #include "cmSystemTools.h" #include "cmVersion.h" #include <cmsys/Directory.hxx> +#include <cmsys/Glob.hxx> //---------------------------------------------------------------------------- @@ -220,55 +221,7 @@ cmDocumentation::cmDocumentation() :CurrentFormatter(0) { this->SetForm(TextForm); - - cmDocumentationSection *sec; - - sec = new cmDocumentationSection("Author","AUTHOR"); - sec->Append(cmDocumentationEntry - (0, - "This manual page was generated by the \"--help-man\" option.", - 0)); - this->AllSections["Author"] = sec; - - sec = new cmDocumentationSection("Copyright","COPYRIGHT"); - sec->Append(cmDocumentationCopyright); - this->AllSections["Copyright"] = sec; - - sec = new cmDocumentationSection("See Also","SEE ALSO"); - sec->Append(cmDocumentationStandardSeeAlso); - this->AllSections["Standard See Also"] = sec; - - sec = new cmDocumentationSection("Options","OPTIONS"); - sec->Append(cmDocumentationStandardOptions); - this->AllSections["Options"] = sec; - - sec = new cmDocumentationSection("Properties","PROPERTIES"); - sec->Append(cmPropertiesDocumentationDescription); - this->AllSections["Properties Description"] = sec; - - sec = new cmDocumentationSection("Generators","GENERATORS"); - sec->Append(cmDocumentationGeneratorsHeader); - this->AllSections["Generators"] = sec; - - sec = new cmDocumentationSection("Compatibility Commands", - "COMPATIBILITY COMMANDS"); - sec->Append(cmCompatCommandsDocumentationDescription); - this->AllSections["Compatibility Commands"] = sec; - - - this->PropertySections.push_back("Properties of Global Scope"); - this->PropertySections.push_back("Properties on Directories"); - this->PropertySections.push_back("Properties on Targets"); - this->PropertySections.push_back("Properties on Tests"); - this->PropertySections.push_back("Properties on Source Files"); - this->PropertySections.push_back("Properties on Cache Entries"); - - this->VariableSections.push_back("Variables that Provide Information"); - this->VariableSections.push_back("Variables That Change Behavior"); - this->VariableSections.push_back("Variables That Describe the System"); - this->VariableSections.push_back("Variables that Control the Build"); - this->VariableSections.push_back("Variables for Languages"); - + this->addCommonStandardDocSections(); this->ShowGenerators = true; } @@ -559,6 +512,8 @@ bool cmDocumentation::CreateSingleModule(const char* fname, { if(line.size() && line[0] == '#') { + /* line beginnings with ## are mark-up ignore them */ + if (line.size()>=2 && line[1] == '#') continue; // blank line if(line.size() <= 2) { @@ -710,6 +665,410 @@ cmDocumentation::Form cmDocumentation::GetFormFromFilename( } //---------------------------------------------------------------------------- +void cmDocumentation::addCommonStandardDocSections() +{ + cmDocumentationSection *sec; + + sec = new cmDocumentationSection("Author","AUTHOR"); + sec->Append(cmDocumentationEntry + (0, + "This manual page was generated by the \"--help-man\" option.", + 0)); + this->AllSections["Author"] = sec; + + sec = new cmDocumentationSection("Copyright","COPYRIGHT"); + sec->Append(cmDocumentationCopyright); + this->AllSections["Copyright"] = sec; + + sec = new cmDocumentationSection("See Also","SEE ALSO"); + sec->Append(cmDocumentationStandardSeeAlso); + this->AllSections["Standard See Also"] = sec; + + sec = new cmDocumentationSection("Options","OPTIONS"); + sec->Append(cmDocumentationStandardOptions); + this->AllSections["Options"] = sec; + + sec = new cmDocumentationSection("Compatibility Commands", + "COMPATIBILITY COMMANDS"); + sec->Append(cmCompatCommandsDocumentationDescription); + this->AllSections["Compatibility Commands"] = sec; +} + +//---------------------------------------------------------------------------- +void cmDocumentation::addCMakeStandardDocSections() +{ + cmDocumentationSection *sec; + + sec = new cmDocumentationSection("Properties","PROPERTIES"); + sec->Append(cmPropertiesDocumentationDescription); + this->AllSections["Properties Description"] = sec; + + sec = new cmDocumentationSection("Generators","GENERATORS"); + sec->Append(cmDocumentationGeneratorsHeader); + this->AllSections["Generators"] = sec; + + this->PropertySections.push_back("Properties of Global Scope"); + this->PropertySections.push_back("Properties on Directories"); + this->PropertySections.push_back("Properties on Targets"); + this->PropertySections.push_back("Properties on Tests"); + this->PropertySections.push_back("Properties on Source Files"); + this->PropertySections.push_back("Properties on Cache Entries"); + + this->VariableSections.push_back("Variables that Provide Information"); + this->VariableSections.push_back("Variables That Change Behavior"); + this->VariableSections.push_back("Variables That Describe the System"); + this->VariableSections.push_back("Variables that Control the Build"); + this->VariableSections.push_back("Variables for Languages"); + +} + +//---------------------------------------------------------------------------- +void cmDocumentation::addCTestStandardDocSections() +{ + // This is currently done for backward compatibility reason + // We may suppress some of these. + addCMakeStandardDocSections(); +} + +//---------------------------------------------------------------------------- +void cmDocumentation::addCPackStandardDocSections() +{ + cmDocumentationSection *sec; + + sec = new cmDocumentationSection("Generators","GENERATORS"); + sec->Append(cmDocumentationGeneratorsHeader); + this->AllSections["Generators"] = sec; + + this->VariableSections.push_back( + "Variables common to all CPack generators"); + this->VariableSections.push_back( + "Variables specific to a CPack generator"); +} + +//---------------------------------------------------------------------------- +int cmDocumentation::getDocumentedModulesListInDir( + std::string path, + std::string globExpr, + documentedModulesList_t& docedModuleList) +{ + cmsys::Glob gl; + std::string findExpr; + std::vector<std::string> files; + std::string line; + documentedModuleSectionPair_t docPair; + int nbDocumentedModules = 0; + + findExpr = path + "/" + globExpr; + if (gl.FindFiles(findExpr)) + { + files = gl.GetFiles(); + for (std::vector<std::string>::iterator itf=files.begin(); + itf!=files.end();++itf) + { + std::ifstream fin((*itf).c_str()); + // file access trouble ignore it (ignore this kind of error) + if (!fin) continue; + /* read first line in order to get doc section */ + if (cmSystemTools::GetLineFromStream(fin, line)) + { + /* Doc section indicates that + * this file has structured doc in it. + */ + if (line.find("##section")!=std::string::npos) + { + // ok found one more documented module + ++nbDocumentedModules; + docPair.first = *itf; + // 10 is the size of '##section' + 1 + docPair.second = line.substr(10,std::string::npos); + docedModuleList.push_back(docPair); + } + // No else if no section is found (undocumented module) + } + // No else cannot read first line (ignore this kind of error) + line = ""; + } + } + if (nbDocumentedModules>0) + { + return 0; + } + else + { + return 1; + } +} + +//---------------------------------------------------------------------------- +static void trim(std::string& s) +{ + std::string::size_type pos = s.find_last_not_of(' '); + if(pos != std::string::npos) + { + s.erase(pos + 1); + pos = s.find_first_not_of(' '); + if(pos != std::string::npos) s.erase(0, pos); + } + else + { + s.erase(s.begin(), s.end()); + } +} + +int cmDocumentation::GetStructuredDocFromFile( + const char* fname, + std::vector<cmDocumentationEntry>& commands, + cmake* cm, + const char *docSection) +{ + typedef enum sdoce { + SDOC_NONE, SDOC_MODULE, SDOC_MACRO, SDOC_FUNCTION, SDOC_VARIABLE, + SDOC_SECTION, + SDOC_UNKNOWN} sdoc_t; + int nbDocItemFound = 0; + int docCtxIdx = 0; + std::vector<int> docContextStack(60); + docContextStack[docCtxIdx]=SDOC_NONE; + cmDocumentationEntry e; + std::ifstream fin(fname); + if(!fin) + { + return nbDocItemFound; + } + std::string name; + std::string full; + std::string brief; + std::string line; + bool newCtx = false; /* we've just entered ##<beginkey> context */ + bool inBrief = false; /* we are currently parsing brief desc. */ + bool inFullFirstParagraph = false; /* we are currently parsing full + desc. first paragraph */ + brief = ""; + full = ""; + bool newParagraph = true; + while ( fin && cmSystemTools::GetLineFromStream(fin, line) ) + { + if(line.size() && line[0] == '#') + { + /* handle structured doc context */ + if ((line.size()>=2) && line[1]=='#') + { + /* markup word is following '##' stopping at first space + * Some markup word like 'section' may have more characters + * following but we don't handle those here. + */ + std::string mkword = line.substr(2,line.find(' ',2)-2); + if (mkword=="macro") + { + docCtxIdx++; + docContextStack[docCtxIdx]=SDOC_MACRO; + newCtx = true; + } + else if (mkword=="variable") + { + docCtxIdx++; + docContextStack[docCtxIdx]=SDOC_VARIABLE; + newCtx = true; + } + else if (mkword=="function") + { + docCtxIdx++; + docContextStack[docCtxIdx]=SDOC_FUNCTION; + newCtx = true; + } + else if (mkword=="module") + { + docCtxIdx++; + docContextStack[docCtxIdx]=SDOC_MODULE; + newCtx = true; + } + else if (mkword=="section") + { + docCtxIdx++; + docContextStack[docCtxIdx]=SDOC_SECTION; + /* drop the rest of the line */ + line = ""; + newCtx = true; + } + else if (mkword.substr(0,3)=="end") + { + switch (docContextStack[docCtxIdx]) { + case SDOC_MACRO: + /* for now MACRO and FUNCTION are handled in the same way */ + case SDOC_FUNCTION: + commands.push_back(cmDocumentationEntry(name.c_str(), + brief.c_str(),full.c_str())); + break; + case SDOC_VARIABLE: + cm->DefineProperty + (name.c_str(), cmProperty::VARIABLE, + brief.c_str(), + full.c_str(),false, + docSection); + break; + case SDOC_MODULE: + /* not implemented */ + break; + case SDOC_SECTION: + /* not implemented */ + break; + default: + /* ignore other cases */ + break; + } + docCtxIdx--; + newCtx = false; + ++nbDocItemFound; + } + else + { + // error out unhandled context + return nbDocItemFound; + } + /* context is set go to next doc line */ + continue; + } + + // Now parse the text attached to the context + + // The first line after the context mark-up contains:: + // name - brief until. (brief is dot terminated or + // followed by a blank line) + if (newCtx) + { + // no brief (for easy variable definition) + if (line.find("-")==std::string::npos) + { + name = line.substr(1,std::string::npos); + trim(name); + brief = ""; + inBrief = false; + full = ""; + } + // here we have a name and brief beginning + else + { + name = line.substr(1,line.find("-")-1); + trim(name); + // we are parsing the brief context + brief = line.substr(line.find("-")+1,std::string::npos); + trim(brief); + // Brief may already be terminated on the first line + if (brief.find('.')!=std::string::npos) + { + inBrief = false; + full = brief.substr(brief.find('.')+1,std::string::npos); + trim(full); + inFullFirstParagraph = true; + brief = brief.substr(0,brief.find('.')); + } + // brief is continued on following lines + else + { + inBrief = true; + full = ""; + } + } + newCtx = false; + continue; + } + // blank line + if(line.size() <= 2) + { + if (inBrief) { + inBrief = false; + full = ""; + } else { + if (full.length()>0) + { + full += "\n"; + } + // the first paragraph of full has ended + inFullFirstParagraph = false; + } + newParagraph = true; + } + // brief is terminated by '.' + else if (inBrief && (line.find('.')!=std::string::npos)) + { + /* the brief just ended */ + inBrief = false; + std::string endBrief = line.substr(1,line.find('.')); + trim(endBrief); + trim(brief); + brief += " " + endBrief; + full += line.substr(line.find('.')+1,std::string::npos); + trim(full); + inFullFirstParagraph = true; + } + // we handle full text or multi-line brief. + else + { + std::string* text; + if (inBrief) + { + text = &brief; + } + else + { + text = &full; + } + // two spaces + if(line[1] == ' ' && line[2] == ' ') + { + // there is no "full first paragraph at all." + if (line[3] == ' ') + { + inFullFirstParagraph = false; + } + + if(!newParagraph && !inFullFirstParagraph) + { + *text += "\n"; + newParagraph = true; + } + // Skip #, and leave space for pre-formatted + if (inFullFirstParagraph) + { + std::string temp = line.c_str()+1; + trim(temp); + *text += " " + temp; + } + else + { + *text += line.c_str()+1; + *text += "\n"; + } + } + else if(line[1] == ' ') + { + if(!newParagraph) + { + *text += " "; + } + newParagraph = false; + // skip # and space + *text += line.c_str()+2; + } + else + { + if(!newParagraph) + { + *text += " "; + } + newParagraph = false; + // skip # + *text += line.c_str()+1; + } + } + } + /* next line is not the first context line */ + newCtx = false; + } + return nbDocItemFound; +} + +//---------------------------------------------------------------------------- bool cmDocumentation::CheckOptions(int argc, const char* const* argv, const char* exitOpt) { diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index 34b83b1..00dba1a 100644 --- a/Source/cmDocumentation.h +++ b/Source/cmDocumentation.h @@ -21,6 +21,7 @@ #include "cmDocumentationFormatterText.h" #include "cmDocumentationFormatterUsage.h" #include "cmDocumentationSection.h" +#include "cmake.h" namespace cmsys { @@ -34,6 +35,21 @@ public: cmDocumentation(); ~cmDocumentation(); + + /** + * An helper type pair for [structured] documented modules. + * The comment of those module contains structure markup + * which makes it possible to retrieve the documentation + * of variables, macros and functions defined in the module. + * - first is the filename of the module + * - second is the section of the doc the module belongs too + */ + typedef std::pair<std::string,std::string> documentedModuleSectionPair_t; + /** + * A list of documented module(s). + */ + typedef std::list<documentedModuleSectionPair_t> documentedModulesList_t; + // High-level interface for standard documents: /** @@ -119,6 +135,58 @@ public: static Form GetFormFromFilename(const std::string& filename); + /** Add common (to all tools) documentation section(s) */ + void addCommonStandardDocSections(); + + /** Add the CMake standard documentation section(s) */ + void addCMakeStandardDocSections(); + + /** Add the CTest standard documentation section(s) */ + void addCTestStandardDocSections(); + + /** Add the CPack standard documentation section(s) */ + void addCPackStandardDocSections(); + + /** + * Retrieve the list of documented module located in + * path which match the globing expression globExpr. + * @param[in] path, directory where to start the search + * we will recurse into it. + * @param[in] globExpr, the globing expression used to + * match the file in path. + * @param[out] the list of obtained pairs (may be empty) + * @return 0 on success 1 on error or empty list + */ + int getDocumentedModulesListInDir( + std::string path, + std::string globExpr, + documentedModulesList_t& docModuleList); + + /** + * Get the documentation of macros, functions and variable documented + * with CMake structured documentation in a CMake script. + * (in fact it may be in any file which follow the structured doc format) + * Structured documentation begin with + * ## (double sharp) in column 1 & 2 immediately followed + * by a markup. Those ## are ignored by the legacy module + * documentation parser @see CreateSingleModule. + * Current markup are ##section, ##module, + * ##macro, ##function, ##variable and ##end. + * ##end is closing either of the previous ones. + * @param[in] fname the script file name to be parsed for documentation + * @param[in,out] commands the vector of command/macros documentation + * entry found in the script file. + * @param[in,out] the cmake object instance to which variable documentation + * will be attached (using @see cmake::DefineProperty) + * @param[in] the documentation section in which the property will be + * inserted. + * @return the number of documented items (command and variable) + * found in the file. + */ + int GetStructuredDocFromFile(const char* fname, + std::vector<cmDocumentationEntry>& commands, + cmake* cm, + const char *docSection); private: void SetForm(Form f); void SetDocName(const char* docname); diff --git a/Source/cmFunctionCommand.cxx b/Source/cmFunctionCommand.cxx index ec4fd16..7a80a1c 100644 --- a/Source/cmFunctionCommand.cxx +++ b/Source/cmFunctionCommand.cxx @@ -23,6 +23,17 @@ public: ~cmFunctionHelperCommand() {}; /** + * This is used to avoid including this command + * in documentation. This is mainly used by + * cmMacroHelperCommand and cmFunctionHelperCommand + * which cannot provide appropriate documentation. + */ + virtual bool ShouldAppearInDocumentation() + { + return false; + } + + /** * This is a virtual constructor for the command. */ virtual cmCommand* Clone() diff --git a/Source/cmMacroCommand.cxx b/Source/cmMacroCommand.cxx index 774f32b..f81a63d 100644 --- a/Source/cmMacroCommand.cxx +++ b/Source/cmMacroCommand.cxx @@ -23,6 +23,17 @@ public: ~cmMacroHelperCommand() {}; /** + * This is used to avoid including this command + * in documentation. This is mainly used by + * cmMacroHelperCommand and cmFunctionHelperCommand + * which cannot provide appropriate documentation. + */ + virtual bool ShouldAppearInDocumentation() + { + return false; + } + + /** * This is a virtual constructor for the command. */ virtual cmCommand* Clone() diff --git a/Source/cmake.cxx b/Source/cmake.cxx index 71dca3a..cce5080 100644 --- a/Source/cmake.cxx +++ b/Source/cmake.cxx @@ -2660,7 +2660,9 @@ void cmake::GetCommandDocumentation(std::vector<cmDocumentationEntry>& v, j != this->Commands.end(); ++j) { if ((( withCompatCommands == false) && ( (*j).second->IsDiscouraged())) - || ((withCurrentCommands == false) && (!(*j).second->IsDiscouraged()))) + || ((withCurrentCommands == false) && (!(*j).second->IsDiscouraged())) + || (!((*j).second->ShouldAppearInDocumentation())) + ) { continue; } diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index 436236d..c3de8ca 100644 --- a/Source/cmakemain.cxx +++ b/Source/cmakemain.cxx @@ -355,6 +355,7 @@ int do_cmake(int ac, char** av) #ifdef CMAKE_BUILD_WITH_CMAKE cmDocumentation doc; + doc.addCMakeStandardDocSections(); if(doc.CheckOptions(ac, av, "-E") || nocwd) { // Construct and print requested documentation. diff --git a/Source/ctest.cxx b/Source/ctest.cxx index 85cecea..d41627e 100644 --- a/Source/ctest.cxx +++ b/Source/ctest.cxx @@ -291,6 +291,7 @@ int main (int argc, char *argv[]) << "*********************************" << std::endl); } cmDocumentation doc; + doc.addCTestStandardDocSections(); if(doc.CheckOptions(argc, argv) || nocwd) { // Construct and print requested documentation. |