Help/guide/tutorial: Adopt tutorial code

9 files changed, 246 insertions, 0 deletions

diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt
new file mode 100644
index 0000000..33aa039
--- /dev/null
+++ b/Help/guide/tutorial/Step7/CMakeLists.txt
@@ -0,0 +1,75 @@
+cmake_minimum_required(VERSION 3.3)
+project(Tutorial)
+
+set(CMAKE_CXX_STANDARD 14)
+
+# the version number.
+set(Tutorial_VERSION_MAJOR 1)
+set(Tutorial_VERSION_MINOR 0)
+
+# does this system provide the log and exp functions?
+include(CheckSymbolExists)
+set(CMAKE_REQUIRED_LIBRARIES "m")
+check_symbol_exists(log "math.h" HAVE_LOG)
+check_symbol_exists(exp "math.h" HAVE_EXP)
+
+# should we use our own math functions
+option(USE_MYMATH "Use tutorial provided math implementation" ON)
+
+# configure a header file to pass some of the CMake settings
+# to the source code
+configure_file(
+  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
+  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
+  )
+
+# add the MathFunctions library?
+if(USE_MYMATH)
+  add_subdirectory(MathFunctions)
+  list(APPEND EXTRA_LIBS MathFunctions)
+endif(USE_MYMATH)
+
+# add the executable
+add_executable(Tutorial tutorial.cxx)
+target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS})
+
+# add the binary tree to the search path for include files
+# so that we will find TutorialConfig.h
+target_include_directories(Tutorial PUBLIC
+                           "${PROJECT_BINARY_DIR}"
+                            )
+
+# add the install targets
+install(TARGETS Tutorial DESTINATION bin)
+install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h"
+  DESTINATION include
+  )
+
+# enable testing
+enable_testing()
+
+# does the application run
+add_test(NAME Runs COMMAND Tutorial 25)
+
+# does the usage message work?
+add_test(NAME Usage COMMAND Tutorial)
+set_tests_properties(Usage
+  PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number"
+  )
+
+# define a function to simplify adding tests
+function(do_test target arg result)
+  add_test(NAME Comp${arg} COMMAND ${target} ${arg})
+  set_tests_properties(Comp${arg}
+    PROPERTIES PASS_REGULAR_EXPRESSION ${result}
+    )
+endfunction(do_test)
+
+# do a bunch of result based tests
+do_test(Tutorial 4 "4 is 2")
+do_test(Tutorial 9 "9 is 3")
+do_test(Tutorial 5 "5 is 2.236")
+do_test(Tutorial 7 "7 is 2.645")
+do_test(Tutorial 25 "25 is 5")
+do_test(Tutorial -25 "-25 is [-nan|nan|0]")
+do_test(Tutorial 0.0001 "0.0001 is 0.01")
diff --git a/Help/guide/tutorial/Step7/License.txt b/Help/guide/tutorial/Step7/License.txt
new file mode 100644
index 0000000..c62d00b
--- /dev/null
+++ b/Help/guide/tutorial/Step7/License.txt
@@ -0,0 +1,2 @@
+This is the open source License.txt file introduced in
+CMake/Tutorial/Step7...
diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt
new file mode 100644
index 0000000..dc3eb98
--- /dev/null
+++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt
@@ -0,0 +1,29 @@
+# first we add the executable that generates the table
+add_executable(MakeTable MakeTable.cxx)
+
+# add the command to generate the source code
+add_custom_command(
+  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
+  COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
+  DEPENDS MakeTable
+  )
+
+# add the main library
+add_library(MathFunctions
+            mysqrt.cxx
+            ${CMAKE_CURRENT_BINARY_DIR}/Table.h
+            )
+
+# state that anybody linking to us needs to include the current source dir
+# to find MathFunctions.h, while we don't.
+# state that we depend on Tutorial_BINARY_DIR but consumers don't, as the
+# TutorialConfig.h include is an implementation detail
+# state that we depend on our binary dir to find Table.h
+target_include_directories(MathFunctions
+          INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
+          PRIVATE ${Tutorial_BINARY_DIR}
+                  ${CMAKE_CURRENT_BINARY_DIR}
+          )
+
+install(TARGETS MathFunctions DESTINATION lib)
+install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step7/MathFunctions/MakeTable.cxx
new file mode 100644
index 0000000..ee58556
--- /dev/null
+++ b/Help/guide/tutorial/Step7/MathFunctions/MakeTable.cxx
@@ -0,0 +1,25 @@
+// A simple program that builds a sqrt table
+#include <cmath>
+#include <fstream>
+#include <iostream>
+
+int main(int argc, char* argv[])
+{
+  // make sure we have enough arguments
+  if (argc < 2) {
+    return 1;
+  }
+
+  std::ofstream fout(argv[1], std::ios_base::out);
+  const bool fileOpen = fout.is_open();
+  if (fileOpen) {
+    fout << "double sqrtTable[] = {" << std::endl;
+    for (int i = 0; i < 10; ++i) {
+      fout << sqrt(static_cast<double>(i)) << "," << std::endl;
+    }
+    // close the table with a zero
+    fout << "0};" << std::endl;
+    fout.close();
+  }
+  return fileOpen ? 0 : 1; // return 0 if wrote the file
+}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h
new file mode 100644
index 0000000..cd36bcc
--- /dev/null
+++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h
@@ -0,0 +1 @@
+double mysqrt(double x);
diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx
new file mode 100644
index 0000000..5272f56
--- /dev/null
+++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx
@@ -0,0 +1,34 @@
+#include "MathFunctions.h"
+#include "TutorialConfig.h"
+#include <iostream>
+
+// include the generated table
+#include "Table.h"
+
+#include <cmath>
+
+// a hack square root calculation using simple operations
+double mysqrt(double x)
+{
+  if (x <= 0) {
+    return 0;
+  }
+
+  // use the table to help find an initial value
+  double result = x;
+  if (x >= 1 && x < 10) {
+    result = sqrtTable[static_cast<int>(x)];
+  }
+
+  // do ten iterations
+  for (int i = 0; i < 10; ++i) {
+    if (result <= 0) {
+      result = 0.1;
+    }
+    double delta = x - (result * result);
+    result = result + 0.5 * delta / result;
+    std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+  }
+
+  return result;
+}
diff --git a/Help/guide/tutorial/Step7/TutorialConfig.h.in b/Help/guide/tutorial/Step7/TutorialConfig.h.in
new file mode 100644
index 0000000..e97ce24
--- /dev/null
+++ b/Help/guide/tutorial/Step7/TutorialConfig.h.in
@@ -0,0 +1,8 @@
+// the configured options and settings for Tutorial
+#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
+#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
+#cmakedefine USE_MYMATH
+
+// does the platform provide exp and log functions?
+#cmakedefine HAVE_LOG
+#cmakedefine HAVE_EXP
diff --git a/Help/guide/tutorial/Step7/directions.txt b/Help/guide/tutorial/Step7/directions.txt
new file mode 100644
index 0000000..7d7c2ea
--- /dev/null
+++ b/Help/guide/tutorial/Step7/directions.txt
@@ -0,0 +1,40 @@
+# Building an Installer #
+
+Next suppose that we want to distribute our project to other people so that they
+can use it. We want to provide both binary and source distributions on a variety
+of platforms. This is a little different from the install we did previously in
+the Installing and Testing section (Step 4), where we were installing the
+binaries that we had built from the source code. In this example we will be
+building installation packages that support binary installations and package
+management features. To accomplish this we will use CPack to create platform
+specific installers. Specifically we need to add a few lines to the bottom of
+our top-level CMakeLists.txt file.
+
+  include(InstallRequiredSystemLibraries)
+  set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
+  set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
+  set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
+  include(CPack)
+
+That is all there is to it. We start by including InstallRequiredSystemLibraries.
+This module will include any runtime libraries that are needed by the project
+for the current platform. Next we set some CPack variables to where we have
+stored the license and version information for this project. The version
+information makes use of the variables we set earlier in this tutorial. Finally
+we include the CPack module which will use these variables and some other
+properties of the system you are on to setup an installer.
+
+The next step is to build the project in the usual manner and then run CPack
+on it. To build a binary distribution you would run:
+
+  cpack
+
+To create a source distribution you would type:
+
+  cpack -C CPackSourceConfig.cmake
+
+Alternatively, run “make package” or right click the Package target and
+“Build Project” from an IDE.
+
+Run the installer executable found  in the binary directory. Then run the
+installed executable and verify that it works.
diff --git a/Help/guide/tutorial/Step7/tutorial.cxx b/Help/guide/tutorial/Step7/tutorial.cxx
new file mode 100644
index 0000000..c2b89df
--- /dev/null
+++ b/Help/guide/tutorial/Step7/tutorial.cxx
@@ -0,0 +1,32 @@
+// A simple program that computes the square root of a number
+#include <cmath>
+#include <iostream>
+#include <string>
+
+#include "TutorialConfig.h"
+
+#ifdef USE_MYMATH
+#  include "MathFunctions.h"
+#endif
+
+int main(int argc, char* argv[])
+{
+  if (argc < 2) {
+    std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
+              << Tutorial_VERSION_MINOR << std::endl;
+    std::cout << "Usage: " << argv[0] << " number" << std::endl;
+    return 1;
+  }
+
+  double inputValue = std::stod(argv[1]);
+
+#ifdef USE_MYMATH
+  double outputValue = mysqrt(inputValue);
+#else
+  double outputValue = sqrt(inputValue);
+#endif
+
+  std::cout << "The square root of " << inputValue << " is " << outputValue
+            << std::endl;
+  return 0;
+}