Merge pull request #1870 from teojgo/doc/pthread_tutorial_option

[doc] Add `-pthread` to the multithreaded tutorial test

Author: Vasileios Karakasis

docs/tutorial_basics.rst

@@ -417,7 +417,7 @@ We extend our C++ "Hello, World!" example to print the greetings from multiple t
    :language: cpp
    :lines: 6-
 
-This program takes as argument the number of threads it will create and it uses ``std::thread``, which is C++11 addition, meaning that we will need to pass ``-std=c++11`` to our compilers.
+This program takes as argument the number of threads it will create and it uses ``std::thread``, which is a C++11 addition, meaning that we will need to pass ``-std=c++11`` to our compilers.
 Here is the corresponding ReFrame test, where the new concepts introduced are highlighted:
 
 .. code-block:: console
@@ -429,12 +429,30 @@ Here is the corresponding ReFrame test, where the new concepts introduced are hi
    :lines: 6-
    :emphasize-lines: 11-13
 
+
+In order to compile applications using ``std::thread`` with GCC and Clang, the ``-pthread`` option has to be passed to the compiler.
+Since the above option might not be valid for other compilers, we use pipeline hooks to differentiate based on the programming environment as follows:
+
+.. code-block:: python
+
+   @rfm.run_before('compile')
+   def set_threading_flags(self):
+       environ = self.current_environ.name
+       if environ in {'clang', 'gnu'}:
+           self.build_system.cxxflags += ['-pthread']
+
+
+.. note::
+
+   The pipeline hooks, as well as the regression test pipeline itself, are covered in more detail later on in the tutorial.
+
+
 ReFrame delegates the compilation of a test to a *build system*, which is an abstraction of the steps needed to compile the test.
 Build systems take also care of interactions with the programming environment if necessary.
 Compilation flags are a property of the build system.
 If not explicitly specified, ReFrame will try to pick the correct build system (e.g., CMake, Autotools etc.) by inspecting the test resources, but in cases as the one presented here where we need to set the compilation flags, we need to specify a build system explicitly.
-In this example, we instruct ReFrame to compile a single source file using the ``-std=c++11 -Wall`` compilation flags.
-Finally, we set the arguments to be passed to the generated executable in :attr:`~reframe.core.pipeline.RegressionTest.executable_opts`.
+In this example, we instruct ReFrame to compile a single source file using the ``-std=c++11 -pthread -Wall`` compilation flags.
+Finally, we set the arguments to be passed to the generated executable in :attr:`executable_opts <reframe.core.pipeline.RegressionTest.executable_opts>`.
 
 
 .. code-block:: console
@@ -1075,7 +1093,7 @@ Let's see and comment the changes:
 First of all, we need to add the new programming environments in the list of the supported ones.
 Now there is the problem that each compiler has its own flags for enabling OpenMP, so we need to differentiate the behavior of the test based on the programming environment.
 For this reason, we define the flags for each compiler in a separate dictionary (``self.flags``) and we set them in the :func:`setflags` pipeline hook.
-Let's explain what is this all about.
+We have first seen the pipeline hooks in the multithreaded "Hello, World!" example and now we explain them in more detail.
 When ReFrame loads a test file, it instantiates all the tests it finds in it.
 Based on the system ReFrame runs on and the supported environments of the tests, it will generate different test cases for each system partition and environment combination and it will finally send the test cases for execution.
 During its execution, a test case goes through the *regression test pipeline*, which is a series of well defined phases.

tutorials/basics/hellomp/hellomp1.py

@@ -17,3 +17,9 @@ def __init__(self):
         self.build_system.cxxflags = ['-std=c++11', '-Wall']
         self.executable_opts = ['16']
         self.sanity_patterns = sn.assert_found(r'Hello, World\!', self.stdout)
+
+    @rfm.run_before('compile')
+    def set_threading_flags(self):
+        environ = self.current_environ.name
+        if environ in {'clang', 'gnu'}:
+            self.build_system.cxxflags += ['-pthread']

tutorials/basics/hellomp/hellomp2.py

@@ -19,3 +19,9 @@ def __init__(self):
         num_messages = sn.len(sn.findall(r'\[\s?\d+\] Hello, World\!',
                                          self.stdout))
         self.sanity_patterns = sn.assert_eq(num_messages, 16)
+
+    @rfm.run_before('compile')
+    def set_threading_flags(self):
+        environ = self.current_environ.name
+        if environ in {'clang', 'gnu'}:
+            self.build_system.cxxflags += ['-pthread']

tutorials/basics/hellomp/hellomp3.py

@@ -20,3 +20,9 @@ def __init__(self):
         num_messages = sn.len(sn.findall(r'\[\s?\d+\] Hello, World\!',
                                          self.stdout))
         self.sanity_patterns = sn.assert_eq(num_messages, 16)
+
+    @rfm.run_before('compile')
+    def set_threading_flags(self):
+        environ = self.current_environ.name
+        if environ in {'clang', 'gnu'}:
+            self.build_system.cxxflags += ['-pthread']