kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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
This commit is contained in:
Eric NOULARD 2012-01-03 00:54:08 +01:00
parent 83e34dd9e6
commit 1629615a10
12 changed files with 388 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
Modules/CPack.cmake
View File

@ -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

34
Modules/CPackDeb.cmake
View File

@ -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.

107
Modules/CPackRPM.cmake
View File

@ -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_<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 +201,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 +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_<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.

80
Source/CPack/cmCPackDocumentMacros.cxx
View File

@ -3,76 +3,14 @@
void cmCPackDocumentMacros::GetMacrosDocumentation(
std::vector<cmDocumentationEntry>& 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_<macro>",
// "Brief Description"
// "which may be on several lines.",
// "Long description in pre-formatted format"
// " blah\n"
// " blah\n"
//);
//v.push_back(e);
}

24
Source/CPack/cmCPackDocumentVariables.cxx
View File

@ -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");
}

103
Source/CPack/cpack.cxx
View File

@ -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<cmDocumentationEntry> 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<std::string,std::string> docModuleSectionPair_t;
typedef std::list<docModuleSectionPair_t> 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<std::string,cmDocumentationSection *> 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);

11
Source/cmCommand.h
View File

@ -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.
*/

142
Source/cmDocumentation.cxx
View File

@ -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<cmDocumentationEntry>& 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 ##<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;
@ -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;
}

11
Source/cmDocumentation.h
View File

@ -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<cmDocumentationEntry>& commands,
cmake* cm,
const char *docSection);

11
Source/cmFunctionCommand.cxx
View File

@ -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.
*/

11
Source/cmMacroCommand.cxx
View File

@ -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.
*/

4
Source/cmake.cxx
View File

@ -2677,7 +2677,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;
}