diff --git a/tribits/doc/README.DEPENDENCIES b/tribits/doc/README.DEPENDENCIES deleted file mode 100644 index 894f2b991..000000000 --- a/tribits/doc/README.DEPENDENCIES +++ /dev/null @@ -1,251 +0,0 @@ -################################################################################ -# -# TriBITS Package Dependencies -# -################################################################################ - -Last updated 2014/09/30 - -Here we describe how package dependencies are set up and managed in this the -TriBITS CMake build system. - - --------------------------------------------------------------------------------- -A) Top-level user cache variables --------------------------------------------------------------------------------- - -See the TribitsDevelopersGuide.rst document for the definition of the -variables: - - ${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}:BOOL - - ${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME}:BOOL - - ${PACKAGE_NAME}_ENABLE_TESTS:BOOL - - ${PACKAGE_NAME}_ENABLE_EXAMPLES:BOOL - - ${PROJECT_NAME}_ENABLE_ALL_PACKAGES:BOOL - - ${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES:BOOL - - ${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL - - ${PROJECT_NAME}_ENABLE_TESTS:BOOL - - ${PROJECT_NAME}_ENABLE_EXAMPLES:BOOL - -These variables are defined in the file: - - TribitsGlobalMacros.cmake - -The way that packages are enabled depending on the above user cache variables -is described in the TribitsDevelopersGuide.rst document. - -This dependency logic is executed in the TriBITS file: - - TribitsAdjustPackageEnables.cmake - -There are pretty good unit and regression tests to demonstrate and protect -this functionality in the directory: - - tribits/package_arch/UntiTests/ - - --------------------------------------------------------------------------------- -B) Top-level internal non-cache variables defining direct package dependencies --------------------------------------------------------------------------------- - -The following top-level non-cache variables are defined by each SE package's -Dependencies.cmake file and they are used to define the basic dependencies -that exist between ${PROJECT_NAME} SE packages to support the SE package -enable and disable logic described above. These variables taken together -constitute a bidirectionally navigateable tree data-structure for SE package -and TPL dependencies. - - ${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES - - The list of *direct* SE package dependencies that are required for the - libraries built by ${PACKAGE_NAME}. These should not include indirect - dependencies but it is harmless to list these also. - - ${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES - - The list of *direct* SE package dependencies that are only optional for - the libraries built by ${PACKAGE_NAME}. These should not include indirect - dependencies but it is harmless to list these also. - - ${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES - - The list of *direct* SE package dependencies that are required for the - tests/examples built by ${PACKAGE_NAME}. This list should not contain any - of the packages listed in ${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES. - These should not include indirect dependencies but it is harmless to list - these also. - - ${PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES - - The list of *direct* SE package dependencies that are optional for the - tests/examples built by ${PACKAGE_NAME}. This list should not contain any - of the SE packages listed in ${PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES, - ${PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES, or - ${PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES. These should not include - indirect dependencies but it is harmless to list these also. - -Given the above variables, the following derived variables are then set: - - ${PACKAGE_NAME}_FORWARD_LIB_REQUIRED_DEP_PACKAGES - - For a given SE package ${PACKAGE_NAME}, gives the names of all of the - forward SE packages that list this SE package in their - ${FORWARD_PACKAGE_NAME}_LIB_REQUIRED_DEP_PACKAGES variables. - - ${PACKAGE_NAME}_FORWARD_LIB_OPTIONAL_DEP_PACKAGES - - For a given SE package ${PACKAGE_NAME}, gives the names of all of the - forward SE packages that list this SE package in their - ${FORWARD_PACKAGE_NAME}_LIB_OPTIONAL_DEP_PACKAGES variables. - - ${PACKAGE_NAME}_FORWARD_TEST_REQUIRED_DEP_PACKAGES - - For a given SE package ${PACKAGE_NAME}, gives the names of all of the - forward SE packages that list this SE package in their - ${FORWARD_PACKAGE_NAME}_TEST_REQUIRED_DEP_PACKAGES variables. - - ${PACKAGE_NAME}_FORWARD_TEST_OPTIONAL_DEP_PACKAGES - - For a given SE package ${PACKAGE_NAME}, gives the names of all of the - forward SE packages that list this SE package in their - ${FORWARD_PACKAGE_NAME}_TEST_OPTIONAL_DEP_PACKAGES variables. - -The primary TriBITS file that processes and defines these variables is: - - TribitsAdjustPackageEnables.cmake - -There are pretty good unit and regression tests to demonstrate and protect -this functionality in the directory: - - tribits/package_arch/UntiTests/ - - --------------------------------------------------------------------------------- -C) Top-level internal cache variables defining header and library dependencies --------------------------------------------------------------------------------- - -The following global internal cache variables are used to communicate -the required header directory paths and libraries needed to build and -link against a given package's capabilities. - - ${PACKAGE_NAME}_INCLUDE_DIRS - - Defines a list of include paths needed to find all of the headers needed - to compile client code against this (sub)packages sources and it's - upstream packages and TPL sources. This variable is used whenever - building downstream code including downstream libraries or executables in - the same package, or libraries or executables in downstream packages. - - ${PACKAGE_NAME}_LIBRARY_DIRS - - Defines as list of the link directories needed to find all of the - libraries for this packages and it's upstream packages and TPLs. Adding - these library directories to the CMake link line is unnecessary and would - cause link-line too long errors on some systems. Instead, this list of - library directories is used when creating the ${PACKAGE_NAME}Config.cmake - files. - - ${PACKAGE_NAME}_LIBRARIES - - Defines as list of *only* the libraries associated with the given - (sub)package and does *not* list libraries in upstream packages. Linkages - to upstream packages is taken care of with calls to - TARGET_LINK_LIBRARIES(...) and the dependency management system in CMake - takes care of adding these to various link lines as needed (this is what - CMake does well). However, when a package has no libraries of its own - (which is often the case for packages that have subpackages, for example), - then this list of libraries will contain the libraries to the direct - dependent upstream packages in order to allow the chain of dependencies to - be handled correctly in downstream packages and executables in the same - package. In this case, ${PACKAGE_NAME}_HAS_NATIVE_LIBRARIES will be - false. The primary purpose of this variable is to passe to - TARGET_LINK_LIBRARIES(...) by downstream libraries and executables. - - ${PACKAGE_NAME}_HAS_NATIVE_LIBRARIES - - Will be true if a package has native libraries. Otherwise, it will be - false. This information is used to build export makefiles to avoid - duplicate libraries on the link line. - - ${PACKAGE_NAME}_FULL_ENABLED_DEP_PACKAGES - - Lists out, in order, all of the enabled upstream SE packages that the - given package depends on and support that package is enabled in the given - package. This is only computed if - ${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES=ON. This is needed to - generate the export makefile Makefile.export.${PACKAGE_NAME}. NOTE: This - list does *not* include the package itself. This list is created after - all of the enable/disable logic is applied.. - - ${PARENT_PACKAGE_NAME}_LIB_TARGETS - - Lists all of the library targets for this package only that are as part of - this package added by the TRIBITS_ADD_LIBRARY(...) function. This is used - to define a target called ${PACKAGE_NAME}_libs that is then used by - TRIBITS_CTEST_DRIVER(). If a package has no libraries, then the library - targets for all of the immediate upstream direct dependent packages will - be added. This is needed for the chain of dependencies to work correctly. - Note that subpackages don't have this variable defined for them. - - ${PARENT_PACKAGE_NAME}_ALL_TARGETS - - Lists all of the targets associated with this package. This includes all - libraries and tests added with TRIBITS_ADD_LIBRARY(...) and - TRIBITS_ADD_EXECUTABLE(...). If this package has no targets (no libraries - or executables) this this will have the dependency only on - ${PARENT_PACKAGE_NAME}_libs. Note that subpackages don't have this - variable defined for them. - - --------------------------------------------------------------------------------- -D) Notes on dependency logic --------------------------------------------------------------------------------- - -The logic used to define the intra-package linkage variables is complex due to -a number of factors: - -1) Packages can have libraries or no libraries. - -2) In installation-testing mode, the libraries for a package are read from a -file instead of generated in source. - -3) A library can be a regular package library, or a test-only library, in -which case it will not be listed in ${PACKAGE_NAME}_LIBRARIES. The above -description does not even talk about how test-only libraries are handed within -the system except to say that they are excluded from the package's exported -library dependencies. - -The management and usage of the intra-package linkage variables is spread -across a number of TriBITS *.cmake files but the primary ones are: - - TribitsPackageMacros.cmake - TribitsSubPackageMacros.cmake - TribitsLibraryMacros.cmake - TribitsAddExecutable.cmake - -There are other TriBITS cmake files that also access these variables but these -are the key files. The CMake code in these files all work together in -coordination to set up and use these variables in a way that allows for smooth -compiling and linking of source code for users of the TriBITS system. - -Another file with complex dependency logic related to these variables is: - - TribitsWriteClientExportFiles.cmake - -The TriBITS cmake code in this file servers a very similar role for external -clients and therefore needs to be considered in this setting. - -All of these variations and features makes this a bit of a complex system to -say the least. Also, currently, there is essentially no unit or regression -testing in place for the CMake code in these files that manipulate these -intra-package dependency variables. Because this logic is tied in with -actually building and linking code, there has not been a way set up yet to -allow it to be efficiently tested outside of the actual build. diff --git a/tribits/doc/developers_guide/generate-dev-guide.sh b/tribits/doc/developers_guide/generate-dev-guide.sh deleted file mode 100755 index 20aec6df3..000000000 --- a/tribits/doc/developers_guide/generate-dev-guide.sh +++ /dev/null @@ -1,193 +0,0 @@ -#!/bin/bash - -# This script is used to generate the the TribitsDevelopersGuide.(html,pdf) -# files using a new script in TriBITS for that purpose. You just run it from -# this directory as: -# -# cd -# ./generate-dev-guide.sh -# -# If you want to override what utils are used to generate the files, you can -# pass in, for example: -# -# ./generate-dev-guide.sh \ -# --generate-html=rst2html.py --generate-latex=rst2latex.py -# -# Note that if you are debugging the parsing, you can disable the generation -# of the latex and pdf by setting: -# -# --generate-latex= -# -# This script also automatically extracts detailed TriBITS documentation from -# the *.cmake files using extract_rst_cmake_doc.py (which works kind of like -# doxygen). -# -# To see output from extract_rst_cmake_doc.py just run the script as: -# -# $ env TRIBITS_DEV_GUIDE_EXTRACT_RST_CMAKE_DOC_EXTRA_ARGS=--do-trace \ -# ./generate-dev-guide.sh [other args] -# -# NOTE: If you see rst2html or rst2latex errors for the file -# TribitsDeveloeprsGuilde.rst with line numbers that don't seem to make sense, -# this is likley due to the include of TribitsDetailedMacroFunctionDoc.rst. -# To adjust the line numbers, subtract the line number of the include for -# TribitsDetailedMacroFunctionDoc.rst in TribitsDevelopersGuilde.rst form the -# line number given in the output and that will be the line number in the -# TribitsDevelopersGuilde.rst file. You can then match that up with the -# original text in the *.cmake file that this came from for the given macro or -# function. -# -# NOTE: To skip the extraction of the documentation from the *.cmake files, -# just sent the env TRIBITS_DEV_GUIDE_varaible SKIP_DOCUMENTATION_EXTRACTION -# as: -# -# $ env TRIBITS_DEV_GUIDE_SKIP_DOCUMENTATION_EXTRACTION=1 \ -# ./generate-dev-guilde.sh -# -# That will result in the generated files TribitsMacroFunctionDoc.rst and -# UtilsMacroFunctionDoc.rst being left as is. This would be useful to speed -# up builds (but it is very fast) but is more useful when spell checking and -# editing the documentation. This speeds up the editing process and then the -# updated documentation can be copied back into the *.cmake files of origin. -# -# Enjoy! - -ARGS=$@ - -source ../utils/gen_doc_utils.sh - -function generate_gitdist_dist_help_topic { - help_topic_name=$1 - ../../python_utils/gitdist --dist-help=$help_topic_name &> gitdist-dist-help-$help_topic_name.txt.tmp - update_if_different gitdist-dist-help-$help_topic_name.txt tmp -} - - -if [ "$TRIBITS_DEV_GUIDE_SKIP_DOCUMENTATION_EXTRACTION" == "" ] ; then - - echo - echo "Extracting TriBITS documentation from *.cmake files ..." - echo - ../../python_utils/extract_rst_cmake_doc.py \ - --extract-from=../../core/package_arch/,../../core/utils/,../../ctest_driver/ \ - --rst-file-pairs=TribitsMacroFunctionDocTemplate.rst:TribitsMacroFunctionDoc.rst.tmp,UtilsMacroFunctionDocTemplate.rst:UtilsMacroFunctionDoc.rst.tmp \ - $TRIBITS_DEV_GUIDE_EXTRACT_RST_CMAKE_DOC_EXTRA_ARGS - - update_if_different TribitsMacroFunctionDoc.rst tmp - update_if_different UtilsMacroFunctionDoc.rst tmp - -fi - -if [ "$TRIBITS_DEV_GUIDE_SKIP_OTHER_EXTRACTION" == "" ] ; then - - echo - echo "Generating list of Standard TriBITS TPLs ..." - echo - ls -w 1 ../../core/std_tpls/ &> TribitsStandardTPLsList.txt.tmp - update_if_different TribitsStandardTPLsList.txt tmp - - echo - echo "Generating list of Common TriBITS TPLs ..." - echo - ls -w 1 ../../common_tpls/ &> TribitsCommonTPLsList.txt.tmp - update_if_different TribitsCommonTPLsList.txt tmp - - echo - echo "Generating Directory structure of TribitsHelloWorld ..." - echo - ../../python_utils/tree.py -f -c -x ../../examples/TribitsHelloWorld/ \ - &> TribitsHelloWorldDirAndFiles.txt.tmp - update_if_different TribitsHelloWorldDirAndFiles.txt tmp - - echo - echo "Generating output for 'checkin-test.py --help' ..." - echo - ../../ci_support/checkin-test.py --help &> checkin-test-help.txt.tmp - update_if_different checkin-test-help.txt tmp - - echo - echo "Generating output for 'gitdist --help' and '--dist-help=' ..." - echo - ../../python_utils/gitdist --help &> gitdist-help.txt.tmp - update_if_different gitdist-help.txt tmp - generate_gitdist_dist_help_topic overview - generate_gitdist_dist_help_topic repo-selection-and-setup - generate_gitdist_dist_help_topic dist-repo-status - generate_gitdist_dist_help_topic repo-versions - generate_gitdist_dist_help_topic aliases - generate_gitdist_dist_help_topic default-branch - generate_gitdist_dist_help_topic move-to-base-dir - generate_gitdist_dist_help_topic usage-tips - generate_gitdist_dist_help_topic script-dependencies - generate_gitdist_dist_help_topic all - - echo - echo "Generating output for 'clone_extra_repos.py --help' ..." - echo - ../../ci_support/clone_extra_repos.py --help \ - &> clone_extra_repos-help.txt.tmp - update_if_different clone_extra_repos-help.txt tmp - - echo - echo "Generating output for 'snapshot-dir.py --help' ..." - echo - env SNAPSHOT_DIR_DUMMY_DEFAULTS=1 ../../python_utils/snapshot-dir.py --help \ - &> snapshot-dir-help.txt.tmp - update_if_different snapshot-dir-help.txt tmp - - echo - echo "Generating output for 'is_checkin_tested_commit.py --help' ..." - echo - ../../ci_support/is_checkin_tested_commit.py --help \ - &> is_checkin_tested_commit.txt.tmp - update_if_different is_checkin_tested_commit.txt tmp - - echo - echo "Generating output for 'get-tribits-packages-from-files-list.py --help' ..." - echo - ../../ci_support/get-tribits-packages-from-files-list.py --help \ - &> get-tribits-packages-from-files-list.txt.tmp - update_if_different get-tribits-packages-from-files-list.txt tmp - - echo - echo "Generating output for 'get-tribits-packages-from-last-tests-failed.py --help' ..." - echo - ../../ci_support/get-tribits-packages-from-last-tests-failed.py --help \ - &> get-tribits-packages-from-last-tests-failed.txt.tmp - update_if_different get-tribits-packages-from-last-tests-failed.txt tmp - - echo - echo "Generating output for 'filter-packages-list.py --help' ..." - echo - ../../ci_support/filter-packages-list.py --help \ - &> filter-packages-list.txt.tmp - update_if_different filter-packages-list.txt tmp - - echo - echo "Generating output for 'install_devtools.py --help' ..." - echo - ../../devtools_install/install_devtools.py --help \ - &> install_devtools-help.txt.tmp - update_if_different install_devtools-help.txt tmp - -fi - -if [ -e "../../../README.DIRECTORY_CONTENTS.rst" ] ; then - echo - echo "Copy TriBITS/README.DIRECTORY_CONTENTS.rst to TriBITS.README.DIRECTORY_CONTENTS.rst ..." - echo - cp ../../../README.DIRECTORY_CONTENTS.rst TriBITS.README.DIRECTORY_CONTENTS.rst.tmp -else - echo - echo "TriBITS/README.DIRECTORY_CONTENTS.rst does not exist to copy!" - echo - touch TriBITS.README.DIRECTORY_CONTENTS.rst.tmp -fi -update_if_different TriBITS.README.DIRECTORY_CONTENTS.rst tmp - -generate_git_version_file - -echo -echo "Generating HTML and PDF files ..." -echo -make