From c6a016944211b737c45385423fc7df10462e34ab Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Sun, 13 Nov 2011 22:44:53 +0100 Subject: CPack begin the implementation of --help-command* and --help-variables* This modifications set tries to keep the unified doc for cmake/ctest/cpack while introducing tool specific documentation separated. Some documentation sections for CMake do not fit well to CPack. --- Source/CMakeLists.txt | 2 + Source/CPack/cmCPackDocumentMacros.cxx | 78 ++++++++++++++++++ Source/CPack/cmCPackDocumentMacros.h | 21 +++++ Source/CPack/cmCPackDocumentVariables.cxx | 30 +++++++ Source/CPack/cmCPackDocumentVariables.h | 21 +++++ Source/CPack/cpack.cxx | 66 +++++++++++++-- Source/CursesDialog/ccmake.cxx | 1 + Source/QtDialog/CMakeSetup.cxx | 1 + Source/cmDocumentation.cxx | 132 +++++++++++++++++++----------- Source/cmDocumentation.h | 12 +++ Source/cmakemain.cxx | 1 + Source/ctest.cxx | 1 + 12 files changed, 312 insertions(+), 54 deletions(-) create mode 100644 Source/CPack/cmCPackDocumentMacros.cxx create mode 100644 Source/CPack/cmCPackDocumentMacros.h create mode 100644 Source/CPack/cmCPackDocumentVariables.cxx create mode 100644 Source/CPack/cmCPackDocumentVariables.h diff --git a/Source/CMakeLists.txt b/Source/CMakeLists.txt index b5115b7..0c420b9 100644 --- a/Source/CMakeLists.txt +++ b/Source/CMakeLists.txt @@ -449,6 +449,8 @@ SET(CPACK_SRCS CPack/cmCPackTarBZip2Generator.cxx CPack/cmCPackTarCompressGenerator.cxx CPack/cmCPackZIPGenerator.cxx + CPack/cmCPackDocumentVariables.cxx + CPack/cmCPackDocumentMacros.cxx ) IF(CYGWIN) diff --git a/Source/CPack/cmCPackDocumentMacros.cxx b/Source/CPack/cmCPackDocumentMacros.cxx new file mode 100644 index 0000000..0dd51a9 --- /dev/null +++ b/Source/CPack/cmCPackDocumentMacros.cxx @@ -0,0 +1,78 @@ +#include "cmCPackDocumentMacros.h" + +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." +); + + v.push_back(e); +} diff --git a/Source/CPack/cmCPackDocumentMacros.h b/Source/CPack/cmCPackDocumentMacros.h new file mode 100644 index 0000000..544f74f --- /dev/null +++ b/Source/CPack/cmCPackDocumentMacros.h @@ -0,0 +1,21 @@ +/*============================================================================ + CMake - Cross Platform Makefile Generator + Copyright 2000-2009 Kitware, Inc., Insight Software Consortium + + Distributed under the OSI-approved BSD License (the "License"); + see accompanying file Copyright.txt for details. + + This software is distributed WITHOUT ANY WARRANTY; without even the + implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the License for more information. +============================================================================*/ +#ifndef cmCPackDocumentMacros_h +#define cmCPackDocumentMacros_h +#include "cmStandardIncludes.h" +class cmCPackDocumentMacros +{ +public: + static void GetMacrosDocumentation(std::vector& v); +}; + +#endif diff --git a/Source/CPack/cmCPackDocumentVariables.cxx b/Source/CPack/cmCPackDocumentVariables.cxx new file mode 100644 index 0000000..1c98e7c --- /dev/null +++ b/Source/CPack/cmCPackDocumentVariables.cxx @@ -0,0 +1,30 @@ +#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_PACKAGE_NAME", cmProperty::VARIABLE, + "The name of the package (or application).", + "If not specified, defaults to the project name." + "", 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"); +} diff --git a/Source/CPack/cmCPackDocumentVariables.h b/Source/CPack/cmCPackDocumentVariables.h new file mode 100644 index 0000000..e7971be --- /dev/null +++ b/Source/CPack/cmCPackDocumentVariables.h @@ -0,0 +1,21 @@ +/*============================================================================ + CMake - Cross Platform Makefile Generator + Copyright 2000-2009 Kitware, Inc., Insight Software Consortium + + Distributed under the OSI-approved BSD License (the "License"); + see accompanying file Copyright.txt for details. + + This software is distributed WITHOUT ANY WARRANTY; without even the + implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the License for more information. +============================================================================*/ +#ifndef cmCPackDocumentVariables_h +#define cmCPackDocumentVariables_h +class cmake; +class cmCPackDocumentVariables +{ +public: + static void DefineVariables(cmake* cm); +}; + +#endif diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx index 163f744..2cfbf12 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -14,6 +14,8 @@ // Need these for documentation support. #include "cmake.h" #include "cmDocumentation.h" +#include "cmCPackDocumentVariables.h" +#include "cmCPackDocumentMacros.h" #include "cmCPackGeneratorFactory.h" #include "cmCPackGenerator.h" #include "cmake.h" @@ -90,6 +92,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 +173,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 +193,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 +219,6 @@ int main (int argc, char *argv[]) cpackConfigFile = ""; - cmDocumentation doc; cmsys::CommandLineArguments arg; arg.Initialize(argc, argv); typedef cmsys::CommandLineArguments argT; @@ -252,10 +291,16 @@ 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; } if ( parsed && !help ) @@ -465,14 +510,25 @@ int main (int argc, char *argv[]) */ if ( help ) { - doc.CheckOptions(argc, argv); // Construct and print requested documentation. + std::vector variables; + doc.SetName("cpack"); doc.SetSection("Name",cmDocumentationName); doc.SetSection("Usage",cmDocumentationUsage); doc.SetSection("Description",cmDocumentationDescription); doc.PrependSection("Options",cmDocumentationOptions); + cmCPackDocumentVariables::DefineVariables(&cminst); + std::map propDocs; + cminst.GetPropertiesDocumentation(propDocs); + doc.SetSections(propDocs); + + std::vector commands; + cminst.GetCommandDocumentation(commands); + cmCPackDocumentMacros::GetMacrosDocumentation(commands); + doc.SetSection("Commands",commands); + std::vector v; cmCPackGeneratorFactory::DescriptionsMap::const_iterator generatorIt; for( generatorIt = generators.GetGeneratorsList().begin(); diff --git a/Source/CursesDialog/ccmake.cxx b/Source/CursesDialog/ccmake.cxx index b1a72af..623d7d3 100644 --- a/Source/CursesDialog/ccmake.cxx +++ b/Source/CursesDialog/ccmake.cxx @@ -102,6 +102,7 @@ int main(int argc, char** argv) { cmSystemTools::FindExecutableDirectory(argv[0]); cmDocumentation doc; + doc.addCMakeStandardDocSections(); if(doc.CheckOptions(argc, argv)) { cmake hcm; diff --git a/Source/QtDialog/CMakeSetup.cxx b/Source/QtDialog/CMakeSetup.cxx index 7ba7f51..b4f3d72 100644 --- a/Source/QtDialog/CMakeSetup.cxx +++ b/Source/QtDialog/CMakeSetup.cxx @@ -64,6 +64,7 @@ int main(int argc, char** argv) // check docs first so that X is not need to get docs // do docs, if args were given cmDocumentation doc; + doc.addCMakeStandardDocSections(); if(argc >1 && doc.CheckOptions(argc, argv)) { // Construct and print requested documentation. diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 07683d0..8f603f2 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -220,55 +220,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; } @@ -710,6 +662,88 @@ cmDocumentation::Form cmDocumentation::GetFormFromFilename( } //---------------------------------------------------------------------------- +void cmDocumentation::addCommonStandardDocSections() +{ + cmDocumentationSection *sec; + + sec = new cmDocumentationSection("Author","AUTHOR"); + sec->Append(cmDocumentationEntry + (0, + "This manual page was generated by the \"--help-man\" option.", + 0)); + this->AllSections["Author"] = sec; + + sec = new cmDocumentationSection("Copyright","COPYRIGHT"); + sec->Append(cmDocumentationCopyright); + this->AllSections["Copyright"] = sec; + + sec = new cmDocumentationSection("See Also","SEE ALSO"); + sec->Append(cmDocumentationStandardSeeAlso); + this->AllSections["Standard See Also"] = sec; + + sec = new cmDocumentationSection("Options","OPTIONS"); + sec->Append(cmDocumentationStandardOptions); + this->AllSections["Options"] = sec; + + sec = new cmDocumentationSection("Compatibility Commands", + "COMPATIBILITY COMMANDS"); + sec->Append(cmCompatCommandsDocumentationDescription); + this->AllSections["Compatibility Commands"] = sec; +} + +//---------------------------------------------------------------------------- +void cmDocumentation::addCMakeStandardDocSections() +{ + cmDocumentationSection *sec; + + sec = new cmDocumentationSection("Properties","PROPERTIES"); + sec->Append(cmPropertiesDocumentationDescription); + this->AllSections["Properties Description"] = sec; + + sec = new cmDocumentationSection("Generators","GENERATORS"); + sec->Append(cmDocumentationGeneratorsHeader); + this->AllSections["Generators"] = sec; + + this->PropertySections.push_back("Properties of Global Scope"); + this->PropertySections.push_back("Properties on Directories"); + this->PropertySections.push_back("Properties on Targets"); + this->PropertySections.push_back("Properties on Tests"); + this->PropertySections.push_back("Properties on Source Files"); + this->PropertySections.push_back("Properties on Cache Entries"); + + this->VariableSections.push_back("Variables that Provide Information"); + this->VariableSections.push_back("Variables That Change Behavior"); + this->VariableSections.push_back("Variables That Describe the System"); + this->VariableSections.push_back("Variables that Control the Build"); + this->VariableSections.push_back("Variables for Languages"); + +} + +//---------------------------------------------------------------------------- +void cmDocumentation::addCTestStandardDocSections() +{ + cmDocumentationSection *sec; + // 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"); +} + +//---------------------------------------------------------------------------- bool cmDocumentation::CheckOptions(int argc, const char* const* argv, const char* exitOpt) { diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index 34b83b1..a7a7a1f 100644 --- a/Source/cmDocumentation.h +++ b/Source/cmDocumentation.h @@ -119,6 +119,18 @@ 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(); + private: void SetForm(Form f); void SetDocName(const char* docname); diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index 436236d..c3de8ca 100644 --- a/Source/cmakemain.cxx +++ b/Source/cmakemain.cxx @@ -355,6 +355,7 @@ int do_cmake(int ac, char** av) #ifdef CMAKE_BUILD_WITH_CMAKE cmDocumentation doc; + doc.addCMakeStandardDocSections(); if(doc.CheckOptions(ac, av, "-E") || nocwd) { // Construct and print requested documentation. diff --git a/Source/ctest.cxx b/Source/ctest.cxx index 85cecea..d41627e 100644 --- a/Source/ctest.cxx +++ b/Source/ctest.cxx @@ -291,6 +291,7 @@ int main (int argc, char *argv[]) << "*********************************" << std::endl); } cmDocumentation doc; + doc.addCTestStandardDocSections(); if(doc.CheckOptions(argc, argv) || nocwd) { // Construct and print requested documentation. -- cgit v0.12 From 83e34dd9e688b4721c70c56e66629bdc2768fa77 Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Tue, 15 Nov 2011 20:24:38 +0100 Subject: Implement simple CMake script comment markup language. The language is very simple. It use ## special comment which opens a structured documentation block and ##end closes it. This may be used to extract documentation for macro as 'command' and 'variables' such that cpack --help-command and --help-variable does parse builtin modules files (CPack.cmake, CPackComponent.cmake, ...) in order to extract the corresponding doc. --- Modules/CPack.cmake | 12 +++ Modules/CPackComponent.cmake | 8 ++ Source/CPack/cmCPackDocumentMacros.cxx | 2 +- Source/CPack/cmCPackDocumentVariables.cxx | 6 -- Source/CPack/cpack.cxx | 34 +++++- Source/cmDocumentation.cxx | 171 ++++++++++++++++++++++++++++++ Source/cmDocumentation.h | 23 ++++ 7 files changed, 247 insertions(+), 9 deletions(-) diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake index 2cc27cf..ce59693 100644 --- a/Modules/CPack.cmake +++ b/Modules/CPack.cmake @@ -49,21 +49,33 @@ # there are a variety of variables that can be set to customize # the resulting installers. The most commonly-used variables are: # +##variable # CPACK_PACKAGE_NAME - The name of the package (or application). If # not specified, defaults to the project name. +##end # +##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 # # CPACK_PACKAGE_DESCRIPTION_SUMMARY - Short description of the # project (only a few words). diff --git a/Modules/CPackComponent.cmake b/Modules/CPackComponent.cmake index 1c10372..a0e0667 100644 --- a/Modules/CPackComponent.cmake +++ b/Modules/CPackComponent.cmake @@ -21,6 +21,7 @@ # INSTALL commands, and should be further described by the following # CPack commands: # +##macro # cpack_add_component - Describes a CPack installation component # named by the COMPONENT argument to a CMake INSTALL command. # @@ -90,7 +91,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 +137,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 +158,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 +210,7 @@ # that can be called from Windows' Add/Remove Programs dialog (via the # "Modify" button) to change the set of installed components. NO_ADD_REMOVE # turns off this behavior. This option is ignored on Mac OS X. +##endmacro #============================================================================= # Copyright 2006-2009 Kitware, Inc. diff --git a/Source/CPack/cmCPackDocumentMacros.cxx b/Source/CPack/cmCPackDocumentMacros.cxx index 0dd51a9..1ff0351 100644 --- a/Source/CPack/cmCPackDocumentMacros.cxx +++ b/Source/CPack/cmCPackDocumentMacros.cxx @@ -74,5 +74,5 @@ void cmCPackDocumentMacros::GetMacrosDocumentation( "information." ); - v.push_back(e); + //v.push_back(e); } diff --git a/Source/CPack/cmCPackDocumentVariables.cxx b/Source/CPack/cmCPackDocumentVariables.cxx index 1c98e7c..ab806d2 100644 --- a/Source/CPack/cmCPackDocumentVariables.cxx +++ b/Source/CPack/cmCPackDocumentVariables.cxx @@ -5,12 +5,6 @@ void cmCPackDocumentVariables::DefineVariables(cmake* cm) { // Subsection: variables defined/used by cpack, // which are common to all CPack generators - cm->DefineProperty - ("CPACK_PACKAGE_NAME", cmProperty::VARIABLE, - "The name of the package (or application).", - "If not specified, defaults to the project name." - "", false, - "Variables common to all CPack generators"); cm->DefineProperty ("CPACK_PACKAGE_VENDOR", cmProperty::VARIABLE, diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx index 2cfbf12..8e59fa0 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -520,11 +520,41 @@ int main (int argc, char *argv[]) doc.PrependSection("Options",cmDocumentationOptions); 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; + } + + 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"); + std::map propDocs; cminst.GetPropertiesDocumentation(propDocs); doc.SetSections(propDocs); - - std::vector commands; cminst.GetCommandDocumentation(commands); cmCPackDocumentMacros::GetMacrosDocumentation(commands); doc.SetSection("Commands",commands); diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 8f603f2..b7b8e37 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -511,6 +511,8 @@ bool cmDocumentation::CreateSingleModule(const char* fname, { if(line.size() && line[0] == '#') { + /* line beginnings with ## are mark-up ignore them */ + if (line[1] == '#') continue; // blank line if(line.size() <= 2) { @@ -744,6 +746,175 @@ void cmDocumentation::addCPackStandardDocSections() } //---------------------------------------------------------------------------- +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& commands, + cmake* cm, + const char *docSection) +{ + typedef enum sdoce { + SDOC_NONE, SDOC_MACRO, + SDOC_PARAM, SDOC_VARIABLE, + SDOC_UNKNOWN} sdoc_t; + int nbDocItemFound = 0; + int docCtxIdx = 0; + std::vector docContextStack(60); + docContextStack[docCtxIdx]=SDOC_NONE; + cmDocumentationEntry e; + 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; + brief = ""; + full = ""; + bool newParagraph = true; + while ( fin && cmSystemTools::GetLineFromStream(fin, line) ) + { + if(line.size() && line[0] == '#') + { + /* handle structured doc context */ + if (line[1]=='#') { + std::string mkword = line.substr(2,std::string::npos); + if (mkword=="macro") + { + docCtxIdx++; + docContextStack[docCtxIdx]=SDOC_MACRO; + newCtx = true; + } + else if (mkword=="variable") + { + docCtxIdx++; + docContextStack[docCtxIdx]=SDOC_VARIABLE; + newCtx = true; + } + else if (mkword.substr(0,3)=="end") + { + ; + switch (docContextStack[docCtxIdx]) { + case SDOC_MACRO: + 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; + } + docCtxIdx--; + newCtx = false; + } + 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 */ + 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) + { + name = line.substr(1,line.find("-")-1); + trim(name); + brief = ""; + line = line.substr(line.find("- ")+1,std::string::npos); + inBrief = true; + full = ""; + } + // blank line + if(line.size() <= 2) + { + inBrief = false; + full += "\n"; + newParagraph = true; + } + // brief terminated by . + else if (inBrief && line[line.length()-1]=='.') + { + inBrief = false; + brief += line.c_str()+1; + } + // 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] == ' ') + { + if(!newParagraph) + { + + *text += "\n"; + newParagraph = true; + } + // Skip #, and leave space for preformatted + *text += line.c_str()+1; + *text += "\n"; + } + else if(line[1] == ' ') + { + if(!newParagraph) + { + *text += " "; + } + newParagraph = false; + // skip # and space + *text += line.c_str()+2; + } + else + { + if(!newParagraph) + { + *text += " "; + } + newParagraph = false; + // skip # + *text += line.c_str()+1; + } + } + } + /* next line is not the first context line */ + newCtx = false; + } + + return nbDocItemFound; +} + +//---------------------------------------------------------------------------- bool cmDocumentation::CheckOptions(int argc, const char* const* argv, const char* exitOpt) { diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index a7a7a1f..2f6e09e 100644 --- a/Source/cmDocumentation.h +++ b/Source/cmDocumentation.h @@ -21,6 +21,7 @@ #include "cmDocumentationFormatterText.h" #include "cmDocumentationFormatterUsage.h" #include "cmDocumentationSection.h" +#include "cmake.h" namespace cmsys { @@ -131,6 +132,28 @@ public: /** Add the CPack standard documentation section(s) */ void addCPackStandardDocSections(); + /** + * Get the documentation of macros and variable documented + * with CMake structured documentation in a CMake script. + * 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. + * @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) + * @return the number of documented items (command and variable) + * found in the file. + */ + int getStructuredDocFromFile(const char* fname, + std::vector& commands, + cmake* cm, + const char *docSection); + ; private: void SetForm(Form f); void SetDocName(const char* docname); -- cgit v0.12 From 1629615a10df10296ba6588f66a680eed424f9ba Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Tue, 3 Jan 2012 00:54:08 +0100 Subject: 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 | 140 +++++++++++++++++++++++------- Source/cmDocumentation.h | 11 ++- Source/cmFunctionCommand.cxx | 11 +++ Source/cmMacroCommand.cxx | 11 +++ Source/cmake.cxx | 4 +- 12 files changed, 387 insertions(+), 204 deletions(-) diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake index ce59693..1718008 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 26433bb..fc7f992 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 e1e76ed..de06fef 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 1ff0351..8752e56 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 ab806d2..8b60d5f 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 8e59fa0..4117971 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -303,29 +303,30 @@ int main (int argc, char *argv[]) help = false; } - 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 + // 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())) { - // 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; - } + 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; - } + 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 ) + { 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; - } - - 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"); + typedef std::pair docModuleSectionPair_t; + typedef std::list docedModulesList_t; + docedModulesList_t docedModList; + docModuleSectionPair_t docPair; + std::string docedFile; + + // 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 7817eb3..e046096 100644 --- a/Source/cmCommand.h +++ b/Source/cmCommand.h @@ -111,6 +111,17 @@ public: } /** + * This is used to avoid including this command + * in documentation. This is mainly used by + * cmMacroHelperCommand and cmFunctionHelperCommand + * which cannot provide appropriate documentation. + */ + virtual bool ShouldAppearInDocumentation() + { + return true; + } + + /** * The name of the command as specified in CMakeList.txt. */ virtual const char* GetName() = 0; diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index b7b8e37..f032592 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] == ' ') { + inFullFirstParagraph = false; + } - *text += "\n"; - newParagraph = true; + if(!newParagraph && !inFullFirstParagraph) + { + *text += "\n"; + newParagraph = true; } - // Skip #, and leave space for preformatted - *text += line.c_str()+1; - *text += "\n"; + // 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 2f6e09e..fae409f 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 ec4fd16..7a80a1c 100644 --- a/Source/cmFunctionCommand.cxx +++ b/Source/cmFunctionCommand.cxx @@ -23,6 +23,17 @@ public: ~cmFunctionHelperCommand() {}; /** + * This is used to avoid including this command + * in documentation. This is mainly used by + * cmMacroHelperCommand and cmFunctionHelperCommand + * which cannot provide appropriate documentation. + */ + virtual bool ShouldAppearInDocumentation() + { + return false; + } + + /** * This is a virtual constructor for the command. */ virtual cmCommand* Clone() diff --git a/Source/cmMacroCommand.cxx b/Source/cmMacroCommand.cxx index 774f32b..f81a63d 100644 --- a/Source/cmMacroCommand.cxx +++ b/Source/cmMacroCommand.cxx @@ -23,6 +23,17 @@ public: ~cmMacroHelperCommand() {}; /** + * This is used to avoid including this command + * in documentation. This is mainly used by + * cmMacroHelperCommand and cmFunctionHelperCommand + * which cannot provide appropriate documentation. + */ + virtual bool ShouldAppearInDocumentation() + { + return false; + } + + /** * This is a virtual constructor for the command. */ virtual cmCommand* Clone() diff --git a/Source/cmake.cxx b/Source/cmake.cxx index d691f46..f8e1216 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; } -- cgit v0.12 From 751713f54b70d955334818f534139f9b59cc66e6 Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Sun, 22 Jan 2012 13:37:39 +0100 Subject: Update bash completion file in order to handle new CPack doc options. --- Docs/cmake-completion | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Docs/cmake-completion b/Docs/cmake-completion index d82d608..d70ac24 100644 --- a/Docs/cmake-completion +++ b/Docs/cmake-completion @@ -130,6 +130,16 @@ _cpack() COMPREPLY=( $(compgen -f ${cur}) ) return 0 ;; + --help-variable) + local running=$(for x in `cpack --help-variable-list | grep -v "cpack version" `; do echo ${x} ; done ) + COMPREPLY=( $(compgen -W "${running}" -- ${cur}) ) + return 0 + ;; + --help-command) + local running=$(for x in `cpack --help-command-list | grep -v "cpack version" `; do echo ${x} ; done ) + COMPREPLY=( $(compgen -W "${running}" -- ${cur}) ) + return 0 + ;; *) ;; esac -- cgit v0.12 From 62b589b4cd73fa59b5902f8f0a5779a6a77947aa Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Tue, 24 Jan 2012 23:38:22 +0100 Subject: Suppress unused var, beautify code, avoid 1 extra newline. There remains extra newlines in text Formatter output but the parser does not seem to be the culprit. The formatter should be. --- Source/cmDocumentation.cxx | 43 +++++++++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index f032592..8aa4721 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -724,7 +724,6 @@ void cmDocumentation::addCMakeStandardDocSections() //---------------------------------------------------------------------------- void cmDocumentation::addCTestStandardDocSections() { - cmDocumentationSection *sec; // This is currently done for backward compatibility reason // We may suppress some of these. addCMakeStandardDocSections(); @@ -749,12 +748,16 @@ void cmDocumentation::addCPackStandardDocSections() static void trim(std::string& s) { std::string::size_type pos = s.find_last_not_of(' '); - if(pos != std::string::npos) { + 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()); + } + else + { + s.erase(s.begin(), s.end()); + } } int cmDocumentation::GetStructuredDocFromFile( @@ -792,7 +795,8 @@ int cmDocumentation::GetStructuredDocFromFile( if(line.size() && line[0] == '#') { /* handle structured doc context */ - if (line[1]=='#') { + if (line[1]=='#') + { std::string mkword = line.substr(2,std::string::npos); if (mkword=="macro") { @@ -904,7 +908,10 @@ int cmDocumentation::GetStructuredDocFromFile( inBrief = false; full = ""; } else { - full += "\n"; + if (full.length()>0) + { + full += "\n"; + } // the first paragraph of full has ended inFullFirstParagraph = false; } @@ -949,18 +956,18 @@ int cmDocumentation::GetStructuredDocFromFile( *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"; - } + // 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] == ' ') { -- cgit v0.12 From 7c82b7f51a7c7a02d060ca804e15049c0a745748 Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Tue, 31 Jan 2012 21:26:44 +0100 Subject: Fix potential bad memory access, thanks to Eike --- Source/cmDocumentation.cxx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 8aa4721..80f74a6 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -512,7 +512,7 @@ bool cmDocumentation::CreateSingleModule(const char* fname, if(line.size() && line[0] == '#') { /* line beginnings with ## are mark-up ignore them */ - if (line[1] == '#') continue; + if (line.size()>=2 && line[1] == '#') continue; // blank line if(line.size() <= 2) { -- cgit v0.12 From 37f90ed57609308ff33223474567e5bfb94c2a21 Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Tue, 31 Jan 2012 21:27:55 +0100 Subject: Calm down compiler warning about unused var --- Source/CPack/cmCPackDocumentMacros.cxx | 2 ++ Source/CPack/cmCPackDocumentVariables.cxx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/Source/CPack/cmCPackDocumentMacros.cxx b/Source/CPack/cmCPackDocumentMacros.cxx index 8752e56..94d5391 100644 --- a/Source/CPack/cmCPackDocumentMacros.cxx +++ b/Source/CPack/cmCPackDocumentMacros.cxx @@ -3,6 +3,8 @@ void cmCPackDocumentMacros::GetMacrosDocumentation( std::vector& v) { + // avoid compiler warning + (int)v.size(); // Commented-out example of use // // cmDocumentationEntry e("cpack_", diff --git a/Source/CPack/cmCPackDocumentVariables.cxx b/Source/CPack/cmCPackDocumentVariables.cxx index 8b60d5f..27d4df2 100644 --- a/Source/CPack/cmCPackDocumentVariables.cxx +++ b/Source/CPack/cmCPackDocumentVariables.cxx @@ -3,6 +3,8 @@ void cmCPackDocumentVariables::DefineVariables(cmake* cm) { + // avoid compiler warning + (void*)cm; // Subsection: variables defined/used by cpack, // which are common to all CPack generators -- cgit v0.12 From 52c53deb1bc0109340479aa1284e2fa03b2f5401 Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Wed, 1 Feb 2012 20:47:28 +0100 Subject: Really avoid compiler warning about unused vars --- Source/CPack/cmCPackDocumentMacros.cxx | 4 +--- Source/CPack/cmCPackDocumentVariables.cxx | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/Source/CPack/cmCPackDocumentMacros.cxx b/Source/CPack/cmCPackDocumentMacros.cxx index 94d5391..ddc75a4 100644 --- a/Source/CPack/cmCPackDocumentMacros.cxx +++ b/Source/CPack/cmCPackDocumentMacros.cxx @@ -1,10 +1,8 @@ #include "cmCPackDocumentMacros.h" void cmCPackDocumentMacros::GetMacrosDocumentation( - std::vector& v) + std::vector& ) { - // avoid compiler warning - (int)v.size(); // Commented-out example of use // // cmDocumentationEntry e("cpack_", diff --git a/Source/CPack/cmCPackDocumentVariables.cxx b/Source/CPack/cmCPackDocumentVariables.cxx index 27d4df2..6327152 100644 --- a/Source/CPack/cmCPackDocumentVariables.cxx +++ b/Source/CPack/cmCPackDocumentVariables.cxx @@ -1,10 +1,8 @@ #include "cmCPackDocumentVariables.h" #include "cmake.h" -void cmCPackDocumentVariables::DefineVariables(cmake* cm) +void cmCPackDocumentVariables::DefineVariables(cmake* ) { - // avoid compiler warning - (void*)cm; // Subsection: variables defined/used by cpack, // which are common to all CPack generators -- cgit v0.12 From cdbd1a9e39e79fe2f29dff3c3a7b9cf9c9fae3cc Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Wed, 1 Feb 2012 21:07:29 +0100 Subject: Fix another compiler warning due to a typo --- Source/cmDocumentation.h | 1 - 1 file changed, 1 deletion(-) diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index fae409f..83a0a09 100644 --- a/Source/cmDocumentation.h +++ b/Source/cmDocumentation.h @@ -156,7 +156,6 @@ public: std::vector& commands, cmake* cm, const char *docSection); - ; private: void SetForm(Form f); void SetDocName(const char* docname); -- cgit v0.12 From 543f1adfa4a8f2f38371512ffcb8c252332acb18 Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Thu, 2 Feb 2012 01:44:21 +0100 Subject: Make the load of script documentation more efficient and dynamic. CPack help will be searched in any CPack*.cmake file located near to CPack.cmake file. The script files is parsed iff the first line begin with ##section. Moreover the documentation section name is specified on the remaining part of the line minus the space immediately following ##section. --- Modules/CPack.cmake | 22 ++++++++++------- Modules/CPackDeb.cmake | 4 ++++ Modules/CPackRPM.cmake | 4 +++- Source/CPack/cpack.cxx | 60 ++++++++++++++++++++++++++++++++++++---------- Source/cmDocumentation.cxx | 20 ++++++++++++++-- 5 files changed, 85 insertions(+), 25 deletions(-) diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake index 1718008..8a44991 100644 --- a/Modules/CPack.cmake +++ b/Modules/CPack.cmake @@ -1,3 +1,6 @@ +##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 @@ -28,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 @@ -47,6 +50,7 @@ # 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 diff --git a/Modules/CPackDeb.cmake b/Modules/CPackDeb.cmake index fc7f992..0916843 100644 --- a/Modules/CPackDeb.cmake +++ b/Modules/CPackDeb.cmake @@ -1,3 +1,6 @@ +##section Variables specific to a CPack generator +##end +##module # - The builtin (binary) CPack Deb generator (Unix only) # CPackDeb may be used to create Deb package using CPack. # CPackDeb is a CPack generator thus it uses the CPACK_XXX variables @@ -11,6 +14,7 @@ # 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 diff --git a/Modules/CPackRPM.cmake b/Modules/CPackRPM.cmake index de06fef..f76e91e 100644 --- a/Modules/CPackRPM.cmake +++ b/Modules/CPackRPM.cmake @@ -1,5 +1,7 @@ -# - The builtin (binary) CPack RPM generator (Unix only) +##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 # used by CPack : http://www.cmake.org/Wiki/CMake:CPackConfiguration diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx index 4117971..25a72fa 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -26,6 +26,8 @@ #include "cmCPackLog.h" #include +#include +#include #include // auto_ptr //---------------------------------------------------------------------------- @@ -527,22 +529,54 @@ int main (int argc, char *argv[]) typedef std::pair docModuleSectionPair_t; typedef std::list docedModulesList_t; - docedModulesList_t docedModList; + docedModulesList_t docedModList; docModuleSectionPair_t docPair; std::string docedFile; - // 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); + cmsys::Glob gl; + std::string findExpr; + std::vector files; + std::string line; + docedFile = globalMF->GetModulesFile("CPack.cmake"); + if (docedFile.length()!=0) + { + findExpr += cmSystemTools::GetFilenamePath(docedFile.c_str()); + findExpr += "/CPack*.cmake"; + if (gl.FindFiles(findExpr)) + { + files = gl.GetFiles(); + for (std::vector::iterator itf=files.begin(); + itf!=files.end();++itf) + { + std::ifstream fin((*itf).c_str()); + if (!fin) continue; + if (cmSystemTools::GetLineFromStream(fin, line)) + { + if (line.find("##section")!=std::string::npos) + { + docPair.first = cmSystemTools::GetFilenameName(*itf); + // 10 is the size of '##section' + 1 + docPair.second = line.substr(10,std::string::npos); + docedModList.push_back(docPair); + } + } + else + { + line.clear(); + } + } + } + else + { + // 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); + } + } // parse the files for documentation. for (docedModulesList_t::iterator it = docedModList.begin(); diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 80f74a6..ed1e5e1 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -768,6 +768,7 @@ int cmDocumentation::GetStructuredDocFromFile( { 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; @@ -795,9 +796,13 @@ int cmDocumentation::GetStructuredDocFromFile( if(line.size() && line[0] == '#') { /* handle structured doc context */ - if (line[1]=='#') + if ((line.size()>=2) && line[1]=='#') { - std::string mkword = line.substr(2,std::string::npos); + /* 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++; @@ -822,6 +827,14 @@ int cmDocumentation::GetStructuredDocFromFile( docContextStack[docCtxIdx]=SDOC_MODULE; newCtx = true; } + else if (mkword=="section") + { + docCtxIdx++; + docContextStack[docCtxIdx]=SDOC_SECTION; + /* drop the rest of the line */ + line.clear(); + newCtx = true; + } else if (mkword.substr(0,3)=="end") { switch (docContextStack[docCtxIdx]) { @@ -841,6 +854,9 @@ int cmDocumentation::GetStructuredDocFromFile( case SDOC_MODULE: /* not implemented */ break; + case SDOC_SECTION: + /* not implemented */ + break; default: /* ignore other cases */ break; -- cgit v0.12 From bafd8a9e79612c260af12f9a42c7e7cddf1f7da3 Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Sat, 4 Feb 2012 12:03:58 +0100 Subject: Example of builtin variable documentation (i.e. only used in C++ source code). --- Source/CPack/cmCPackDocumentVariables.cxx | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/Source/CPack/cmCPackDocumentVariables.cxx b/Source/CPack/cmCPackDocumentVariables.cxx index 6327152..68cde78 100644 --- a/Source/CPack/cmCPackDocumentVariables.cxx +++ b/Source/CPack/cmCPackDocumentVariables.cxx @@ -1,17 +1,25 @@ #include "cmCPackDocumentVariables.h" #include "cmake.h" -void cmCPackDocumentVariables::DefineVariables(cmake* ) +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_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 -- cgit v0.12 From 24fbc28e5f81823661853be0c0acdf2670b3453e Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Sat, 4 Feb 2012 12:06:09 +0100 Subject: Add missing section markup for CPackComponent --- Modules/CPackComponent.cmake | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Modules/CPackComponent.cmake b/Modules/CPackComponent.cmake index a0e0667..016cb8c 100644 --- a/Modules/CPackComponent.cmake +++ b/Modules/CPackComponent.cmake @@ -1,3 +1,6 @@ +##section Variables common to all CPack generators +##end +##module # - Build binary and source package installers # # The CPackComponent module is the module which handles @@ -20,6 +23,7 @@ # 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 -- cgit v0.12 From 02ccb3291bd1053df30600211b0ceefbb7fea00f Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Sat, 4 Feb 2012 12:15:57 +0100 Subject: Create getDocumentedModulesListInDir which may be used in other context. This should makes it easier to use the same "documented module" techniques for CTest, CMake or user module. --- Source/CPack/cpack.cxx | 67 +++++++++------------------------------------- Source/cmDocumentation.cxx | 55 +++++++++++++++++++++++++++++++++++++ Source/cmDocumentation.h | 33 ++++++++++++++++++++++- 3 files changed, 99 insertions(+), 56 deletions(-) diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx index 25a72fa..3182915 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -26,7 +26,6 @@ #include "cmCPackLog.h" #include -#include #include #include // auto_ptr @@ -527,68 +526,26 @@ int main (int argc, char *argv[]) std::vector commands; - typedef std::pair docModuleSectionPair_t; - typedef std::list docedModulesList_t; - docedModulesList_t docedModList; - docModuleSectionPair_t docPair; - std::string docedFile; + std::string docedFile; + std::string docPath; + cmDocumentation::documentedModulesList_t docedModList; - cmsys::Glob gl; - std::string findExpr; - std::vector files; - std::string line; docedFile = globalMF->GetModulesFile("CPack.cmake"); if (docedFile.length()!=0) { - findExpr += cmSystemTools::GetFilenamePath(docedFile.c_str()); - findExpr += "/CPack*.cmake"; - if (gl.FindFiles(findExpr)) - { - files = gl.GetFiles(); - for (std::vector::iterator itf=files.begin(); - itf!=files.end();++itf) - { - std::ifstream fin((*itf).c_str()); - if (!fin) continue; - if (cmSystemTools::GetLineFromStream(fin, line)) - { - if (line.find("##section")!=std::string::npos) - { - docPair.first = cmSystemTools::GetFilenameName(*itf); - // 10 is the size of '##section' + 1 - docPair.second = line.substr(10,std::string::npos); - docedModList.push_back(docPair); - } - } - else - { - line.clear(); - } - } - } - else - { - // 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); - } + docPath = cmSystemTools::GetFilenamePath(docedFile.c_str()); + doc.getDocumentedModulesListInDir(docPath,"CPack*.cmake",docedModList); } // parse the files for documentation. - for (docedModulesList_t::iterator it = docedModList.begin(); - it!= docedModList.end(); ++it) + cmDocumentation::documentedModulesList_t::iterator docedIt; + for (docedIt = docedModList.begin(); + docedIt!= docedModList.end(); ++docedIt) { - docedFile = globalMF->GetModulesFile((it->first).c_str()); - if (docedFile.length()!=0) - { - doc.GetStructuredDocFromFile(docedFile.c_str(), - commands,&cminst,(it->second).c_str()); - } - } + doc.GetStructuredDocFromFile( + (docedIt->first).c_str(), + commands,&cminst,(docedIt->second).c_str()); + } std::map propDocs; cminst.GetPropertiesDocumentation(propDocs); diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index ed1e5e1..dde4953 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -14,6 +14,7 @@ #include "cmSystemTools.h" #include "cmVersion.h" #include +#include //---------------------------------------------------------------------------- @@ -745,6 +746,60 @@ void cmDocumentation::addCPackStandardDocSections() } //---------------------------------------------------------------------------- +int cmDocumentation::getDocumentedModulesListInDir( + std::string path, + std::string globExpr, + documentedModulesList_t& docedModuleList) +{ + cmsys::Glob gl; + std::string findExpr; + std::vector files; + std::string line; + documentedModuleSectionPair_t docPair; + int nbDocumentedModules = 0; + + findExpr = path + "/" + globExpr; + if (gl.FindFiles(findExpr)) + { + files = gl.GetFiles(); + for (std::vector::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.clear(); + } + } + if (nbDocumentedModules>0) + { + return 0; + } + else + { + return 1; + } +} + +//---------------------------------------------------------------------------- static void trim(std::string& s) { std::string::size_type pos = s.find_last_not_of(' '); diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index 83a0a09..00dba1a 100644 --- a/Source/cmDocumentation.h +++ b/Source/cmDocumentation.h @@ -35,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 documentedModuleSectionPair_t; + /** + * A list of documented module(s). + */ + typedef std::list documentedModulesList_t; + // High-level interface for standard documents: /** @@ -133,6 +148,21 @@ public: 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) @@ -140,7 +170,8 @@ public: * ## (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, ##function, ##variable and ##end. + * 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 -- cgit v0.12 From 9002f73f311893be20d8d986de8e5239ed2afce2 Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Mon, 6 Feb 2012 17:20:54 +0100 Subject: Fix non existent std::string::clear on VS6 --- Source/cmDocumentation.cxx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index dde4953..02f69f1 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -786,7 +786,7 @@ int cmDocumentation::getDocumentedModulesListInDir( // No else if no section is found (undocumented module) } // No else cannot read first line (ignore this kind of error) - line.clear(); + line = ""; } } if (nbDocumentedModules>0) @@ -887,7 +887,7 @@ int cmDocumentation::GetStructuredDocFromFile( docCtxIdx++; docContextStack[docCtxIdx]=SDOC_SECTION; /* drop the rest of the line */ - line.clear(); + line = ""; newCtx = true; } else if (mkword.substr(0,3)=="end") -- cgit v0.12 From d4b77eba17e01badc836777dbb0c9ec287f098aa Mon Sep 17 00:00:00 2001 From: Eric NOULARD Date: Tue, 7 Feb 2012 16:59:04 +0100 Subject: Avoid discovering system infos for documentation. Adding some path is enough. --- Source/CPack/cpack.cxx | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx index 3182915..c541610 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -304,30 +304,31 @@ 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 + 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 = -- cgit v0.12