reactos/CMake
1
0
Fork 0
mirror of https://github.com/reactos/CMake.git synced 2024-11-24 12:09:48 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge topic 'ImproveCPackDoc-reloaded'

Browse Source 
d4b77eb Avoid discovering system infos for documentation. Adding some path is enough.
9002f73 Fix non existent std::string::clear on VS6
02ccb32 Create getDocumentedModulesListInDir which may be used in other context.
24fbc28 Add missing section markup for CPackComponent
bafd8a9 Example of builtin variable documentation (i.e. only used in C++ source code).
543f1ad Make the load of script documentation more efficient and dynamic.
cdbd1a9 Fix another compiler warning due to a typo
52c53de Really avoid compiler warning about unused vars
37f90ed Calm down compiler warning about unused var
7c82b7f Fix potential bad memory access, thanks to Eike
62b589b Suppress unused var, beautify code, avoid 1 extra newline.
751713f Update bash completion file in order to handle new CPack doc options.
1629615 CPack Documentation extraction from CMake script begins to work
83e34dd Implement simple CMake script comment markup language.
c6a0169 CPack begin the implementation of --help-command* and --help-variables*
This commit is contained in:
David Cole 2012-02-14 16:14:56 -05:00 committed by CMake Topic Stage
commit 4f9c114dfa
21 changed files with 911 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
Docs/cmake-completion
View File

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

89
Modules/CPack.cmake
View File

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

12
Modules/CPackComponent.cmake
View File

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

38
Modules/CPackDeb.cmake
View File

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

109
Modules/CPackRPM.cmake
View File

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

2
Source/CMakeLists.txt
View File

@ -449,6 +449,8 @@ SET(CPACK_SRCS
CPack/cmCPackTarBZip2Generator.cxx
CPack/cmCPackTarCompressGenerator.cxx
CPack/cmCPackZIPGenerator.cxx
CPack/cmCPackDocumentVariables.cxx
CPack/cmCPackDocumentMacros.cxx
)
IF(CYGWIN)

16
Source/CPack/cmCPackDocumentMacros.cxx Normal file
View File

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

21
Source/CPack/cmCPackDocumentMacros.h Normal file
View File

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

32
Source/CPack/cmCPackDocumentVariables.cxx Normal file
View File

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

21
Source/CPack/cmCPackDocumentVariables.h Normal file
View File

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

95
Source/CPack/cpack.cxx
View File

@ -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();

1
Source/CursesDialog/ccmake.cxx
View File

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

1
Source/QtDialog/CMakeSetup.cxx
View File

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

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

457
Source/cmDocumentation.cxx
View File

@ -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)
{
@ -709,6 +664,410 @@ cmDocumentation::Form cmDocumentation::GetFormFromFilename(
return cmDocumentation::TextForm;
}
//----------------------------------------------------------------------------
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)

68
Source/cmDocumentation.h
View File

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

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

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

1
Source/cmakemain.cxx
View File

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

1
Source/ctest.cxx
View File

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