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

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_<TPL>=OFF ...
+
+
+Disabling subpackages for hard disables of parent packages due to TribitsGreetings_ENABLE_<PARENT_PACKAGE>=OFF ...
+
+
+Disabling forward required SE packages and optional intra-package support that have a dependancy on disabled SE packages TribitsGreetings_ENABLE_<TRIBITS_PACKAGE>=OFF ...
+
+
+Enabling subpackages for hard enables of parent packages due to TribitsGreetings_ENABLE_<PARENT_PACKAGE>=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 <TRIBITS_PACKAGE>_ENABLE_<DEPPACKAGE> 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 <TRIBITS_PACKAGE>_ENABLE_<TPL>=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

tribits/doc/tribits_tutorial/TribitsTutorialHelloWorld.rst

@@ -0,0 +1,194 @@
+=======================================
+TriBITS Hello World Tutorial
+=======================================
+
+:Author: Roscoe A. Bartlett ([email protected]), Joe Frye ([email protected])
+: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 <iostream>
+
+  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
+