From 4809a2bccf03f83728fe1799313cf30cd047a486 Mon Sep 17 00:00:00 2001 From: Joe Frye Date: Fri, 19 May 2017 09:36:16 -0600 Subject: [PATCH 1/9] Initial commit of the basic HelloWolrd tutorial * TribitsTutorialHelloWorld.rst has a nearly complete first draft of a basic tutorial for TriBITS * HelloWorldConfigure.output is a file I want to reference in the rst * generate-tutorial.sh is a copy of the generate-*.py for the developer's guide and has not been modified at all --- .../HelloWorldConfigure.output | 160 +++++++++++++++ .../TribitsTutorialHelloWorld.rst | 194 ++++++++++++++++++ .../doc/tribits_tutorial/generate-tutorial.sh | 170 +++++++++++++++ 3 files changed, 524 insertions(+) create mode 100644 tribits/doc/tribits_tutorial/HelloWorldConfigure.output create mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst create mode 100755 tribits/doc/tribits_tutorial/generate-tutorial.sh diff --git a/tribits/doc/tribits_tutorial/HelloWorldConfigure.output b/tribits/doc/tribits_tutorial/HelloWorldConfigure.output new file mode 100644 index 000000000..f1f950be0 --- /dev/null +++ b/tribits/doc/tribits_tutorial/HelloWorldConfigure.output @@ -0,0 +1,160 @@ + +Configuring TribitsGreetings build directory + +-- PROJECT_SOURCE_DIR='/Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world' +-- PROJECT_BINARY_DIR='/Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/build' +-- TribitsGreetings_TRIBITS_DIR='/Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/cmake/tribits' +-- TriBITS_VERSION_STRING='0.9 (Dev)' +-- CMAKE_VERSION='3.4.1' +-- CMAKE_GENERATOR='Unix Makefiles' +-- CMAKE_HOST_SYSTEM_NAME='Darwin' +-- TribitsGreetings_HOSTNAME='cupojoe' +-- Found PythonInterp: /Users/jfrye/anaconda/bin/python (found suitable version "2.7.12", minimum required is "2.6") +-- PYTHON_EXECUTABLE='/Users/jfrye/anaconda/bin/python' + +Setting up major user options ... + + +Reading list of native packages from /Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/PackagesList.cmake + +-- TribitsGreetings_NUM_PACKAGES='1' + +Reading list of native TPLs from /Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/TPLsList.cmake + +-- TribitsGreetings_NUM_TPLS='0' + +Processing Project, Repository, and Package dependency files and building internal dependencies graph ... + +-- TribitsGreetings_NUM_SE_PACKAGES='1' + +Explicitly enabled packages on input (by user): HelloPackage 1 + +Explicitly enabled SE packages on input (by user): HelloPackage 1 + +Explicitly disabled packages on input (by user or by default): 0 + +Explicitly disabled SE packages on input (by user or by default): 0 + +Explicitly enabled TPLs on input (by user): 0 + +Explicitly disabled TPLs on input (by user or by default): 0 + +Disabling all packages that have a required dependency on disabled TPLs and optional package TPL support based on TPL_ENABLE_=OFF ... + + +Disabling subpackages for hard disables of parent packages due to TribitsGreetings_ENABLE_=OFF ... + + +Disabling forward required SE packages and optional intra-package support that have a dependancy on disabled SE packages TribitsGreetings_ENABLE_=OFF ... + + +Enabling subpackages for hard enables of parent packages due to TribitsGreetings_ENABLE_=ON ... + + +Enabling all required (and optional since TribitsGreetings_ENABLE_ALL_OPTIONAL_PACKAGES=ON) upstream SE packages for current set of enabled packages (TribitsGreetings_ENABLE_SECONDARY_TESTED_CODE=OFF) ... + + +Enabling all optional intra-package enables _ENABLE_ that are not currently disabled if both sets of packages are enabled ... + + +Enabling all remaining required TPLs for current set of enabled packages ... + + +Enabling all optional package TPL support for currently enabled TPLs ... + + +Enabling TPLs based on _ENABLE_=ON if TPL is not explicitly disabled ... + + +Set cache entries for optional packages/TPLs and tests/examples for packages actually enabled ... + + +Enabling all parent packages that have at least one subpackage enabled ... + + +Final set of enabled packages: HelloPackage 1 + +Final set of enabled SE packages: HelloPackage 1 + +Final set of non-enabled packages: 0 + +Final set of non-enabled SE packages: 0 + +Final set of enabled TPLs: 0 + +Final set of non-enabled TPLs: 0 + +Setting up export dependencies for all enabled SE packages ... + + +Probing the environment ... + +-- BUILD_SHARED_LIBS='FALSE' +-- Setting CMAKE_BUILD_TYPE=RELEASE since it was not set ... +-- CMAKE_BUILD_TYPE='RELEASE' +-- The C compiler identification is AppleClang 8.0.0.8000042 +-- Check for working C compiler: /Library/Developer/CommandLineTools/usr/bin/cc +-- Check for working C compiler: /Library/Developer/CommandLineTools/usr/bin/cc -- works +-- Detecting C compiler ABI info +-- Detecting C compiler ABI info - done +-- Detecting C compile features +-- Detecting C compile features - done +-- CMAKE_C_COMPILER_ID='AppleClang' +-- CMAKE_C_COMPILER_VERSION='8.0.0.8000042' +-- The CXX compiler identification is AppleClang 8.0.0.8000042 +-- Check for working CXX compiler: /Library/Developer/CommandLineTools/usr/bin/c++ +-- Check for working CXX compiler: /Library/Developer/CommandLineTools/usr/bin/c++ -- works +-- Detecting CXX compiler ABI info +-- Detecting CXX compiler ABI info - done +-- Detecting CXX compile features +-- Detecting CXX compile features - done +-- CMAKE_CXX_COMPILER_ID='AppleClang' +-- CMAKE_CXX_COMPILER_VERSION='8.0.0.8000042' +-- TribitsGreetings_SET_INSTALL_RPATH='TRUE' +-- CMAKE_INSTALL_RPATH_USE_LINK_PATH='TRUE' +-- Setting default for CMAKE_INSTALL_RPATH pointing to TribitsGreetings_INSTALL_LIB_DIR +-- Setting default CMAKE_MACOSX_RPATH=TRUE +-- CMAKE_MACOSX_RPATH='TRUE' +-- CMAKE_INSTALL_RPATH='/usr/local/lib' +-- Looking for C++ include sys/time.h +-- Looking for C++ include sys/time.h - found +-- Looking for C++ include time.h +-- Looking for C++ include time.h - found +-- Looking for C++ include stdint.h +-- Looking for C++ include stdint.h - found +-- Looking for C++ include inttypes.h +-- Looking for C++ include inttypes.h - found +-- Found Perl: /usr/bin/perl (found version "5.18.2") +-- Performing Test MATH_LIBRARY_IS_SUPPLIED +-- Performing Test MATH_LIBRARY_IS_SUPPLIED - Success +-- Performing Test FINITE_VALUE_HAVE_GLOBAL_ISNAN +-- Performing Test FINITE_VALUE_HAVE_GLOBAL_ISNAN - Success +-- Performing Test FINITE_VALUE_HAVE_STD_ISNAN +-- Performing Test FINITE_VALUE_HAVE_STD_ISNAN - Success +-- Performing Test FINITE_VALUE_HAVE_GLOBAL_ISINF +-- Performing Test FINITE_VALUE_HAVE_GLOBAL_ISINF - Success +-- Performing Test FINITE_VALUE_HAVE_STD_ISINF +-- Performing Test FINITE_VALUE_HAVE_STD_ISINF - Success +-- Could NOT find Doxygen (missing: DOXYGEN_EXECUTABLE) + +Getting information for all enabled TPLs ... + + +Setting up testing support ... + + +Configuring individual enabled TribitsGreetings packages ... + +Processing enabled package: HelloPackage (Libs) + +No ETI support requested by packages. + + +Skipping setup for distribution because TribitsGreetings_ENABLE_CPACK_PACKAGING=OFF + + +Finished configuring TribitsGreetings! + +-- Configuring done +-- Generating done +-- Build files have been written to: /Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/build diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst new file mode 100644 index 000000000..eedf2124a --- /dev/null +++ b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst @@ -0,0 +1,194 @@ +======================================= +TriBITS Hello World Tutorial +======================================= + +:Author: Roscoe A. Bartlett (bartlettra@ornl.gov), Joe Frye (jfrye@sandia.gov) +:Date: |date| +:Version: .. include:: TribitsGitVersion.txt + +.. |date| date:: + + +.. sectnum:: + :depth: 2 + +.. Above, the depth of the TOC is set to just 2 because I don't want the +.. TriBITS function/macro names to have section numbers appearing before them. +.. Also, some of them are long and I don't want them to go off the page of the +.. PDF document. + +.. Sections in this document use the underlines: +.. +.. Level-1 ================== +.. Level-2 ------------------ +.. Level-3 ++++++++++++++++++ +.. Level-4 .................. + +.. contents:: + +The Simplest HelloWorld project +=================================== +This short tutorial will walk you through setting up a basic HelloWorld project +built by TriBITS to intdroduce the basic concepts in TriBits. To begin you +will need cmake and TriBITS installed on your machine. You will also need a +working c and c++ compiler. + +TriBITS projects have a specific structure ie a project is a collection of +packages. For this example we will be creating a project that has just one +package, the "HelloPackage" package. + +Initial Setup +---------------- +First lets create all the directories for our project. We will need a top level +directory for the project which I will call tribits_hello_world. We need a +directory for the "HelloPackage" package. We will also need a directory for the +build which I call "build". Under the hello_package_dir also create the directories +"camke" and "src":: + + tribits_hello_world/ + tribits_hello_wolrd/build + tribits_hello_world/hello_package_dir + tribits_hello_world/hello_package_dir/cmake + tribits_hello_world/hello_package_dir/src + + $ tree + . + └── tribits_hello_world + ├── build + └── hello_package_dir + ├── cmake + └── src + +Create a TriBITS package +------------------------- +The most basic TriBITS package needs to have 3 files. +* a top level CMakeLists file +* a source file +* a file that track package dependencies + +First lets create the source file which is the classic HelloWorld.cpp. Just +copy this to HelloWorld.cpp in the src directory:: + + #include + + int main() + { + std::cout << "Hello World!\n"; + return 0; + + } + +Second lets create the package dependencies file which should be placed in the +cmake directory. Copy the below text into a file called Dependencies.cmake:: + + TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() + +In this case the package we are creating has no dependencies but we still need +this file. The lack of arguments to the TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() call +reflects that this package does not have dependencies. The last and most interesting +file we will create in the package directory is the CMakeLists.txt file. Copy the following +into CMakeLists.txt:: + + TRIBITS_PACKAGE(HelloPackage) + TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) + TRIBITS_PACKAGE_POSTPROCESS() + + +**TRIBITS_PACKAGE(HelloPackage)** Sets this up a TriBITS package with the name "HelloPackage" + +**TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE)** tells +TriBITS that we want to build an executable named "Hello-Executable-Name" from the source file src/HelloWorld.cpp. +NOEXEPREFIX and INSTALLABLE are options to TRIBITS_ADD_EXECUTABLE() that I will not go into right now. + +**TRIBITS_PACKAGE_POSTPROCESS()** Must be at the end of any packages top level CMakeLists file + +**Say some stuff about Tribits packages (here) or at teh top of this section** + +Create a Tribits Project +------------------------- +Recall that a TriBITS project is made up of TriBITS packages. We have just defeined a package now we will create +a project that consists of just that one package. In order to do this we are going to create 4 files in the top +level directory and they are named: +* CMakeLists.txt +* PackageList.cmake +* ProjectName.camke +* TPLsList.cmake + +**TPLsList.camke** this file tells Tribits ablout TPLs needed for the project. In this case, the package does not +depend on any TPLs so this file will be very simple. It should contain just the following single line:: + + TRIBITS_REPOSITORY_DEFINE_TPLS() + +**ProjectName.camke** this file sets the name of the project. Some other options can be specified in this file but we +will just set the project name. It should contain the following:: + + SET(PROJECT_NAME TribitsHelloWorld) + +**PackageList.cmake** defeines which packages are in the project. We will just need to tell it the name and location +of our one package:: + + TRIBITS_REPOSITORY_DEFINE_PACKAGES( + HelloPackage hello_package_dir PT + ) + +**CMakeLists.txt** This is the most interesting file in this example. Here we will set a minimum cmake version, load some +options, and tell cmake that this is a Tribits project. The CMakeLists.txt file should have the following contents:: + + # To be safe, define your minimum CMake version + CMAKE_MINIMUM_REQUIRED(VERSION 2.8.11 FATAL_ERROR) + + # Make CMake set WIN32 with CYGWIN for older CMake versions + SET(CMAKE_LEGACY_CYGWIN_WIN32 1 CACHE BOOL "" FORCE) + + # Get PROJECT_NAME (must be in file for other parts of system) + INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake) + + # CMake requires that you declare the CMake project in the top-level file + PROJECT(${PROJECT_NAME} NONE) + + # This needs to be set to the path to the installation of TriBITS on your machine + SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).") + + # Include the TriBITS system + INCLUDE("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake") + + # MPI and Fortran are enabled by defualt, turn them off for this project + SET(TPL_ENABLE_MPI OFF CACHE BOOL "" FORCE) + # Turn off Fortran support by default + SET(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF) + + # Only one package in this simple project so just enable it :-) + SET(${PROJECT_NAME}_ENABLE_HelloPackage ON CACHE BOOL "" FORCE) + + # Do all of the processing for this Tribits project + TRIBITS_PROJECT() + +**SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).")** +Make sure you set this to your Tribits Installation path it may not be the same as +this path. Now you should have a directory structure that looks like this:: + + . + ├── CMakeLists.txt + ├── PackagesList.cmake + ├── ProjectName.cmake + ├── TPLsList.cmake + ├── build + └── hello_package_dir + ├── CMakeLists.txt + ├── cmake + │ └── Dependencies.cmake + └── src + └── HelloWorld.cpp + + +Build your TriBITS project +--------------------------- +Go to the build directory and type:: + cmake ../ + +You should see something very similar to:: + +..literalinclude:: HelloWorldConfigure.output + diff --git a/tribits/doc/tribits_tutorial/generate-tutorial.sh b/tribits/doc/tribits_tutorial/generate-tutorial.sh new file mode 100755 index 000000000..2c5982f9f --- /dev/null +++ b/tribits/doc/tribits_tutorial/generate-tutorial.sh @@ -0,0 +1,170 @@ +#!/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 exmaple: +# +# ./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 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 '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 From 94707d07c14e6d9f2cad6b35c2ad5d53c7024416 Mon Sep 17 00:00:00 2001 From: Joe Frye Date: Fri, 19 May 2017 09:36:16 -0600 Subject: [PATCH 2/9] Initial commit of the basic HelloWolrd tutorial * TribitsTutorialHelloWorld.rst has a nearly complete first draft of a basic tutorial for TriBITS * HelloWorldConfigure.output is a file I want to reference in the rst * generate-tutorial.sh is a copy of the generate-*.py for the developer's guide and has not been modified at all --- .../HelloWorldConfigure.output | 160 +++++++++++++++ .../TribitsTutorialHelloWorld.rst | 194 ++++++++++++++++++ .../doc/tribits_tutorial/generate-tutorial.sh | 170 +++++++++++++++ 3 files changed, 524 insertions(+) create mode 100644 tribits/doc/tribits_tutorial/HelloWorldConfigure.output create mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst create mode 100755 tribits/doc/tribits_tutorial/generate-tutorial.sh diff --git a/tribits/doc/tribits_tutorial/HelloWorldConfigure.output b/tribits/doc/tribits_tutorial/HelloWorldConfigure.output new file mode 100644 index 000000000..f1f950be0 --- /dev/null +++ b/tribits/doc/tribits_tutorial/HelloWorldConfigure.output @@ -0,0 +1,160 @@ + +Configuring TribitsGreetings build directory + +-- PROJECT_SOURCE_DIR='/Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world' +-- PROJECT_BINARY_DIR='/Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/build' +-- TribitsGreetings_TRIBITS_DIR='/Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/cmake/tribits' +-- TriBITS_VERSION_STRING='0.9 (Dev)' +-- CMAKE_VERSION='3.4.1' +-- CMAKE_GENERATOR='Unix Makefiles' +-- CMAKE_HOST_SYSTEM_NAME='Darwin' +-- TribitsGreetings_HOSTNAME='cupojoe' +-- Found PythonInterp: /Users/jfrye/anaconda/bin/python (found suitable version "2.7.12", minimum required is "2.6") +-- PYTHON_EXECUTABLE='/Users/jfrye/anaconda/bin/python' + +Setting up major user options ... + + +Reading list of native packages from /Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/PackagesList.cmake + +-- TribitsGreetings_NUM_PACKAGES='1' + +Reading list of native TPLs from /Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/TPLsList.cmake + +-- TribitsGreetings_NUM_TPLS='0' + +Processing Project, Repository, and Package dependency files and building internal dependencies graph ... + +-- TribitsGreetings_NUM_SE_PACKAGES='1' + +Explicitly enabled packages on input (by user): HelloPackage 1 + +Explicitly enabled SE packages on input (by user): HelloPackage 1 + +Explicitly disabled packages on input (by user or by default): 0 + +Explicitly disabled SE packages on input (by user or by default): 0 + +Explicitly enabled TPLs on input (by user): 0 + +Explicitly disabled TPLs on input (by user or by default): 0 + +Disabling all packages that have a required dependency on disabled TPLs and optional package TPL support based on TPL_ENABLE_=OFF ... + + +Disabling subpackages for hard disables of parent packages due to TribitsGreetings_ENABLE_=OFF ... + + +Disabling forward required SE packages and optional intra-package support that have a dependancy on disabled SE packages TribitsGreetings_ENABLE_=OFF ... + + +Enabling subpackages for hard enables of parent packages due to TribitsGreetings_ENABLE_=ON ... + + +Enabling all required (and optional since TribitsGreetings_ENABLE_ALL_OPTIONAL_PACKAGES=ON) upstream SE packages for current set of enabled packages (TribitsGreetings_ENABLE_SECONDARY_TESTED_CODE=OFF) ... + + +Enabling all optional intra-package enables _ENABLE_ that are not currently disabled if both sets of packages are enabled ... + + +Enabling all remaining required TPLs for current set of enabled packages ... + + +Enabling all optional package TPL support for currently enabled TPLs ... + + +Enabling TPLs based on _ENABLE_=ON if TPL is not explicitly disabled ... + + +Set cache entries for optional packages/TPLs and tests/examples for packages actually enabled ... + + +Enabling all parent packages that have at least one subpackage enabled ... + + +Final set of enabled packages: HelloPackage 1 + +Final set of enabled SE packages: HelloPackage 1 + +Final set of non-enabled packages: 0 + +Final set of non-enabled SE packages: 0 + +Final set of enabled TPLs: 0 + +Final set of non-enabled TPLs: 0 + +Setting up export dependencies for all enabled SE packages ... + + +Probing the environment ... + +-- BUILD_SHARED_LIBS='FALSE' +-- Setting CMAKE_BUILD_TYPE=RELEASE since it was not set ... +-- CMAKE_BUILD_TYPE='RELEASE' +-- The C compiler identification is AppleClang 8.0.0.8000042 +-- Check for working C compiler: /Library/Developer/CommandLineTools/usr/bin/cc +-- Check for working C compiler: /Library/Developer/CommandLineTools/usr/bin/cc -- works +-- Detecting C compiler ABI info +-- Detecting C compiler ABI info - done +-- Detecting C compile features +-- Detecting C compile features - done +-- CMAKE_C_COMPILER_ID='AppleClang' +-- CMAKE_C_COMPILER_VERSION='8.0.0.8000042' +-- The CXX compiler identification is AppleClang 8.0.0.8000042 +-- Check for working CXX compiler: /Library/Developer/CommandLineTools/usr/bin/c++ +-- Check for working CXX compiler: /Library/Developer/CommandLineTools/usr/bin/c++ -- works +-- Detecting CXX compiler ABI info +-- Detecting CXX compiler ABI info - done +-- Detecting CXX compile features +-- Detecting CXX compile features - done +-- CMAKE_CXX_COMPILER_ID='AppleClang' +-- CMAKE_CXX_COMPILER_VERSION='8.0.0.8000042' +-- TribitsGreetings_SET_INSTALL_RPATH='TRUE' +-- CMAKE_INSTALL_RPATH_USE_LINK_PATH='TRUE' +-- Setting default for CMAKE_INSTALL_RPATH pointing to TribitsGreetings_INSTALL_LIB_DIR +-- Setting default CMAKE_MACOSX_RPATH=TRUE +-- CMAKE_MACOSX_RPATH='TRUE' +-- CMAKE_INSTALL_RPATH='/usr/local/lib' +-- Looking for C++ include sys/time.h +-- Looking for C++ include sys/time.h - found +-- Looking for C++ include time.h +-- Looking for C++ include time.h - found +-- Looking for C++ include stdint.h +-- Looking for C++ include stdint.h - found +-- Looking for C++ include inttypes.h +-- Looking for C++ include inttypes.h - found +-- Found Perl: /usr/bin/perl (found version "5.18.2") +-- Performing Test MATH_LIBRARY_IS_SUPPLIED +-- Performing Test MATH_LIBRARY_IS_SUPPLIED - Success +-- Performing Test FINITE_VALUE_HAVE_GLOBAL_ISNAN +-- Performing Test FINITE_VALUE_HAVE_GLOBAL_ISNAN - Success +-- Performing Test FINITE_VALUE_HAVE_STD_ISNAN +-- Performing Test FINITE_VALUE_HAVE_STD_ISNAN - Success +-- Performing Test FINITE_VALUE_HAVE_GLOBAL_ISINF +-- Performing Test FINITE_VALUE_HAVE_GLOBAL_ISINF - Success +-- Performing Test FINITE_VALUE_HAVE_STD_ISINF +-- Performing Test FINITE_VALUE_HAVE_STD_ISINF - Success +-- Could NOT find Doxygen (missing: DOXYGEN_EXECUTABLE) + +Getting information for all enabled TPLs ... + + +Setting up testing support ... + + +Configuring individual enabled TribitsGreetings packages ... + +Processing enabled package: HelloPackage (Libs) + +No ETI support requested by packages. + + +Skipping setup for distribution because TribitsGreetings_ENABLE_CPACK_PACKAGING=OFF + + +Finished configuring TribitsGreetings! + +-- Configuring done +-- Generating done +-- Build files have been written to: /Users/jfrye/learn-cmake-tribits/trash/tribits_hello_world/build diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst new file mode 100644 index 000000000..eedf2124a --- /dev/null +++ b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst @@ -0,0 +1,194 @@ +======================================= +TriBITS Hello World Tutorial +======================================= + +:Author: Roscoe A. Bartlett (bartlettra@ornl.gov), Joe Frye (jfrye@sandia.gov) +:Date: |date| +:Version: .. include:: TribitsGitVersion.txt + +.. |date| date:: + + +.. sectnum:: + :depth: 2 + +.. Above, the depth of the TOC is set to just 2 because I don't want the +.. TriBITS function/macro names to have section numbers appearing before them. +.. Also, some of them are long and I don't want them to go off the page of the +.. PDF document. + +.. Sections in this document use the underlines: +.. +.. Level-1 ================== +.. Level-2 ------------------ +.. Level-3 ++++++++++++++++++ +.. Level-4 .................. + +.. contents:: + +The Simplest HelloWorld project +=================================== +This short tutorial will walk you through setting up a basic HelloWorld project +built by TriBITS to intdroduce the basic concepts in TriBits. To begin you +will need cmake and TriBITS installed on your machine. You will also need a +working c and c++ compiler. + +TriBITS projects have a specific structure ie a project is a collection of +packages. For this example we will be creating a project that has just one +package, the "HelloPackage" package. + +Initial Setup +---------------- +First lets create all the directories for our project. We will need a top level +directory for the project which I will call tribits_hello_world. We need a +directory for the "HelloPackage" package. We will also need a directory for the +build which I call "build". Under the hello_package_dir also create the directories +"camke" and "src":: + + tribits_hello_world/ + tribits_hello_wolrd/build + tribits_hello_world/hello_package_dir + tribits_hello_world/hello_package_dir/cmake + tribits_hello_world/hello_package_dir/src + + $ tree + . + └── tribits_hello_world + ├── build + └── hello_package_dir + ├── cmake + └── src + +Create a TriBITS package +------------------------- +The most basic TriBITS package needs to have 3 files. +* a top level CMakeLists file +* a source file +* a file that track package dependencies + +First lets create the source file which is the classic HelloWorld.cpp. Just +copy this to HelloWorld.cpp in the src directory:: + + #include + + int main() + { + std::cout << "Hello World!\n"; + return 0; + + } + +Second lets create the package dependencies file which should be placed in the +cmake directory. Copy the below text into a file called Dependencies.cmake:: + + TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() + +In this case the package we are creating has no dependencies but we still need +this file. The lack of arguments to the TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() call +reflects that this package does not have dependencies. The last and most interesting +file we will create in the package directory is the CMakeLists.txt file. Copy the following +into CMakeLists.txt:: + + TRIBITS_PACKAGE(HelloPackage) + TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) + TRIBITS_PACKAGE_POSTPROCESS() + + +**TRIBITS_PACKAGE(HelloPackage)** Sets this up a TriBITS package with the name "HelloPackage" + +**TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE)** tells +TriBITS that we want to build an executable named "Hello-Executable-Name" from the source file src/HelloWorld.cpp. +NOEXEPREFIX and INSTALLABLE are options to TRIBITS_ADD_EXECUTABLE() that I will not go into right now. + +**TRIBITS_PACKAGE_POSTPROCESS()** Must be at the end of any packages top level CMakeLists file + +**Say some stuff about Tribits packages (here) or at teh top of this section** + +Create a Tribits Project +------------------------- +Recall that a TriBITS project is made up of TriBITS packages. We have just defeined a package now we will create +a project that consists of just that one package. In order to do this we are going to create 4 files in the top +level directory and they are named: +* CMakeLists.txt +* PackageList.cmake +* ProjectName.camke +* TPLsList.cmake + +**TPLsList.camke** this file tells Tribits ablout TPLs needed for the project. In this case, the package does not +depend on any TPLs so this file will be very simple. It should contain just the following single line:: + + TRIBITS_REPOSITORY_DEFINE_TPLS() + +**ProjectName.camke** this file sets the name of the project. Some other options can be specified in this file but we +will just set the project name. It should contain the following:: + + SET(PROJECT_NAME TribitsHelloWorld) + +**PackageList.cmake** defeines which packages are in the project. We will just need to tell it the name and location +of our one package:: + + TRIBITS_REPOSITORY_DEFINE_PACKAGES( + HelloPackage hello_package_dir PT + ) + +**CMakeLists.txt** This is the most interesting file in this example. Here we will set a minimum cmake version, load some +options, and tell cmake that this is a Tribits project. The CMakeLists.txt file should have the following contents:: + + # To be safe, define your minimum CMake version + CMAKE_MINIMUM_REQUIRED(VERSION 2.8.11 FATAL_ERROR) + + # Make CMake set WIN32 with CYGWIN for older CMake versions + SET(CMAKE_LEGACY_CYGWIN_WIN32 1 CACHE BOOL "" FORCE) + + # Get PROJECT_NAME (must be in file for other parts of system) + INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake) + + # CMake requires that you declare the CMake project in the top-level file + PROJECT(${PROJECT_NAME} NONE) + + # This needs to be set to the path to the installation of TriBITS on your machine + SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).") + + # Include the TriBITS system + INCLUDE("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake") + + # MPI and Fortran are enabled by defualt, turn them off for this project + SET(TPL_ENABLE_MPI OFF CACHE BOOL "" FORCE) + # Turn off Fortran support by default + SET(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF) + + # Only one package in this simple project so just enable it :-) + SET(${PROJECT_NAME}_ENABLE_HelloPackage ON CACHE BOOL "" FORCE) + + # Do all of the processing for this Tribits project + TRIBITS_PROJECT() + +**SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).")** +Make sure you set this to your Tribits Installation path it may not be the same as +this path. Now you should have a directory structure that looks like this:: + + . + ├── CMakeLists.txt + ├── PackagesList.cmake + ├── ProjectName.cmake + ├── TPLsList.cmake + ├── build + └── hello_package_dir + ├── CMakeLists.txt + ├── cmake + │ └── Dependencies.cmake + └── src + └── HelloWorld.cpp + + +Build your TriBITS project +--------------------------- +Go to the build directory and type:: + cmake ../ + +You should see something very similar to:: + +..literalinclude:: HelloWorldConfigure.output + diff --git a/tribits/doc/tribits_tutorial/generate-tutorial.sh b/tribits/doc/tribits_tutorial/generate-tutorial.sh new file mode 100755 index 000000000..2c5982f9f --- /dev/null +++ b/tribits/doc/tribits_tutorial/generate-tutorial.sh @@ -0,0 +1,170 @@ +#!/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 exmaple: +# +# ./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 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 '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 From a05fd6033c8ca1f04641964e2b4f3be1e4c3e108 Mon Sep 17 00:00:00 2001 From: Joe Frye Date: Mon, 22 May 2017 13:06:36 -0600 Subject: [PATCH 3/9] Added more to the Tribits helllo world tutorial document --- tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst index eedf2124a..15940ec1b 100644 --- a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst +++ b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst @@ -192,3 +192,6 @@ You should see something very similar to:: ..literalinclude:: HelloWorldConfigure.output +Now type:: + make + From 8c3b6c330bd246630e8357d85ae09a18ad0f1d31 Mon Sep 17 00:00:00 2001 From: Joe Frye Date: Tue, 6 Jun 2017 13:38:38 -0600 Subject: [PATCH 4/9] more content for the first tutorial --- .../TribitsTutorialHelloWorld.rst | 144 +++++++++++++++++- 1 file changed, 141 insertions(+), 3 deletions(-) diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst index 15940ec1b..aa9e5ac3f 100644 --- a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst +++ b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst @@ -29,7 +29,7 @@ TriBITS Hello World Tutorial The Simplest HelloWorld project =================================== This short tutorial will walk you through setting up a basic HelloWorld project -built by TriBITS to intdroduce the basic concepts in TriBits. To begin you +built by TriBITS to intdroduce the basic concepts in TriBITS. To begin you will need cmake and TriBITS installed on your machine. You will also need a working c and c++ compiler. @@ -185,13 +185,151 @@ this path. Now you should have a directory structure that looks like this:: Build your TriBITS project --------------------------- -Go to the build directory and type:: +Go to the build directory and type the following to configure your project:: cmake ../ You should see something very similar to:: ..literalinclude:: HelloWorldConfigure.output -Now type:: +The configure step will have created several files inside your build directory, most notably it will have created nessesary make files to +actually build your project. The other file I will mention here is the CMakeCache.txt which stores information about how the project was +configured. + +To build your project just type:: + make + +you should see:: + [ 50%] Building CXX object hello_package_dir/CMakeFiles/Hello-Executable-Name.dir/src/HelloWorld.cpp.o + [100%] Linking CXX executable Hello-Executable-Name.exe + [100%] Built target Hello-Executable-Name + +now in build/hello_package_dir you will see an executable named "Hello-Executable-Name" and if you run that executable you will see:: + $ ./hello_package_dir/Hello-Executable-Name.exe + Hello World! + + +Adding other targets +=============================== + +Types of targets +----------------- +Previously we had just one source file and we compiled it into one executable. In addition to executables we may also want to create other +targets such as libraries abd tests. In the hello_package_dir/src directory create the following files: + +hello_world_main.cpp:: + #include + #include "hello_world_lib.hpp" + int main() { + std::cout << HelloWorld::getHelloWorld() << "\n"; + return 0; + } + +hello_world_lib.hpp:: + #include + + namespace HelloWorld { std::string getHelloWorld(); } + + +hello_world_lib.cpp:: + #include "hello_world_lib.hpp" + std::string HelloWorld::getHelloWorld() + { return "Hello World!"; } + +hello_world_unit_tests.cpp:: + #include + #include "hello_world_lib.hpp" + + int main() { + + bool success = true; + + const std::string rtn = HelloWorld::getHelloWorld(); + std::cout << "HelloWorld::getHelloWorld() = '"< Date: Wed, 14 Jun 2017 15:28:46 -0600 Subject: [PATCH 5/9] squash - commit of WIP on tutorial documents --- .../TribitsTutorialHelloWorld_0.rst | 361 ++++++++++++++++++ .../TribitsTutorialHelloWorld_1.rst | 48 +++ 2 files changed, 409 insertions(+) create mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.rst create mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_1.rst diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.rst b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.rst new file mode 100644 index 000000000..7a7383e1d --- /dev/null +++ b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.rst @@ -0,0 +1,361 @@ +======================================= +TriBITS Hello World Tutorial +======================================= + +:Author: Roscoe A. Bartlett (bartlettra@ornl.gov), Joe Frye (jfrye@sandia.gov) +:Date: |date| +:Version: .. include:: TribitsGitVersion.txt + +.. |date| date:: + + +.. sectnum:: + :depth: 2 + +.. Above, the depth of the TOC is set to just 2 because I don't want the +.. TriBITS function/macro names to have section numbers appearing before them. +.. Also, some of them are long and I don't want them to go off the page of the +.. PDF document. + +.. Sections in this document use the underlines: +.. +.. Level-1 ================== +.. Level-2 ------------------ +.. Level-3 ++++++++++++++++++ +.. Level-4 .................. + +.. contents:: + +The Simplest HelloWorld project +=================================== +This short tutorial will walk you through setting up a basic HelloWorld project +built by TriBITS to intdroduce the basic concepts in TriBITS. To begin you +will need cmake and TriBITS installed on your machine. You will also need a +working c and c++ compiler. + +TriBITS projects have a specific structure ie a project is a collection of +packages. For this example we will be creating a project that has just one +package, the "HelloPackage" package. + +Initial Setup +---------------- +First lets create all the directories for our project. We will need a top level +directory for the project which I will call tribits_hello_world. We need a +directory for the "HelloPackage" package. We will also need a directory for the +build which I call "build". Under the hello_package_dir also create the directories +"camke" and "src":: + + tribits_hello_world/ + tribits_hello_wolrd/build + tribits_hello_world/hello_package_dir + tribits_hello_world/hello_package_dir/cmake + tribits_hello_world/hello_package_dir/src + + $ tree + . + └── tribits_hello_world + ├── build + └── hello_package_dir + ├── cmake + └── src + +Create a TriBITS package +------------------------- +The most basic TriBITS package needs to have 3 files. +* a top level CMakeLists file +* a source file +* a file that track package dependencies + +First lets create the source file which is the classic HelloWorld.cpp. Just +copy this to HelloWorld.cpp in the src directory:: + + #include + + int main() + { + std::cout << "Hello World!\n"; + return 0; + + } + +Second lets create the package dependencies file which should be placed in the +cmake directory. Copy the below text into a file called Dependencies.cmake:: + + TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() + +In this case the package we are creating has no dependencies but we still need +this file. The lack of arguments to the TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() call +reflects that this package does not have dependencies. The last and most interesting +file we will create in the package directory is the CMakeLists.txt file. Copy the following +into CMakeLists.txt:: + + TRIBITS_PACKAGE(HelloPackage) + TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) + TRIBITS_PACKAGE_POSTPROCESS() + + +**TRIBITS_PACKAGE(HelloPackage)** Sets this up a TriBITS package with the name "HelloPackage" + +**TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE)** tells +TriBITS that we want to build an executable named "Hello-Executable-Name" from the source file src/HelloWorld.cpp. +NOEXEPREFIX and INSTALLABLE are options to TRIBITS_ADD_EXECUTABLE() that I will not go into right now. + +**TRIBITS_PACKAGE_POSTPROCESS()** Must be at the end of any packages top level CMakeLists file + +**Say some stuff about Tribits packages (here) or at teh top of this section** + +Create a Tribits Project +------------------------- +Recall that a TriBITS project is made up of TriBITS packages. We have just defeined a package now we will create +a project that consists of just that one package. In order to do this we are going to create 4 files in the top +level directory and they are named: +* CMakeLists.txt +* PackageList.cmake +* ProjectName.camke +* TPLsList.cmake + +**TPLsList.camke** this file tells Tribits ablout TPLs needed for the project. In this case, the package does not +depend on any TPLs so this file will be very simple. It should contain just the following single line:: + + TRIBITS_REPOSITORY_DEFINE_TPLS() + +**ProjectName.camke** this file sets the name of the project. Some other options can be specified in this file but we +will just set the project name. It should contain the following:: + + SET(PROJECT_NAME TribitsHelloWorld) + +**PackageList.cmake** defeines which packages are in the project. We will just need to tell it the name and location +of our one package:: + + TRIBITS_REPOSITORY_DEFINE_PACKAGES( + HelloPackage hello_package_dir PT + ) + +**CMakeLists.txt** This is the most interesting file in this example. Here we will set a minimum cmake version, load some +options, and tell cmake that this is a Tribits project. The CMakeLists.txt file should have the following contents:: + + # To be safe, define your minimum CMake version + CMAKE_MINIMUM_REQUIRED(VERSION 2.8.11 FATAL_ERROR) + + # Make CMake set WIN32 with CYGWIN for older CMake versions + SET(CMAKE_LEGACY_CYGWIN_WIN32 1 CACHE BOOL "" FORCE) + + # Get PROJECT_NAME (must be in file for other parts of system) + INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake) + + # CMake requires that you declare the CMake project in the top-level file + PROJECT(${PROJECT_NAME} NONE) + + # This needs to be set to the path to the installation of TriBITS on your machine + SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).") + + # Include the TriBITS system + INCLUDE("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake") + + # MPI and Fortran are enabled by defualt, turn them off for this project + SET(TPL_ENABLE_MPI OFF CACHE BOOL "" FORCE) + # Turn off Fortran support by default + SET(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF) + + # Only one package in this simple project so just enable it :-) + SET(${PROJECT_NAME}_ENABLE_HelloPackage ON CACHE BOOL "" FORCE) + + # Do all of the processing for this Tribits project + TRIBITS_PROJECT() + +**SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).")** +Make sure you set this to your Tribits Installation path it may not be the same as +this path. Now you should have a directory structure that looks like this:: + + . + ├── CMakeLists.txt + ├── PackagesList.cmake + ├── ProjectName.cmake + ├── TPLsList.cmake + ├── build + └── hello_package_dir + ├── CMakeLists.txt + ├── cmake + │ └── Dependencies.cmake + └── src + └── HelloWorld.cpp + + +Build your TriBITS project +--------------------------- +Go to the build directory and type the following to configure your project:: + cmake ../ + +You should see something very similar to:: + +..literalinclude:: HelloWorldConfigure.output + +The configure step will have created several files inside your build directory, most notably it will have created nessesary make files to +actually build your project. The other file I will mention here is the CMakeCache.txt which stores information about how the project was +configured. + +To build your project just type:: + make + +you should see:: + [ 50%] Building CXX object hello_package_dir/CMakeFiles/Hello-Executable-Name.dir/src/HelloWorld.cpp.o + [100%] Linking CXX executable Hello-Executable-Name.exe + [100%] Built target Hello-Executable-Name + +now in build/hello_package_dir you will see an executable named "Hello-Executable-Name" and if you run that executable you will see:: + $ ./hello_package_dir/Hello-Executable-Name.exe + Hello World! + + +Adding other targets +=============================== + +Types of targets +----------------- +Previously we had just one source file and we compiled it into one executable. In addition to executables we may also want to create other +targets such as libraries abd tests. In the hello_package_dir/src directory create the following files: + +hello_world_main.cpp:: + #include + #include "hello_world_lib.hpp" + int main() { + std::cout << HelloWorld::getHelloWorld() << "\n"; + return 0; + } + +hello_world_lib.hpp:: + #include + + namespace HelloWorld { std::string getHelloWorld(); } + + +hello_world_lib.cpp:: + #include "hello_world_lib.hpp" + std::string HelloWorld::getHelloWorld() + { return "Hello World!"; } + +hello_world_unit_tests.cpp:: + #include + #include "hello_world_lib.hpp" + + int main() { + + bool success = true; + + const std::string rtn = HelloWorld::getHelloWorld(); + std::cout << "HelloWorld::getHelloWorld() = '"< Date: Wed, 14 Jun 2017 15:30:05 -0600 Subject: [PATCH 6/9] squish - remove file that was renamed and split into 2 files --- .../TribitsTutorialHelloWorld.rst | 335 ------------------ 1 file changed, 335 deletions(-) delete mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst deleted file mode 100644 index aa9e5ac3f..000000000 --- a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst +++ /dev/null @@ -1,335 +0,0 @@ -======================================= -TriBITS Hello World Tutorial -======================================= - -:Author: Roscoe A. Bartlett (bartlettra@ornl.gov), Joe Frye (jfrye@sandia.gov) -:Date: |date| -:Version: .. include:: TribitsGitVersion.txt - -.. |date| date:: - - -.. sectnum:: - :depth: 2 - -.. Above, the depth of the TOC is set to just 2 because I don't want the -.. TriBITS function/macro names to have section numbers appearing before them. -.. Also, some of them are long and I don't want them to go off the page of the -.. PDF document. - -.. Sections in this document use the underlines: -.. -.. Level-1 ================== -.. Level-2 ------------------ -.. Level-3 ++++++++++++++++++ -.. Level-4 .................. - -.. contents:: - -The Simplest HelloWorld project -=================================== -This short tutorial will walk you through setting up a basic HelloWorld project -built by TriBITS to intdroduce the basic concepts in TriBITS. To begin you -will need cmake and TriBITS installed on your machine. You will also need a -working c and c++ compiler. - -TriBITS projects have a specific structure ie a project is a collection of -packages. For this example we will be creating a project that has just one -package, the "HelloPackage" package. - -Initial Setup ----------------- -First lets create all the directories for our project. We will need a top level -directory for the project which I will call tribits_hello_world. We need a -directory for the "HelloPackage" package. We will also need a directory for the -build which I call "build". Under the hello_package_dir also create the directories -"camke" and "src":: - - tribits_hello_world/ - tribits_hello_wolrd/build - tribits_hello_world/hello_package_dir - tribits_hello_world/hello_package_dir/cmake - tribits_hello_world/hello_package_dir/src - - $ tree - . - └── tribits_hello_world - ├── build - └── hello_package_dir - ├── cmake - └── src - -Create a TriBITS package -------------------------- -The most basic TriBITS package needs to have 3 files. -* a top level CMakeLists file -* a source file -* a file that track package dependencies - -First lets create the source file which is the classic HelloWorld.cpp. Just -copy this to HelloWorld.cpp in the src directory:: - - #include - - int main() - { - std::cout << "Hello World!\n"; - return 0; - - } - -Second lets create the package dependencies file which should be placed in the -cmake directory. Copy the below text into a file called Dependencies.cmake:: - - TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() - -In this case the package we are creating has no dependencies but we still need -this file. The lack of arguments to the TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() call -reflects that this package does not have dependencies. The last and most interesting -file we will create in the package directory is the CMakeLists.txt file. Copy the following -into CMakeLists.txt:: - - TRIBITS_PACKAGE(HelloPackage) - TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) - TRIBITS_PACKAGE_POSTPROCESS() - - -**TRIBITS_PACKAGE(HelloPackage)** Sets this up a TriBITS package with the name "HelloPackage" - -**TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE)** tells -TriBITS that we want to build an executable named "Hello-Executable-Name" from the source file src/HelloWorld.cpp. -NOEXEPREFIX and INSTALLABLE are options to TRIBITS_ADD_EXECUTABLE() that I will not go into right now. - -**TRIBITS_PACKAGE_POSTPROCESS()** Must be at the end of any packages top level CMakeLists file - -**Say some stuff about Tribits packages (here) or at teh top of this section** - -Create a Tribits Project -------------------------- -Recall that a TriBITS project is made up of TriBITS packages. We have just defeined a package now we will create -a project that consists of just that one package. In order to do this we are going to create 4 files in the top -level directory and they are named: -* CMakeLists.txt -* PackageList.cmake -* ProjectName.camke -* TPLsList.cmake - -**TPLsList.camke** this file tells Tribits ablout TPLs needed for the project. In this case, the package does not -depend on any TPLs so this file will be very simple. It should contain just the following single line:: - - TRIBITS_REPOSITORY_DEFINE_TPLS() - -**ProjectName.camke** this file sets the name of the project. Some other options can be specified in this file but we -will just set the project name. It should contain the following:: - - SET(PROJECT_NAME TribitsHelloWorld) - -**PackageList.cmake** defeines which packages are in the project. We will just need to tell it the name and location -of our one package:: - - TRIBITS_REPOSITORY_DEFINE_PACKAGES( - HelloPackage hello_package_dir PT - ) - -**CMakeLists.txt** This is the most interesting file in this example. Here we will set a minimum cmake version, load some -options, and tell cmake that this is a Tribits project. The CMakeLists.txt file should have the following contents:: - - # To be safe, define your minimum CMake version - CMAKE_MINIMUM_REQUIRED(VERSION 2.8.11 FATAL_ERROR) - - # Make CMake set WIN32 with CYGWIN for older CMake versions - SET(CMAKE_LEGACY_CYGWIN_WIN32 1 CACHE BOOL "" FORCE) - - # Get PROJECT_NAME (must be in file for other parts of system) - INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake) - - # CMake requires that you declare the CMake project in the top-level file - PROJECT(${PROJECT_NAME} NONE) - - # This needs to be set to the path to the installation of TriBITS on your machine - SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits - CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).") - - # Include the TriBITS system - INCLUDE("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake") - - # MPI and Fortran are enabled by defualt, turn them off for this project - SET(TPL_ENABLE_MPI OFF CACHE BOOL "" FORCE) - # Turn off Fortran support by default - SET(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF) - - # Only one package in this simple project so just enable it :-) - SET(${PROJECT_NAME}_ENABLE_HelloPackage ON CACHE BOOL "" FORCE) - - # Do all of the processing for this Tribits project - TRIBITS_PROJECT() - -**SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits - CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).")** -Make sure you set this to your Tribits Installation path it may not be the same as -this path. Now you should have a directory structure that looks like this:: - - . - ├── CMakeLists.txt - ├── PackagesList.cmake - ├── ProjectName.cmake - ├── TPLsList.cmake - ├── build - └── hello_package_dir - ├── CMakeLists.txt - ├── cmake - │ └── Dependencies.cmake - └── src - └── HelloWorld.cpp - - -Build your TriBITS project ---------------------------- -Go to the build directory and type the following to configure your project:: - cmake ../ - -You should see something very similar to:: - -..literalinclude:: HelloWorldConfigure.output - -The configure step will have created several files inside your build directory, most notably it will have created nessesary make files to -actually build your project. The other file I will mention here is the CMakeCache.txt which stores information about how the project was -configured. - -To build your project just type:: - make - -you should see:: - [ 50%] Building CXX object hello_package_dir/CMakeFiles/Hello-Executable-Name.dir/src/HelloWorld.cpp.o - [100%] Linking CXX executable Hello-Executable-Name.exe - [100%] Built target Hello-Executable-Name - -now in build/hello_package_dir you will see an executable named "Hello-Executable-Name" and if you run that executable you will see:: - $ ./hello_package_dir/Hello-Executable-Name.exe - Hello World! - - -Adding other targets -=============================== - -Types of targets ------------------ -Previously we had just one source file and we compiled it into one executable. In addition to executables we may also want to create other -targets such as libraries abd tests. In the hello_package_dir/src directory create the following files: - -hello_world_main.cpp:: - #include - #include "hello_world_lib.hpp" - int main() { - std::cout << HelloWorld::getHelloWorld() << "\n"; - return 0; - } - -hello_world_lib.hpp:: - #include - - namespace HelloWorld { std::string getHelloWorld(); } - - -hello_world_lib.cpp:: - #include "hello_world_lib.hpp" - std::string HelloWorld::getHelloWorld() - { return "Hello World!"; } - -hello_world_unit_tests.cpp:: - #include - #include "hello_world_lib.hpp" - - int main() { - - bool success = true; - - const std::string rtn = HelloWorld::getHelloWorld(); - std::cout << "HelloWorld::getHelloWorld() = '"< Date: Tue, 27 Jun 2017 16:06:37 -0600 Subject: [PATCH 7/9] first latex format tutorial files --- .../TribitsTutorialHelloWorld_0.tex | 474 ++++++++++++++++++ .../TribitsTutorialHelloWorld_1.tex | 66 +++ 2 files changed, 540 insertions(+) create mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.tex create mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_1.tex diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.tex b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.tex new file mode 100644 index 000000000..2e7e32b7b --- /dev/null +++ b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.tex @@ -0,0 +1,474 @@ +\documentclass[12pt]{article} +\usepackage{verbatim} +\title{TriBITS Hello World Tutorial} +\author{Roscoe A. Bartlett + (rabartl@sandia.gov), Joe Frye (jfrye@sandia.gov)} + +\begin{document} +\maketitle + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section*{The Simplest HelloWorld project} + +This short tutorial will walk you through setting up a basic +HelloWorld project built by TriBITS to intdroduce the basic concepts +in TriBITS. To begin you will need cmake and TriBITS installed on +your machine. You will also need a working c and c++ compiler. + +TriBITS projects have a specific structure ie a project is a +collection of packages. For this example we will be creating a +project that has just one package, the "HelloPackage" package. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection*{Initial Setup} + +First lets create all the directories +for our project. We will need a top level directory for the project +which I will call tribits\_hello\_world. We need a directory for the +"HelloPackage" package. We will also need a directory for the build +which I call "build". Under the hello\_package\_dir also create the +directories "camke" and "src" + +\begin{verbatim} + tribits_hello_world/ + tribits_hello_wolrd/build + tribits_hello_world/hello_package_dir + tribits_hello_world/hello_package_dir/cmake + tribits_hello_world/hello_package_dir/src + + $ tree + . + └── tribits_hello_world + ├── build + └── hello_package_dir + ├── cmake + └── src +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection*{Create a TriBITS package} + +The most basic TriBITS package needs to have 3 files. +* a top level CMakeLists file +* a source file +* a file that track package dependencies + +First lets create the source file which is the classic HelloWorld.cpp. Just +copy this to HelloWorld.cpp in the src directory + +\begin{verbatim} + #include + + int main() + { + std::cout << "Hello World!\n"; + return 0; + + } +\end{verbatim} + +Second lets create the package dependencies file which should be +placed in the cmake directory. Copy the below text into a file called +Dependencies.cmake + +\begin{verbatim} + TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() +\end{verbatim} + +In this case the package we are creating has no dependencies but we +still need this file. The lack of arguments to the +TRIBITS\_PACKAGE\_DEFINE\_DEPENDENCIES() call reflects that this package +does not have dependencies. The last and most interesting file we +will create in the package directory is the CMakeLists.txt file. Copy +the following into CMakeLists.txt + +\begin{verbatim} + TRIBITS_PACKAGE(HelloPackage) + TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) + TRIBITS_PACKAGE_POSTPROCESS() +\end{verbatim} + +\textbf{\\TRIBITS\_PACKAGE(HelloPackage)} Sets this up a TriBITS package +with the name "HelloPackage" + +\textbf{\\TRIBITS\_ADD\_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES + src/HelloWorld.cpp INSTALLABLE)} tells TriBITS that we want to build +an executable named "Hello-Executable-Name" from the source file +src/HelloWorld.cpp. NOEXEPREFIX and INSTALLABLE are options to +TRIBITS\_ADD\_EXECUTABLE() that I will not go into right now. + +\textbf{\\TRIBITS\_PACKAGE\_POSTPROCESS()} Must be at the end of any +packages top level CMakeLists file + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection*{Create a Tribits Project} + +Recall that a TriBITS project is made up of TriBITS packages. We have +just defeined a package now we will create a project that consists of +just that one package. In order to do this we are going to create 4 +files in the top level directory and they are named: + +\begin{itemize} +\item CMakeLists.txt +\item PackageList.cmake +\item ProjectName.camke +\item TPLsList.cmake +\end{itemize} + + + +\textbf{\\\\TPLsList.camke} this file tells Tribits ablout TPLs needed for +the project. In this case, the package does not depend on any TPLs so +this file will be very simple. It should contain just the following +single line + +\begin{verbatim} + TRIBITS\_REPOSITORY\_DEFINE\_TPLS() +\end{verbatim} + +\textbf{\\ProjectName.camke} this file sets the name of the project. Some other options can be specified in this file but we +will just set the project name. It should contain the following + +\begin{verbatim} + SET(PROJECT\_NAME TribitsHelloWorld) +\end{verbatim} + +\textbf{\\PackageList.cmake} defeines which packages are in the project. We will just need to tell it the name and location +of our one package + +\begin{verbatim} + TRIBITS_REPOSITORY_DEFINE_PACKAGES( + HelloPackage hello_package_dir PT + ) +\end{verbatim} + +\textbf{\\CMakeLists.txt} This is the most interesting file in this example. Here we will set a minimum cmake version, load some +options, and tell cmake that this is a Tribits project. The CMakeLists.txt file should have the following contents + +\begin{verbatim} + # To be safe, define your minimum CMake version + CMAKE_MINIMUM_REQUIRED(VERSION 2.8.11 FATAL_ERROR) + + # Make CMake set WIN32 with CYGWIN for older CMake versions + SET(CMAKE_LEGACY_CYGWIN_WIN32 1 CACHE BOOL "" FORCE) + + # Get PROJECT_NAME (must be in file for other parts of system) + INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake) + + # CMake requires that you declare the CMake project in the top-level file + PROJECT(${PROJECT_NAME} NONE) + + # This needs to be set to the path to the installation of TriBITS on your machine + SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).") + + # Include the TriBITS system + INCLUDE("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake") + + # MPI and Fortran are enabled by defualt, turn them off for this project + SET(TPL_ENABLE_MPI OFF CACHE BOOL "" FORCE) + # Turn off Fortran support by default + SET(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF) + + # Only one package in this simple project so just enable it :-) + SET(${PROJECT_NAME}_ENABLE_HelloPackage ON CACHE BOOL "" FORCE) + + # Do all of the processing for this Tribits project + TRIBITS_PROJECT() +\end{verbatim} + + +\textbf{\\SET(${PROJECT\_NAME}\_TRIBITS\_DIR ${CMAKE\_CURRENT\_SOURCE\_DIR}/cmake/tribits + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).")} +Make sure you set this to your Tribits Installation path it may not be the same as +this path. Now you should have a directory structure that looks like this + +\begin{verbatim} + . + ├── CMakeLists.txt + ├── PackagesList.cmake + ├── ProjectName.cmake + ├── TPLsList.cmake + ├── build + └── hello_package_dir + ├── CMakeLists.txt + ├── cmake + │ └── Dependencies.cmake + └── src + └── HelloWorld.cpp +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection*{Build your TriBITS project} + +Go to the build directory and type the following to configure your project + +\begin{verbatim} + cmake ../ +\end{verbatim} + +You should see something very similar to + +\begin{verbatim} + ..literalinclude:: HelloWorldConfigure.output +\end{verbatim} + +The configure step will have created several files inside your build +directory, most notably it will have created nessesary make files to +actually build your project. The other file I will mention here is +the CMakeCache.txt which stores information about how the project was +configured. + +To build your project just type + +\begin{verbatim} + make +\end{verbatim} + +you should see + +\begin{verbatim} + [ 50\%] Building CXX object + hello_package_dir/CMakeFiles/Hello-Executable-Name.dir/src/HelloWorld.cpp.o + [100\%] Linking CXX executable Hello-Executable-Name.exe + [100\%] Built target Hello-Executable-Name +\end{verbatim} + +now in build/hello\_package\_dir you will see an executable named +"Hello-Executable-Name" and if you run that executable you will see + +\begin{verbatim} + $ ./hello_package_dir/Hello-Executable-Name.exe + Hello World! +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Adding other targets} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Types of targets} + +Previously we had just one source +file and we compiled it into one executable. In addition to +executables we may also want to create other targets such as libraries +abd tests. In the hello\_package\_dir/src directory create the +following files: + +\textbf{\\hello\_world\_main.cpp} +\begin{verbatim} + #include + #include "hello_world_lib.hpp" + int main() { + std::cout << HelloWorld::getHelloWorld() << "\n"; + return 0; + } +\end{verbatim} + +\textbf{\\hello\_world\_lib.hpp} +\begin{verbatim} + #include + + namespace HelloWorld { std::string getHelloWorld(); } +\end{verbatim} + +\textbf{\\hello\_world\_lib.cpp} +\begin{verbatim} + #include "hello_world_lib.hpp" + std::string HelloWorld::getHelloWorld() + { return "Hello World!"; } +\end{verbatim} + +\textbf{\\hello\_world\_unit\_tests.cpp} +\begin{verbatim} + #include + #include "hello_world_lib.hpp" + + int main() { + + bool success = true; + + const std::string rtn = HelloWorld::getHelloWorld(); + std::cout << "HelloWorld::getHelloWorld() = '"< + NameOfPackageB path/to/packageB + ) +\end{verbatim} + +you must specify the name of the package and where it is located. +Each package must contain a CmakeLists.cmake file and a +Dependencies.cmake file. The CmakeLists file defines targets for this +package and must begin with a call to TRIBITS\_PACKAGE() and end with a +call to TRIBITS\_PACKAGE\_POSTPROCESS(). Tribits TPLs are defined +similarly in TPLsList.cmake:: + +\begin{verbatim} + TRIBITS\_REPOSITORY\_DEFINE\_TPLS( + NameOfTPL-1 location/of/TPL-1 + NameOfTPL-2 path/to/TPL-2 + ) +\end{verbatim} + +more detail on packages and tpls will follow below. + +\subsection*{Tribits Packages} + + +\subsection*{TriBITS TPLs} + + +% End document +\end{document} From db634ad03a5f393ac7ce5a1ecda8a8dc7bc0bc4d Mon Sep 17 00:00:00 2001 From: Joe Frye Date: Wed, 28 Jun 2017 13:53:53 -0600 Subject: [PATCH 8/9] squish - refined the hello world tutorial --- .../TribitsTutorialHelloWorld_0.tex | 244 +++++++++--------- .../doc/tribits_tutorial/generate-tutorial.sh | 170 +----------- 2 files changed, 120 insertions(+), 294 deletions(-) diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.tex b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.tex index 2e7e32b7b..51e5b50ce 100644 --- a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.tex +++ b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.tex @@ -1,8 +1,7 @@ \documentclass[12pt]{article} \usepackage{verbatim} \title{TriBITS Hello World Tutorial} -\author{Roscoe A. Bartlett - (rabartl@sandia.gov), Joe Frye (jfrye@sandia.gov)} +\author{Joe Frye (jfrye@sandia.gov)} \begin{document} \maketitle @@ -12,24 +11,33 @@ \section*{The Simplest HelloWorld project} This short tutorial will walk you through setting up a basic -HelloWorld project built by TriBITS to intdroduce the basic concepts +HelloWorld project built by TriBITS to intdroduce basic concepts in TriBITS. To begin you will need cmake and TriBITS installed on -your machine. You will also need a working c and c++ compiler. +your machine. You will also need a working c and c++ compiler.\\ -TriBITS projects have a specific structure ie a project is a -collection of packages. For this example we will be creating a -project that has just one package, the "HelloPackage" package. +\textbf{Before you begin make sure you have:} +\begin{itemize} +\item CMake installed +\item Tribits installed +\item C compiler +\item C++ compiler +\end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection*{Initial Setup} -First lets create all the directories -for our project. We will need a top level directory for the project -which I will call tribits\_hello\_world. We need a directory for the -"HelloPackage" package. We will also need a directory for the build -which I call "build". Under the hello\_package\_dir also create the -directories "camke" and "src" - +TriBITS projects have a specific structure ie a project is a +collection of packages. Packages may or may not depend on other +packages, and may or may not be required. For this example we will be +creating a project that has just one package, the "HelloPackage" +package. First lets create all the directories for our project. We +will need a top level directory for the project which I will call +tribits\_hello\_world. We need a directory for the "HelloPackage" +package. We will also need a directory for the build which I call +"build". Under the hello\_package\_dir also create the directories +"cmake" and "src".\\ + +\textbf{You should have the following directories:} \begin{verbatim} tribits_hello_world/ tribits_hello_wolrd/build @@ -39,23 +47,26 @@ \subsection*{Initial Setup} $ tree . - └── tribits_hello_world - ├── build - └── hello_package_dir - ├── cmake - └── src + |__ tribits_hello_world + |__ build + |__ hello_package_dir + |__ cmake + |__ src \end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection*{Create a TriBITS package} -The most basic TriBITS package needs to have 3 files. -* a top level CMakeLists file -* a source file -* a file that track package dependencies -First lets create the source file which is the classic HelloWorld.cpp. Just -copy this to HelloWorld.cpp in the src directory +Any TriBITS package needs to have atleast 3 file. +\begin{itemize} +\item a top level CMakeLists file +\item a file that track package dependencies +\item source files +\end{itemize} + +First lets create a single source file which is the classic +HelloWorld.cpp. Just copy this to HelloWorld.cpp in the src directory \begin{verbatim} #include @@ -66,7 +77,7 @@ \subsection*{Create a TriBITS package} return 0; } -\end{verbatim} +\end{verbatim}\\ Second lets create the package dependencies file which should be placed in the cmake directory. Copy the below text into a file called @@ -74,20 +85,23 @@ \subsection*{Create a TriBITS package} \begin{verbatim} TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() -\end{verbatim} +\end{verbatim}\\ In this case the package we are creating has no dependencies but we still need this file. The lack of arguments to the -TRIBITS\_PACKAGE\_DEFINE\_DEPENDENCIES() call reflects that this package -does not have dependencies. The last and most interesting file we -will create in the package directory is the CMakeLists.txt file. Copy -the following into CMakeLists.txt +TRIBITS\_PACKAGE\_DEFINE\_DEPENDENCIES() call reflects that this +package does not have dependencies. The last and most interesting +file we will create in the package directory is the CMakeLists.txt +file. Copy the following into CMakeLists.txt \begin{verbatim} TRIBITS_PACKAGE(HelloPackage) - TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) + + TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES + src/HelloWorld.cpp INSTALLABLE) + TRIBITS_PACKAGE_POSTPROCESS() -\end{verbatim} +\end{verbatim}\\ \textbf{\\TRIBITS\_PACKAGE(HelloPackage)} Sets this up a TriBITS package with the name "HelloPackage" @@ -112,27 +126,27 @@ \subsection*{Create a Tribits Project} \begin{itemize} \item CMakeLists.txt \item PackageList.cmake -\item ProjectName.camke +\item ProjectName.cmake \item TPLsList.cmake \end{itemize} -\textbf{\\\\TPLsList.camke} this file tells Tribits ablout TPLs needed for +\textbf{\\\\TPLsList.cmake} this file tells Tribits ablout TPLs needed for the project. In this case, the package does not depend on any TPLs so this file will be very simple. It should contain just the following single line \begin{verbatim} - TRIBITS\_REPOSITORY\_DEFINE\_TPLS() -\end{verbatim} + TRIBITS_REPOSITORY_DEFINE_TPLS() +\end{verbatim}\\ -\textbf{\\ProjectName.camke} this file sets the name of the project. Some other options can be specified in this file but we +\textbf{\\ProjectName.cmake} this file sets the name of the project. Some other options can be specified in this file but we will just set the project name. It should contain the following \begin{verbatim} - SET(PROJECT\_NAME TribitsHelloWorld) -\end{verbatim} + SET(PROJECT_NAME TribitsHelloWorld) +\end{verbatim}\\ \textbf{\\PackageList.cmake} defeines which packages are in the project. We will just need to tell it the name and location of our one package @@ -141,7 +155,7 @@ \subsection*{Create a Tribits Project} TRIBITS_REPOSITORY_DEFINE_PACKAGES( HelloPackage hello_package_dir PT ) -\end{verbatim} +\end{verbatim}\\ \textbf{\\CMakeLists.txt} This is the most interesting file in this example. Here we will set a minimum cmake version, load some options, and tell cmake that this is a Tribits project. The CMakeLists.txt file should have the following contents @@ -176,27 +190,26 @@ \subsection*{Create a Tribits Project} # Do all of the processing for this Tribits project TRIBITS_PROJECT() -\end{verbatim} +\end{verbatim}\\ -\textbf{\\SET(${PROJECT\_NAME}\_TRIBITS\_DIR ${CMAKE\_CURRENT\_SOURCE\_DIR}/cmake/tribits - CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).")} +\textbf{\\\${PROJECT\_NAME}\_TRIBITS\_DIR} Make sure you set this to your Tribits Installation path it may not be the same as this path. Now you should have a directory structure that looks like this \begin{verbatim} . - ├── CMakeLists.txt - ├── PackagesList.cmake - ├── ProjectName.cmake - ├── TPLsList.cmake - ├── build - └── hello_package_dir - ├── CMakeLists.txt - ├── cmake - │ └── Dependencies.cmake - └── src - └── HelloWorld.cpp + |__ CMakeLists.txt + |__ PackagesList.cmake + |__ ProjectName.cmake + |__ TPLsList.cmake + |__ build + |__ hello_package_dir + |__ CMakeLists.txt + |__ cmake + |__ └── Dependencies.cmake + |__ src + |__ HelloWorld.cpp \end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -206,42 +219,28 @@ \subsection*{Build your TriBITS project} \begin{verbatim} cmake ../ -\end{verbatim} - -You should see something very similar to - -\begin{verbatim} - ..literalinclude:: HelloWorldConfigure.output -\end{verbatim} - +\end{verbatim}\\ The configure step will have created several files inside your build directory, most notably it will have created nessesary make files to actually build your project. The other file I will mention here is the CMakeCache.txt which stores information about how the project was -configured. - -To build your project just type - +configured. To build your project just type \begin{verbatim} make -\end{verbatim} - +\end{verbatim}\\ you should see - \begin{verbatim} [ 50\%] Building CXX object hello_package_dir/CMakeFiles/Hello-Executable-Name.dir/src/HelloWorld.cpp.o [100\%] Linking CXX executable Hello-Executable-Name.exe [100\%] Built target Hello-Executable-Name -\end{verbatim} - +\end{verbatim}\\ now in build/hello\_package\_dir you will see an executable named "Hello-Executable-Name" and if you run that executable you will see - \begin{verbatim} $ ./hello_package_dir/Hello-Executable-Name.exe Hello World! -\end{verbatim} +\end{verbatim}\\ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -265,7 +264,7 @@ \subsection{Types of targets} std::cout << HelloWorld::getHelloWorld() << "\n"; return 0; } -\end{verbatim} +\end{verbatim}\\ \textbf{\\hello\_world\_lib.hpp} \begin{verbatim} @@ -308,57 +307,45 @@ \subsection{Types of targets} } } -\end{verbatim} - +\end{verbatim}\\ We will use these files to build an executalbe, a library, and tests. Remember in the CMakeLists.txt file for the HelloPackage (hello\_package\_dir/CMakeList.txt) we have the line - \begin{verbatim} TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) -\end{verbatim} - +\end{verbatim}\\ lets now modify that line to build an executable of the same name but using hello\_world\_main.cpp instead of HelloWorld.cpp - \begin{verbatim} TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/hello_world_main.cpp INSTALLABLE) -\end{verbatim} - +\end{verbatim}\\ to create a library we need to call TRIBITS\_ADD\_LIBRARY() and give it a name, headers and sources. add this the CMakeLists.txt - \begin{verbatim} TRIBITS_ADD_LIBRARY(hello_world_lib HEADERS src/hello_world_lib.hpp SOURCES src/hello_world_lib.cpp) -\end{verbatim} - +\end{verbatim}\\ we can also add tests. You can add a test based on an executable you have already specified for example - \begin{verbatim} TRIBITS_ADD_TEST(Hello-Executable-Name NOEXEPREFIX PASS_REGULAR_EXPRESSION "Hello World") -\end{verbatim} - +\end{verbatim}\\ will run "Hello-Executable-Name" and verify that the output is "Hello World". You can also add a test and an exectuable att he same time. for example - \begin{verbatim} TRIBITS_ADD_EXECUTABLE_AND_TEST(unit_tests SOURCES src/hello_world_unit_tests.cpp PASS_REGULAR_EXPRESSION "All unit tests passed") -\end{verbatim} - +\end{verbatim}\\ will create an executable named "unit\_tests" from the source file hello\_world\_unit\_tests.cpp. This executable will be used in a test that will be marked as passing if the output of that executable is "All unit tests passed". After making these changes and additions to the CMakeLists.txt file it should read - \begin{verbatim} TRIBITS_PACKAGE(HelloPackage) @@ -376,14 +363,12 @@ \subsection{Types of targets} passed") TRIBITS_PACKAGE_POSTPROCESS() -\end{verbatim} - +\end{verbatim}\\ now reconfigure and rebuild in the build directory with - \begin{verbatim} cmake ../ make -\end{verbatim} +\end{verbatim}\\ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -401,37 +386,33 @@ \subsection{Build Targets} \begin{verbatim} build/hello_package_dir -\end{verbatim} - +\end{verbatim}\\ among other things you will see \begin{verbatim} Hello-Executable-Name.exe HelloPackage_unit_tests.exe libhello_world_lib.a -\end{verbatim} - +\end{verbatim}\\ by default, TriBITS will place the targets inside a directory with the same name as the package directory. If you have more than one package then the files will be in separate directories \begin{verbatim} build - ├── package_one - │ ├── build_target_A - │ └── build_target_B - └── package_two - ├── build_target_C - └── build_target_D -\end{verbatim} - + |__ package_one + |__ build_target_A + |__ build_target_B + |__ package_two + |__ build_target_C + |__ build_target_D +\end{verbatim}\\ You can install the built targets to the default location (/usr/local/bin) with \begin{verbatim} make install -\end{verbatim} - +\end{verbatim}\\ You may want to install somewhere other than the default. In this case you want to set a CMamke variable called CMAKE\_INSTALL\_PREFIX. If this is set then the files will be installed to the directory @@ -440,34 +421,43 @@ \subsection{Build Targets} \begin{verbatim} SET(CMAKE_INSTALL_PREFIX ${CMAKE_CURRENT_SOURCE_DIR}/Install) -\end{verbatim} - +\end{verbatim}\\ now clear the contents ofthe build directory and reconfigure, biuld, and install the project with \begin{verbatim} cmake ../ make install -\end{verbatim} - +\end{verbatim}\\ Now you should see a directory calle "Install" in the top level of the project with contents \begin{verbatim} tree . - ├── bin - │ └── Hello-Executable-Name.exe - ├── include - │ ├── Makefile.export.HelloPackage - │ ├── Makefile.export.TribitsGreetings - │ └── hello_world_lib.hpp - └── lib - ├── cmake - │ └── TribitsGreetings - │ └── TribitsGreetingsConfigVersion.cmake - └── libhello_world_lib.a -\end{verbatim} + |__ bin + | |__ Hello-Executable-Name.exe + |__ include + | |__ Makefile.export.HelloPackage + | |__ Makefile.export.TribitsGreetings + | |__ hello_world_lib.hpp + |__ lib + |__ cmake + | |__ TribitsGreetings + | |__ TribitsGreetingsConfigVersion.cmake + |__ libhello_world_lib.a +\end{verbatim}\\ + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Summary} +This tutorial has covered the most basic concepts in a TriBITS +project. A TriBITS project a collection of TriBITS packages and each +package defines its build targets (executables, tests, and libraries) +and source files. A package also must define its dependencies. See +the TriBITS example project tutarial for a more complicate example of +a project and more detail about Tribits packages, TPLs, and +dependencies % End document diff --git a/tribits/doc/tribits_tutorial/generate-tutorial.sh b/tribits/doc/tribits_tutorial/generate-tutorial.sh index 2c5982f9f..97aaa5ade 100755 --- a/tribits/doc/tribits_tutorial/generate-tutorial.sh +++ b/tribits/doc/tribits_tutorial/generate-tutorial.sh @@ -1,170 +1,6 @@ #!/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 exmaple: -# -# ./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 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 '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 + +latex -output-format=pdf ../TribitsTutorialHelloWorld_0.tex +latex -output-format=pdf ../TribitsTutorialHelloWorld_1.tex From 7afdb7c6fb92520b90f0126a995da005465c5dc7 Mon Sep 17 00:00:00 2001 From: Joe Frye Date: Wed, 28 Jun 2017 13:55:22 -0600 Subject: [PATCH 9/9] squish - removed some unused files. contents moved to other files --- .../TribitsTutorialHelloWorld.rst | 194 ---------- .../TribitsTutorialHelloWorld_0.rst | 361 ------------------ .../TribitsTutorialHelloWorld_1.rst | 48 --- 3 files changed, 603 deletions(-) delete mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst delete mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.rst delete mode 100644 tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_1.rst diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst deleted file mode 100644 index eedf2124a..000000000 --- a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst +++ /dev/null @@ -1,194 +0,0 @@ -======================================= -TriBITS Hello World Tutorial -======================================= - -:Author: Roscoe A. Bartlett (bartlettra@ornl.gov), Joe Frye (jfrye@sandia.gov) -:Date: |date| -:Version: .. include:: TribitsGitVersion.txt - -.. |date| date:: - - -.. sectnum:: - :depth: 2 - -.. Above, the depth of the TOC is set to just 2 because I don't want the -.. TriBITS function/macro names to have section numbers appearing before them. -.. Also, some of them are long and I don't want them to go off the page of the -.. PDF document. - -.. Sections in this document use the underlines: -.. -.. Level-1 ================== -.. Level-2 ------------------ -.. Level-3 ++++++++++++++++++ -.. Level-4 .................. - -.. contents:: - -The Simplest HelloWorld project -=================================== -This short tutorial will walk you through setting up a basic HelloWorld project -built by TriBITS to intdroduce the basic concepts in TriBits. To begin you -will need cmake and TriBITS installed on your machine. You will also need a -working c and c++ compiler. - -TriBITS projects have a specific structure ie a project is a collection of -packages. For this example we will be creating a project that has just one -package, the "HelloPackage" package. - -Initial Setup ----------------- -First lets create all the directories for our project. We will need a top level -directory for the project which I will call tribits_hello_world. We need a -directory for the "HelloPackage" package. We will also need a directory for the -build which I call "build". Under the hello_package_dir also create the directories -"camke" and "src":: - - tribits_hello_world/ - tribits_hello_wolrd/build - tribits_hello_world/hello_package_dir - tribits_hello_world/hello_package_dir/cmake - tribits_hello_world/hello_package_dir/src - - $ tree - . - └── tribits_hello_world - ├── build - └── hello_package_dir - ├── cmake - └── src - -Create a TriBITS package -------------------------- -The most basic TriBITS package needs to have 3 files. -* a top level CMakeLists file -* a source file -* a file that track package dependencies - -First lets create the source file which is the classic HelloWorld.cpp. Just -copy this to HelloWorld.cpp in the src directory:: - - #include - - int main() - { - std::cout << "Hello World!\n"; - return 0; - - } - -Second lets create the package dependencies file which should be placed in the -cmake directory. Copy the below text into a file called Dependencies.cmake:: - - TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() - -In this case the package we are creating has no dependencies but we still need -this file. The lack of arguments to the TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() call -reflects that this package does not have dependencies. The last and most interesting -file we will create in the package directory is the CMakeLists.txt file. Copy the following -into CMakeLists.txt:: - - TRIBITS_PACKAGE(HelloPackage) - TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) - TRIBITS_PACKAGE_POSTPROCESS() - - -**TRIBITS_PACKAGE(HelloPackage)** Sets this up a TriBITS package with the name "HelloPackage" - -**TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE)** tells -TriBITS that we want to build an executable named "Hello-Executable-Name" from the source file src/HelloWorld.cpp. -NOEXEPREFIX and INSTALLABLE are options to TRIBITS_ADD_EXECUTABLE() that I will not go into right now. - -**TRIBITS_PACKAGE_POSTPROCESS()** Must be at the end of any packages top level CMakeLists file - -**Say some stuff about Tribits packages (here) or at teh top of this section** - -Create a Tribits Project -------------------------- -Recall that a TriBITS project is made up of TriBITS packages. We have just defeined a package now we will create -a project that consists of just that one package. In order to do this we are going to create 4 files in the top -level directory and they are named: -* CMakeLists.txt -* PackageList.cmake -* ProjectName.camke -* TPLsList.cmake - -**TPLsList.camke** this file tells Tribits ablout TPLs needed for the project. In this case, the package does not -depend on any TPLs so this file will be very simple. It should contain just the following single line:: - - TRIBITS_REPOSITORY_DEFINE_TPLS() - -**ProjectName.camke** this file sets the name of the project. Some other options can be specified in this file but we -will just set the project name. It should contain the following:: - - SET(PROJECT_NAME TribitsHelloWorld) - -**PackageList.cmake** defeines which packages are in the project. We will just need to tell it the name and location -of our one package:: - - TRIBITS_REPOSITORY_DEFINE_PACKAGES( - HelloPackage hello_package_dir PT - ) - -**CMakeLists.txt** This is the most interesting file in this example. Here we will set a minimum cmake version, load some -options, and tell cmake that this is a Tribits project. The CMakeLists.txt file should have the following contents:: - - # To be safe, define your minimum CMake version - CMAKE_MINIMUM_REQUIRED(VERSION 2.8.11 FATAL_ERROR) - - # Make CMake set WIN32 with CYGWIN for older CMake versions - SET(CMAKE_LEGACY_CYGWIN_WIN32 1 CACHE BOOL "" FORCE) - - # Get PROJECT_NAME (must be in file for other parts of system) - INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake) - - # CMake requires that you declare the CMake project in the top-level file - PROJECT(${PROJECT_NAME} NONE) - - # This needs to be set to the path to the installation of TriBITS on your machine - SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits - CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).") - - # Include the TriBITS system - INCLUDE("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake") - - # MPI and Fortran are enabled by defualt, turn them off for this project - SET(TPL_ENABLE_MPI OFF CACHE BOOL "" FORCE) - # Turn off Fortran support by default - SET(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF) - - # Only one package in this simple project so just enable it :-) - SET(${PROJECT_NAME}_ENABLE_HelloPackage ON CACHE BOOL "" FORCE) - - # Do all of the processing for this Tribits project - TRIBITS_PROJECT() - -**SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits - CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).")** -Make sure you set this to your Tribits Installation path it may not be the same as -this path. Now you should have a directory structure that looks like this:: - - . - ├── CMakeLists.txt - ├── PackagesList.cmake - ├── ProjectName.cmake - ├── TPLsList.cmake - ├── build - └── hello_package_dir - ├── CMakeLists.txt - ├── cmake - │ └── Dependencies.cmake - └── src - └── HelloWorld.cpp - - -Build your TriBITS project ---------------------------- -Go to the build directory and type:: - cmake ../ - -You should see something very similar to:: - -..literalinclude:: HelloWorldConfigure.output - diff --git a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.rst b/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.rst deleted file mode 100644 index 7a7383e1d..000000000 --- a/tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld_0.rst +++ /dev/null @@ -1,361 +0,0 @@ -======================================= -TriBITS Hello World Tutorial -======================================= - -:Author: Roscoe A. Bartlett (bartlettra@ornl.gov), Joe Frye (jfrye@sandia.gov) -:Date: |date| -:Version: .. include:: TribitsGitVersion.txt - -.. |date| date:: - - -.. sectnum:: - :depth: 2 - -.. Above, the depth of the TOC is set to just 2 because I don't want the -.. TriBITS function/macro names to have section numbers appearing before them. -.. Also, some of them are long and I don't want them to go off the page of the -.. PDF document. - -.. Sections in this document use the underlines: -.. -.. Level-1 ================== -.. Level-2 ------------------ -.. Level-3 ++++++++++++++++++ -.. Level-4 .................. - -.. contents:: - -The Simplest HelloWorld project -=================================== -This short tutorial will walk you through setting up a basic HelloWorld project -built by TriBITS to intdroduce the basic concepts in TriBITS. To begin you -will need cmake and TriBITS installed on your machine. You will also need a -working c and c++ compiler. - -TriBITS projects have a specific structure ie a project is a collection of -packages. For this example we will be creating a project that has just one -package, the "HelloPackage" package. - -Initial Setup ----------------- -First lets create all the directories for our project. We will need a top level -directory for the project which I will call tribits_hello_world. We need a -directory for the "HelloPackage" package. We will also need a directory for the -build which I call "build". Under the hello_package_dir also create the directories -"camke" and "src":: - - tribits_hello_world/ - tribits_hello_wolrd/build - tribits_hello_world/hello_package_dir - tribits_hello_world/hello_package_dir/cmake - tribits_hello_world/hello_package_dir/src - - $ tree - . - └── tribits_hello_world - ├── build - └── hello_package_dir - ├── cmake - └── src - -Create a TriBITS package -------------------------- -The most basic TriBITS package needs to have 3 files. -* a top level CMakeLists file -* a source file -* a file that track package dependencies - -First lets create the source file which is the classic HelloWorld.cpp. Just -copy this to HelloWorld.cpp in the src directory:: - - #include - - int main() - { - std::cout << "Hello World!\n"; - return 0; - - } - -Second lets create the package dependencies file which should be placed in the -cmake directory. Copy the below text into a file called Dependencies.cmake:: - - TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() - -In this case the package we are creating has no dependencies but we still need -this file. The lack of arguments to the TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() call -reflects that this package does not have dependencies. The last and most interesting -file we will create in the package directory is the CMakeLists.txt file. Copy the following -into CMakeLists.txt:: - - TRIBITS_PACKAGE(HelloPackage) - TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) - TRIBITS_PACKAGE_POSTPROCESS() - - -**TRIBITS_PACKAGE(HelloPackage)** Sets this up a TriBITS package with the name "HelloPackage" - -**TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE)** tells -TriBITS that we want to build an executable named "Hello-Executable-Name" from the source file src/HelloWorld.cpp. -NOEXEPREFIX and INSTALLABLE are options to TRIBITS_ADD_EXECUTABLE() that I will not go into right now. - -**TRIBITS_PACKAGE_POSTPROCESS()** Must be at the end of any packages top level CMakeLists file - -**Say some stuff about Tribits packages (here) or at teh top of this section** - -Create a Tribits Project -------------------------- -Recall that a TriBITS project is made up of TriBITS packages. We have just defeined a package now we will create -a project that consists of just that one package. In order to do this we are going to create 4 files in the top -level directory and they are named: -* CMakeLists.txt -* PackageList.cmake -* ProjectName.camke -* TPLsList.cmake - -**TPLsList.camke** this file tells Tribits ablout TPLs needed for the project. In this case, the package does not -depend on any TPLs so this file will be very simple. It should contain just the following single line:: - - TRIBITS_REPOSITORY_DEFINE_TPLS() - -**ProjectName.camke** this file sets the name of the project. Some other options can be specified in this file but we -will just set the project name. It should contain the following:: - - SET(PROJECT_NAME TribitsHelloWorld) - -**PackageList.cmake** defeines which packages are in the project. We will just need to tell it the name and location -of our one package:: - - TRIBITS_REPOSITORY_DEFINE_PACKAGES( - HelloPackage hello_package_dir PT - ) - -**CMakeLists.txt** This is the most interesting file in this example. Here we will set a minimum cmake version, load some -options, and tell cmake that this is a Tribits project. The CMakeLists.txt file should have the following contents:: - - # To be safe, define your minimum CMake version - CMAKE_MINIMUM_REQUIRED(VERSION 2.8.11 FATAL_ERROR) - - # Make CMake set WIN32 with CYGWIN for older CMake versions - SET(CMAKE_LEGACY_CYGWIN_WIN32 1 CACHE BOOL "" FORCE) - - # Get PROJECT_NAME (must be in file for other parts of system) - INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake) - - # CMake requires that you declare the CMake project in the top-level file - PROJECT(${PROJECT_NAME} NONE) - - # This needs to be set to the path to the installation of TriBITS on your machine - SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits - CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).") - - # Include the TriBITS system - INCLUDE("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake") - - # MPI and Fortran are enabled by defualt, turn them off for this project - SET(TPL_ENABLE_MPI OFF CACHE BOOL "" FORCE) - # Turn off Fortran support by default - SET(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF) - - # Only one package in this simple project so just enable it :-) - SET(${PROJECT_NAME}_ENABLE_HelloPackage ON CACHE BOOL "" FORCE) - - # Do all of the processing for this Tribits project - TRIBITS_PROJECT() - -**SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits - CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).")** -Make sure you set this to your Tribits Installation path it may not be the same as -this path. Now you should have a directory structure that looks like this:: - - . - ├── CMakeLists.txt - ├── PackagesList.cmake - ├── ProjectName.cmake - ├── TPLsList.cmake - ├── build - └── hello_package_dir - ├── CMakeLists.txt - ├── cmake - │ └── Dependencies.cmake - └── src - └── HelloWorld.cpp - - -Build your TriBITS project ---------------------------- -Go to the build directory and type the following to configure your project:: - cmake ../ - -You should see something very similar to:: - -..literalinclude:: HelloWorldConfigure.output - -The configure step will have created several files inside your build directory, most notably it will have created nessesary make files to -actually build your project. The other file I will mention here is the CMakeCache.txt which stores information about how the project was -configured. - -To build your project just type:: - make - -you should see:: - [ 50%] Building CXX object hello_package_dir/CMakeFiles/Hello-Executable-Name.dir/src/HelloWorld.cpp.o - [100%] Linking CXX executable Hello-Executable-Name.exe - [100%] Built target Hello-Executable-Name - -now in build/hello_package_dir you will see an executable named "Hello-Executable-Name" and if you run that executable you will see:: - $ ./hello_package_dir/Hello-Executable-Name.exe - Hello World! - - -Adding other targets -=============================== - -Types of targets ------------------ -Previously we had just one source file and we compiled it into one executable. In addition to executables we may also want to create other -targets such as libraries abd tests. In the hello_package_dir/src directory create the following files: - -hello_world_main.cpp:: - #include - #include "hello_world_lib.hpp" - int main() { - std::cout << HelloWorld::getHelloWorld() << "\n"; - return 0; - } - -hello_world_lib.hpp:: - #include - - namespace HelloWorld { std::string getHelloWorld(); } - - -hello_world_lib.cpp:: - #include "hello_world_lib.hpp" - std::string HelloWorld::getHelloWorld() - { return "Hello World!"; } - -hello_world_unit_tests.cpp:: - #include - #include "hello_world_lib.hpp" - - int main() { - - bool success = true; - - const std::string rtn = HelloWorld::getHelloWorld(); - std::cout << "HelloWorld::getHelloWorld() = '"<