Modernize for newer CMake and compilers (trilinos#8498)

This now builds without errors with Clang 10.0.  (There was a build error
before this update.)

* Require CMake 3.17.1 which is the same minimum now required by Trilinos

* Updated the documentation to use Markdown and use raw CMake and no do-cmake
  script

* Deleted unneccasary do-cmake script

* Deleted usage of a 'Trilinos_PREFIX' var and just use built-in CMake var
  CMAKE_PREFIX_PATH directly as documented in CMake documentation for
  'find_package()'

* Turn off warning from Kokkos about not suupporting C++ extensions

* Fix build error with source code

demos/buildAgainstTrilinos/CMakeLists.txt

@@ -1,11 +1,9 @@
 # CMAKE File for "MyApp" application building against an installed Trilinos
 
-cmake_minimum_required(VERSION 2.7)
+cmake_minimum_required(VERSION 3.17.1)
 
-# Use Trilinos_PREFIX, if the user set it, to help find Trilinos.
-# The final location will actually be held in Trilinos_DIR which must
-# point at "<prefix>/lib/cmake/Trilinos", but this helps the search.
-SET(CMAKE_PREFIX_PATH ${Trilinos_PREFIX} ${CMAKE_PREFIX_PATH})
+# Disable Kokkos warning about not supporting C++ extensions
+set(CMAKE_CXX_EXTENSIONS OFF)
 
 # Get Trilinos as one entity
 FIND_PACKAGE(Trilinos REQUIRED)
@@ -72,4 +70,3 @@ ADD_SUBDIRECTORY(src)
 #Turn on test to be run by ctest
 ENABLE_TESTING()
 ADD_SUBDIRECTORY(test)
-

demos/buildAgainstTrilinos/README.md

@@ -0,0 +1,67 @@
+# Example of building against install Trilinos with CMake
+
+```
+******************************************************************
+*** WARNING: THIS CODE IS NOT AUTOMATICALLY TESTED IN TRILINOS ***
+***          BECAUSE IT REQUIRES AN INSTALLED TRILINOS         ***
+******************************************************************
+```
+
+This is a small demonstration of how to build an application code using CMake
+against an installation of Trilinos.  This example also demonstrates how to
+use CTest.
+
+To run this example, do the following steps.
+
+1. Configure Trilinos to be installed:
+
+```
+  $ cd <any-base-dir>/
+  $ mkdir <tril-build-dir>
+  $ cd <tril-build-dir>/
+  $ cmake \
+    -D CMAKE_INSTALL_PREFIX=<install-prefix> \
+    -D Trilinos_ENABLE_Teuchos=ON \
+    -D Trilinos_ENABLE_Epetra=ON \
+    [other options] \
+    <trilinos-src>
+```
+
+NOTE: Must enable at least the Trilinos packages Teuchos and Epetra in order
+to build this example.  But in a real case, enable and install any packages
+needed by the application.
+
+2. Build and install Trilinos:
+
+```
+  $ make -j4 install
+``
+
+This will put a file under `<install-prefix>/` called `TrilinosConfig.cmake`.
+
+3. Configure the example project:
+
+```
+  $ cd <any--base-dir>/
+  $ mkdir <app-build-dir>
+  $ cd <app-build-dir>/
+  $ cmake \
+    CMAKE_PREFIX_PATH=<install-prefix> \
+    <trilinos-src>/demos/buildAgainstTrilinos
+```
+
+4. Build the application
+
+```
+  $ make -j4
+```
+
+5. Run the application tests:
+
+```
+  $ ctest -j4
+```
+
+Look into comments in the `CMakeLists.txt` files for more info.
+
+Send questions to trilinos-framework@software.sandia.gov.

demos/buildAgainstTrilinos/src/src_file.cpp

@@ -3,8 +3,9 @@
 
 int buildDemo::src_file(std::string& infile, Teuchos::Comm<int>& comm) {
 
+  using Teuchos::inOutArg;
   Teuchos::ParameterList p;
-  Teuchos::updateParametersFromXmlFileAndBroadcast(infile, &p, comm);
+  Teuchos::updateParametersFromXmlFileAndBroadcast(infile, inOutArg(p), comm);
 
   std::cout << "\nProcessor " << comm.getRank()
             << "  has param list : \n" << p << std::endl;