From 1629615a10df10296ba6588f66a680eed424f9ba Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Tue, 3 Jan 2012 00:54:08 +0100 Subject: [PATCH] CPack Documentation extraction from CMake script begins to work - Enhance extract doc parser. Seems robust now. The legacy module documentation parser works as before ignoring the new markup. - Proof of concept for CPack (generic), CPack RPM and CPack Deb generator for macro and variables. Try cpack --help-command and cpack --help-variables --- Modules/CPack.cmake | 55 ++++++++- Modules/CPackDeb.cmake | 34 ++++++ Modules/CPackRPM.cmake | 107 +++++++++++----- Source/CPack/cmCPackDocumentMacros.cxx | 80 ++---------- Source/CPack/cmCPackDocumentVariables.cxx | 24 ++-- Source/CPack/cpack.cxx | 103 ++++++++-------- Source/cmCommand.h | 11 ++ Source/cmDocumentation.cxx | 142 +++++++++++++++++----- Source/cmDocumentation.h | 11 +- Source/cmFunctionCommand.cxx | 11 ++ Source/cmMacroCommand.cxx | 11 ++ Source/cmake.cxx | 4 +- 12 files changed, 388 insertions(+), 205 deletions(-) diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake index ce59693680..1718008ae9 100644 --- a/Modules/CPack.cmake +++ b/Modules/CPack.cmake @@ -1,5 +1,4 @@ -# - Build binary and source package installers -# +# - 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 @@ -55,7 +54,7 @@ ##end # ##variable -# CPACK_PACKAGE_VENDOR - The name of the package vendor (e.g., +# CPACK_PACKAGE_VENDOR - The name of the package vendor. (e.g., # "Kitware"). ##end # @@ -77,78 +76,112 @@ # 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: @@ -207,27 +240,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 # #============================================================================= @@ -271,7 +318,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/CPackDeb.cmake b/Modules/CPackDeb.cmake index 26433bb978..fc7f992c73 100644 --- a/Modules/CPackDeb.cmake +++ b/Modules/CPackDeb.cmake @@ -12,42 +12,61 @@ # http://www.cmake.org/Wiki/CMake:CPackPackageGenerators#DEB_.28UNIX_only.29 # However as a handy reminder here comes the list of specific variables: # +##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 +76,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 +92,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 +109,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 e1e76edcdb..de06feff21 100644 --- a/Modules/CPackRPM.cmake +++ b/Modules/CPackRPM.cmake @@ -1,4 +1,5 @@ # - The builtin (binary) CPack RPM generator (Unix only) +##module # CPackRPM may be used to create RPM package using CPack. # CPackRPM is a CPack generator thus it uses the CPACK_XXX variables # used by CPack : http://www.cmake.org/Wiki/CMake:CPackConfiguration @@ -15,52 +16,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 +84,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 +95,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 +129,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 +139,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 +171,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 +186,8 @@ # CPACK_RPM__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 +201,8 @@ # CPACK_RPM__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__USER_FILELIST # Mandatory : NO @@ -170,12 +212,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__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/CPack/cmCPackDocumentMacros.cxx b/Source/CPack/cmCPackDocumentMacros.cxx index 1ff03516b8..8752e56742 100644 --- a/Source/CPack/cmCPackDocumentMacros.cxx +++ b/Source/CPack/cmCPackDocumentMacros.cxx @@ -3,76 +3,14 @@ void cmCPackDocumentMacros::GetMacrosDocumentation( std::vector& v) { - cmDocumentationEntry e("cpack_add_component", - "Describes a CPack installation component " - "named by the COMPONENT argument to a CMake INSTALL command.", - " cpack_add_component(compname\n" - " [DISPLAY_NAME name]\n" - " [DESCRIPTION description]\n" - " [HIDDEN | REQUIRED | DISABLED ]\n" - " [GROUP group]\n" - " [DEPENDS comp1 comp2 ... ]\n" - " [INSTALL_TYPES type1 type2 ... ]\n" - " [DOWNLOADED]\n" - " [ARCHIVE_FILE filename])\n" - "\n" - "The cmake_add_component command describes an installation" - "component, which the user can opt to install or remove as part of" - " the graphical installation process. compname is the name of the " - "component, as provided to the COMPONENT argument of one or more " - "CMake INSTALL commands." - "\n" - "DISPLAY_NAME is the displayed name of the component, used in " - "graphical installers to display the component name. This value " - "can be any string." - "\n" - "DESCRIPTION is an extended description of the component, used in " - "graphical installers to give the user additional information about " - "the component. Descriptions can span multiple lines using \"\\n\" " - " as the line separator. Typically, these descriptions should be no " - "more than a few lines long." - "\n" - "HIDDEN indicates that this component will be hidden in the " - "graphical installer, so that the user cannot directly change " - "whether it is installed or not." - "\n" - "REQUIRED indicates that this component is required, and therefore " - "will always be installed. It will be visible in the graphical " - "installer, but it cannot be unselected. (Typically, required " - "components are shown greyed out)." - "\n" - "DISABLED indicates that this component should be disabled " - "(unselected) by default. The user is free to select this component " - "for installation, unless it is also HIDDEN." - "\n" - "DEPENDS lists the components on which this component depends. If " - "this component is selected, then each of the components listed " - "must also be selected. The dependency information is encoded " - "within the installer itself, so that users cannot install " - "inconsistent sets of components." - "\n" - "GROUP names the component group of which this component is a " - "part. If not provided, the component will be a standalone " - "component, not part of any component group. Component groups are " - "described with the cpack_add_component_group command, detailed" - "below." - "\n" - "INSTALL_TYPES lists the installation types of which this component " - "is a part. When one of these installations types is selected, this " - "component will automatically be selected. Installation types are" - "described with the cpack_add_install_type command, detailed below." - "\n" - "DOWNLOADED indicates that this component should be downloaded " - "on-the-fly by the installer, rather than packaged in with the " - "installer itself. For more information, see the " - "cpack_configure_downloads command." - "\n" - "ARCHIVE_FILE provides a name for the archive file created by CPack " - "to be used for downloaded components. If not supplied, CPack will " - "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." -); - + // Commented-out example of use + // + // cmDocumentationEntry e("cpack_", + // "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/cmCPackDocumentVariables.cxx b/Source/CPack/cmCPackDocumentVariables.cxx index ab806d289a..8b60d5f0e2 100644 --- a/Source/CPack/cmCPackDocumentVariables.cxx +++ b/Source/CPack/cmCPackDocumentVariables.cxx @@ -6,19 +6,19 @@ void cmCPackDocumentVariables::DefineVariables(cmake* cm) // Subsection: variables defined/used by cpack, // which are common to all CPack generators - cm->DefineProperty - ("CPACK_PACKAGE_VENDOR", cmProperty::VARIABLE, - "The name of the package vendor.", - "If not specified, defaults to \"Humanity\"." - "", false, - "Variables common to all CPack generators"); +// cm->DefineProperty +// ("CPACK_PACKAGE_VENDOR", cmProperty::VARIABLE, +// "The name of the package vendor.", +// "If not specified, defaults to \"Humanity\"." +// "", 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"); +// 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/cpack.cxx b/Source/CPack/cpack.cxx index 8e59fa009a..4117971bae 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -303,29 +303,30 @@ int main (int argc, char *argv[]) help = false; } + // find out which system cpack is running on, so it can setup the search + // paths, so FIND_XXX() commands can be used in scripts + // This part is used for cpack documentation lookup as well. + cminst.AddCMakePaths(); + std::string systemFile = + globalMF->GetModulesFile("CMakeDetermineSystem.cmake"); + if (!globalMF->ReadListFile(0, systemFile.c_str())) + { + cmCPack_Log(&log, cmCPackLog::LOG_ERROR, + "Error reading CMakeDetermineSystem.cmake" << std::endl); + return 1; + } + + systemFile = + globalMF->GetModulesFile("CMakeSystemSpecificInformation.cmake"); + if (!globalMF->ReadListFile(0, systemFile.c_str())) + { + cmCPack_Log(&log, cmCPackLog::LOG_ERROR, + "Error reading CMakeSystemSpecificInformation.cmake" << std::endl); + return 1; + } + 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())) - { - cmCPack_Log(&log, cmCPackLog::LOG_ERROR, - "Error reading CMakeDetermineSystem.cmake" << std::endl); - return 1; - } - - systemFile = - globalMF->GetModulesFile("CMakeSystemSpecificInformation.cmake"); - if (!globalMF->ReadListFile(0, systemFile.c_str())) - { - cmCPack_Log(&log, cmCPackLog::LOG_ERROR, - "Error reading CMakeSystemSpecificInformation.cmake" << std::endl); - return 1; - } - if ( cmSystemTools::FileExists(cpackConfigFile.c_str()) ) { cpackConfigFile = @@ -519,43 +520,47 @@ int main (int argc, char *argv[]) doc.SetSection("Description",cmDocumentationDescription); doc.PrependSection("Options",cmDocumentationOptions); + // statically (in C++ code) defined variables cmCPackDocumentVariables::DefineVariables(&cminst); std::vector commands; - cminst.AddCMakePaths(); - std::string systemFile = - globalMF->GetModulesFile("CMakeDetermineSystem.cmake"); - if (!globalMF->ReadListFile(0, systemFile.c_str())) - { - cmCPack_Log(&log, cmCPackLog::LOG_ERROR, - "Error reading CMakeDetermineSystem.cmake" << std::endl); - return 1; - } + typedef std::pair docModuleSectionPair_t; + typedef std::list docedModulesList_t; + docedModulesList_t docedModList; + docModuleSectionPair_t docPair; + std::string docedFile; - systemFile = - globalMF->GetModulesFile("CMakeSystemSpecificInformation.cmake"); - if (!globalMF->ReadListFile(0, systemFile.c_str())) - { - cmCPack_Log(&log, cmCPackLog::LOG_ERROR, - "Error reading CMakeSystemSpecificInformation.cmake" - << std::endl); - return 1; - } - std::string cpFile = globalMF->GetModulesFile("CPack.cmake"); - doc.getStructuredDocFromFile(cpFile.c_str(), - commands,&cminst,"Variables common to all CPack generators"); - cpFile = globalMF->GetModulesFile("CPackComponent.cmake"); - doc.getStructuredDocFromFile(cpFile.c_str(), - commands,&cminst,"Variables common to all CPack generators"); - cpFile = globalMF->GetModulesFile("CPackRPM.cmake"); - doc.getStructuredDocFromFile(cpFile.c_str(), - commands,&cminst,"Variables specific to a CPack generator"); + // build the list of files to be parsed for documentation + // extraction + docPair.first = "CPack.cmake"; + docPair.second = "Variables common to all CPack generators"; + docedModList.push_back(docPair); + docPair.first = "CPackComponent.cmake"; + docedModList.push_back(docPair); + docPair.first = "CPackRPM.cmake"; + docPair.second = "Variables specific to a CPack generator"; + docedModList.push_back(docPair); + docPair.first = "CPackDeb.cmake"; + docedModList.push_back(docPair); + + // parse the files for documentation. + for (docedModulesList_t::iterator it = docedModList.begin(); + it!= docedModList.end(); ++it) + { + docedFile = globalMF->GetModulesFile((it->first).c_str()); + if (docedFile.length()!=0) + { + doc.GetStructuredDocFromFile(docedFile.c_str(), + commands,&cminst,(it->second).c_str()); + } + } std::map propDocs; cminst.GetPropertiesDocumentation(propDocs); doc.SetSections(propDocs); - cminst.GetCommandDocumentation(commands); + cminst.GetCommandDocumentation(commands,true,false); + // statically (in C++ code) defined macros/commands cmCPackDocumentMacros::GetMacrosDocumentation(commands); doc.SetSection("Commands",commands); diff --git a/Source/cmCommand.h b/Source/cmCommand.h index 7817eb3c1b..e046096317 100644 --- a/Source/cmCommand.h +++ b/Source/cmCommand.h @@ -110,6 +110,17 @@ public: return false; } + /** + * 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. */ diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index b7b8e374fb..f032592465 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -757,15 +757,14 @@ static void trim(std::string& s) else s.erase(s.begin(), s.end()); } -int cmDocumentation::getStructuredDocFromFile( +int cmDocumentation::GetStructuredDocFromFile( const char* fname, std::vector& commands, cmake* cm, const char *docSection) { typedef enum sdoce { - SDOC_NONE, SDOC_MACRO, - SDOC_PARAM, SDOC_VARIABLE, + SDOC_NONE, SDOC_MODULE, SDOC_MACRO, SDOC_FUNCTION, SDOC_VARIABLE, SDOC_UNKNOWN} sdoc_t; int nbDocItemFound = 0; int docCtxIdx = 0; @@ -775,15 +774,16 @@ int cmDocumentation::getStructuredDocFromFile( std::ifstream fin(fname); if(!fin) { - //std::cerr << "Internal error: can not open script file: <" << fname <<">."<< std::endl; return nbDocItemFound; } std::string name; std::string full; std::string brief; std::string line; - bool newCtx = false; - bool inBrief = false; + bool newCtx = false; /* we've just entered ## 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; @@ -806,11 +806,24 @@ int cmDocumentation::getStructuredDocFromFile( 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.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; @@ -821,15 +834,20 @@ int cmDocumentation::getStructuredDocFromFile( full.c_str(),false, docSection); break; + case SDOC_MODULE: + /* not implemented */ + break; + default: + /* ignore other cases */ + break; } docCtxIdx--; newCtx = false; + ++nbDocItemFound; } else { // error out unhandled context - std::cerr << "Internal error: unknown markup context <" - << mkword <<"> found in:" << fname << std::endl; return nbDocItemFound; } /* context is set go to next doc line */ @@ -843,47 +861,106 @@ int cmDocumentation::getStructuredDocFromFile( // followed by a blank line) if (newCtx) { - name = line.substr(1,line.find("-")-1); - trim(name); - brief = ""; - line = line.substr(line.find("- ")+1,std::string::npos); - inBrief = true; - full = ""; + // 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) { - inBrief = false; - full += "\n"; + if (inBrief) { + inBrief = false; + full = ""; + } else { + full += "\n"; + // the first paragraph of full has ended + inFullFirstParagraph = false; + } newParagraph = true; } - // brief terminated by . - else if (inBrief && line[line.length()-1]=='.') + // brief is terminated by '.' + else if (inBrief && (line.find('.')!=std::string::npos)) { + /* the brief just ended */ inBrief = false; - brief += line.c_str()+1; + 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; - } + if (inBrief) + { + text = &brief; + } + else + { + text = &full; + } // two spaces if(line[1] == ' ' && line[2] == ' ') { - if(!newParagraph) + // there is no "full first paragraph at all." + if (line[3] == ' ') { - - *text += "\n"; - newParagraph = true; + inFullFirstParagraph = false; } - // Skip #, and leave space for preformatted - *text += line.c_str()+1; - *text += "\n"; + + 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] == ' ') { @@ -910,7 +987,6 @@ int cmDocumentation::getStructuredDocFromFile( /* next line is not the first context line */ newCtx = false; } - return nbDocItemFound; } diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index 2f6e09ec08..fae409f32d 100644 --- a/Source/cmDocumentation.h +++ b/Source/cmDocumentation.h @@ -133,23 +133,26 @@ public: void addCPackStandardDocSections(); /** - * Get the documentation of macros and variable documented + * 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 ##macro, ##param, ##variable and ##end - * which is closing either of the previous ones. + * Current markup are ##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, + int GetStructuredDocFromFile(const char* fname, std::vector& commands, cmake* cm, const char *docSection); diff --git a/Source/cmFunctionCommand.cxx b/Source/cmFunctionCommand.cxx index ec4fd16bca..7a80a1c717 100644 --- a/Source/cmFunctionCommand.cxx +++ b/Source/cmFunctionCommand.cxx @@ -22,6 +22,17 @@ public: ///! clean up any memory allocated by the function ~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. */ diff --git a/Source/cmMacroCommand.cxx b/Source/cmMacroCommand.cxx index 774f32b446..f81a63db01 100644 --- a/Source/cmMacroCommand.cxx +++ b/Source/cmMacroCommand.cxx @@ -22,6 +22,17 @@ public: ///! clean up any memory allocated by the macro ~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. */ diff --git a/Source/cmake.cxx b/Source/cmake.cxx index d691f46dc2..f8e1216638 100644 --- a/Source/cmake.cxx +++ b/Source/cmake.cxx @@ -2677,7 +2677,9 @@ void cmake::GetCommandDocumentation(std::vector& 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; }