| -v or -verbose | Verbose execution. |
| -d or -debug | Provide debugging information. |
| -h | Print help message. |
| -o \ | Direct pFUnit messages to a file. - |
| -robust | Use the robust runner. Runs tests as processes so failures do not halt testing. |
| -max-timeout-duration | |
| -max-launch-duration | |
| -skip \ | Use the subset runner, which runs a subset of the tests in a suite. |
| -xml \ | Generate XML output in JUnit -compatible format, write it to given file. This XML output can be used -in integration with e.g. Jenkins. To ensure the XML file is written -correctly, it is recommended to also use the -robust flag. |
| -name \ | Give the set of tests an identifying -name, which is used in the XML output. |
Symptom: The system under test compiles and runs fine, but reports zero tests run.
-Solutions: -
testSuites.inc file. Please add a testSuites.inc that lists the suites to add via ADD_TEST_SUITE(the_suite_to_add), one to a line.-DUSE_MPI passed to the compiler during the build. Please add to the compiler invokation. Please see \ref SomeOfMyTestsAreNotRunning.Solutions: -
-DUSE_MPI passed to the compiler during the build. Please add as in the following example.
-\code
-% $PFUNIT/bin/funitproc test_pio.pf test_pio.F90
-% mpif90 -DUSE_MPI $PFUNIT/include/driver.F90 \
-% -I$PFUNIT/mod -L$PFUNIT/lib -lpfunit test_pio.F90
-
-% mpirun -np 8 ./a.out
-
-.
-Time: 0.004 seconds
-
- OK\endcode
--DINTEL_13 is passed to the compiler when building or
-using pFUnit. In the build process for pFUnit, this is added to the
-make variables CPPFLAGS and FPPFLAGS.
-
-\subsection FAQSegAndLinkFaults Segmentation Faults and Odd Link Errors
-
-Q. pFUnit fails to build or now leads to segmentation faults. Did something change?
-
-A. One cause for failure to build or odd runtime segmentation faults is when we change compiler configurations and some object or library files are left over from a previous environment. This might be hard to spot, for example, during compiler upgrades. Switching from one compiler to another, e.g. from Intel to GNU, is more likely to generate link-time errors if old code is still around. A few items to check follow.
-
--DINTEL_13 is passed to the compiler when building or
-using pFUnit. In the build process for pFUnit, this is added to the
-make variables CPPFLAGS and FPPFLAGS.
-
-
-\page page_Acknowledgments Acknowledgments
-
-
-Thanks to the follwing for their review and comments: B. Van Aartsen, T. Clune.
-
-Windows/CYGWIN contributions from E. Lezar.
-
-PGI port contributions from M. Leair (PG Group).
-
-Other acknowledgments: S.P. Santos (NCAR), M. Hambley (UK Met Office)., J. Krishna (ANL).
-
-The design of pFUnit is strongly influenced by JUnit.
-
-Initial pFUnit 2 documentation by Michael Rilee (Rilee Systems Technologies).
-
-
-\page page_KnownInstallationsAndVersions Known Installations & Versions
-
-master - The current release.
-
-development - The cutting edge of pFUnit development.
-
-mock_services - Experimental support for mocking.
-
-pfunit_2.1.0 - A feature freeze prior to a major upgrade of the preprocessor.
-
-\page page_TODO TODO
-
-- Make other directory.
-- Make Environment Modules example in other directory.
-
-\page page_funitproc The Preprocessor - funitproc
-
-Overview of Preprocessor (funitproc)
-
-getParameters
-method of the abstract ParameterizedTest must be implemented. For
-example:
-
-\code
- @Parameters = [p1,p2]
- type, extends(AbstractTestParameter) :: exampleCase
- integer :: i
- real :: x
- end type exampleCase\endcode
-
-\subsubsection s3_atTestCase @TestCase
-
-This directive identifies to the preprocessor the TestCase
-declaration. The type declared at this point extends TestCase (or its
-extension), which includes setting methods such as the following:
-setUp, tearDown, runMethod, userMethod. For the extension
-MPITestCase, as with ParameterizedTestCase, you have the option
-(requirement if parameters are used) to set getParameters and
-getParameterString. For example:
-
-\code
- @TestCase
- type, extends(MPITestCase) :: Test_Parameters
- integer :: p1, p2
- procedure(runMethod), pointer :: userMethod => null()
- contains
- procedure, nopass :: getParameters
- procedure :: getParameterString => getParameterString_
- procedure :: runMethod
- end type Test_Parameters\endcode
-
-\page page_Assert @Assert Preprocessor Directives
-
-Symptom: The system under test compiles and runs fine, but reports zero tests run.
+Solutions: +
testSuites.inc file. Please add a testSuites.inc that lists the suites to add via ADD_TEST_SUITE(the_suite_to_add), one to a line.-DUSE_MPI passed to the compiler during the build. Please add to the compiler invokation. Please see \ref SomeOfMyTestsAreNotRunning.Solutions: +
-DUSE_MPI passed to the compiler during the build. Please add as in the following example.
+\code
+% $PFUNIT/bin/funitproc test_pio.pf test_pio.F90
+% mpif90 -DUSE_MPI $PFUNIT/include/driver.F90 \
+% -I$PFUNIT/mod -L$PFUNIT/lib -lpfunit test_pio.F90
+
+% mpirun -np 8 ./a.out
+
+.
+Time: 0.004 seconds
+
+ OK\endcode
+-DINTEL_13 is passed to the compiler when building or
+using pFUnit. In the build process for pFUnit, this is added to the
+make variables CPPFLAGS and FPPFLAGS.
+
+\subsection FAQSegAndLinkFaults Segmentation Faults and Odd Link Errors
+
+Q. pFUnit fails to build or now leads to segmentation faults. Did something change?
+
+A. One cause for failure to build or odd runtime segmentation faults is when we change compiler configurations and some object or library files are left over from a previous environment. This might be hard to spot, for example, during compiler upgrades. Switching from one compiler to another, e.g. from Intel to GNU, is more likely to generate link-time errors if old code is still around. A few items to check follow.
+
+-DINTEL_13 is passed to the compiler when building or
+using pFUnit. In the build process for pFUnit, this is added to the
+make variables CPPFLAGS and FPPFLAGS.
+
+*/
diff --git a/documentation/pages/revision-notes.dox b/documentation/pages/revision-notes.dox
new file mode 100644
index 00000000..12bb3416
--- /dev/null
+++ b/documentation/pages/revision-notes.dox
@@ -0,0 +1,23 @@
+
+/*!
+
+\page page_RevisionNotes Revision Notes
+
+getParameters
+method of the abstract ParameterizedTest must be implemented. For
+example:
+
+\code
+ @Parameters = [p1,p2]
+ type, extends(AbstractTestParameter) :: exampleCase
+ integer :: i
+ real :: x
+ end type exampleCase
+\endcode
+
+\subsection s3_atTestCase @TestCase
+
+This directive identifies to the preprocessor the TestCase
+declaration. The type declared at this point extends TestCase (or its
+extension), which includes setting methods such as the following:
+setUp, tearDown, runMethod, userMethod. For the extension
+MPITestCase, as with ParameterizedTestCase, you have the option
+(requirement if parameters are used) to set getParameters and
+getParameterString. For example:
+
+\code
+ @TestCase
+ type, extends(MPITestCase) :: Test_Parameters
+ integer :: p1, p2
+ procedure(runMethod), pointer :: userMethod => null()
+ contains
+ procedure, nopass :: getParameters
+ procedure :: getParameterString => getParameterString_
+ procedure :: runMethod
+ end type Test_Parameters
+\endcode
+
+*/
diff --git a/documentation/pages/usage.dox b/documentation/pages/usage.dox
new file mode 100644
index 00000000..63e3f88c
--- /dev/null
+++ b/documentation/pages/usage.dox
@@ -0,0 +1,196 @@
+
+/*!
+
+\page page_Usage Usage
+
+\li \ref sec_UsageConfiguration
+\li \ref sec_CmakeIntegration
+\li \ref sec_UsageHelloWorld
+\li \ref sec_UsagePreprocessor
+\li \ref sec_UsageExecutingTheTest
+
+\section sec_UsageConfiguration Usage - Configuration
+
+For regular use, after installation, the same compiler/MPI development
+configuration that was used to build pFUnit should be used. Once the
+environment variables and paths associated with the environment are
+set, to configure pFUnit, please set the following.
+
+`PFUNIT` - set to the directory into which pFUnit was installed.
+
+`F90_VENDOR` - set to Intel, GNU, NAG, or PGI accordingly.
+
+\section sec_CmakeIntegration Integrating with CMake
+
+Integrating with CMake can be achieved once you have a local version of pFUnit installed with the following code.
+
+\code{cmake}
+# Include pFUnit libraries and CMake functions within your project
+find_package(PFUNIT REQUIRED)
+
+# Enable ctest
+enable_testing()
+
+# Create library for src code
+file(GLOB PROJ_SRC_FILES "${PROJECT_SOURCE_DIR}/src/*.f90")
+add_library (src_lib STATIC ${PROJ_SRC_FILES})
+
+# List all .pf test files
+file(GLOB
+ test_srcs
+ "${PROJECT_SOURCE_DIR}/test/*.pf"
+)
+
+# Filter all tests to only the ones desired for this ctest test
+set(specific_test_files ${test_srcs})
+list(FILTER specific_test_files INCLUDE REGEX ".*test_something_*.pf")
+
+add_pfunit_ctest (test_something_specific # Give your test a name
+ TEST_SOURCES ${specific_test_files} # Specify the .pf files for this test
+ LINK_LIBRARIES src_lib # Link to your src application library
+ )
+\endcode
+
+To include the pFUnit library within the CMake project, we have added the following to the CMakeLists.txt
+
+\code{cmake}
+find_package(PFUNIT REQUIRED)
+\endcode
+
+This will search the CMAKE_PREFIX_PATH for the pFUnit libraries. Therefore, you need to add the pFUnit installed libraries
+to this path. To do this, build your project with the following command, setting any custom CMake flags as needed.
+
+\code{.sh}
+cmake -B build -DCMAKE_PREFIX_PATH=$PFUNIT_INSTALLED_PATH
+\endcode
+
+The ctest test itelf is added via the call to the CMake fucntion provided by pFUnit
+
+\code{cmake}
+add_pfunit_ctest (test_something_specific # Give your test a name
+ TEST_SOURCES ${specific_test_files} # Specify the .pf files for this test
+ LINK_LIBRARIES src_lib # Link to your src application library
+ )
+\endcode
+
+\subsection sec_CmakeIntegrationParallel Enabling MPI parallel testing via CMake
+
+To enable building a parallel pFUnit test with CMake and ctest you must add one extra input into
+the `add_pfunit_ctest` function - `MAX_PES`
+
+\code{cmake}
+add_pfunit_ctest (test_something_specific # Give your test a name
+ TEST_SOURCES ${specific_test_files} # Specify the .pf files for this test
+ LINK_LIBRARIES src_lib # Link to your src application library
+ MAX_PES | -v or -verbose | Verbose execution. |
| -d or -debug | Provide debugging information. |
| -h | Print help message. |
| -o \ | Direct pFUnit messages to a file. + |
| -robust | Use the robust runner. Runs tests as processes so failures do not halt testing. |
| -max-timeout-duration | |
| -max-launch-duration | |
| -skip \ | Use the subset runner, which runs a subset of the tests in a suite. |
| -xml \ | Generate XML output in JUnit +compatible format, write it to given file. This XML output can be used +in integration with e.g. Jenkins. To ensure the XML file is written +correctly, it is recommended to also use the -robust flag. |
| -name \ | Give the set of tests an identifying +name, which is used in the XML output. |
Whitespace. These options are