Customizing Parallelware Trainer through environment variables

Starting with version 1.4.0, Parallelware Trainer can be customized using environment variables. This is particularly helpful in deployments using a multi-user license or when certain development packages are installed in non-standard locations (e.g. MPI headers being located in /opt/mpi/include instead of in /usr/include/mpi).

Customizing license file location

When looking for a license file, Parallelware Trainer first checks if the PWT_LICENSE_PATH environment variable is pointing to one. For instance, the following would make Parallelware Trainer use the /opt/licensing/parallelware-trainer.lic license file:

$ export PWT_LICENSE_PATH=/opt/licensing/parallelware-trainer.lic
$ pwtrainer

If the environment variable is not set (or doesn’t point to a file), it will prompt the user to provide one by browsing her filesystem. Note that the environment variable will always take precedence since it can also be overridden by the user.

Customizing default analysis flags

In order for Parallelware Trainer to be able to analyze code, it must be valid. Although Parallelware doesn’t compile code, it is easier to think that it must be compilable to be analyzable. For instance, most C/C++ code includes header files. The code contained in those headers is inserted into the source code. Thus, in the same way header files must be available in order to build the code, Parallelware Trainer needs to have access to those headers in order to analyze source code including them. Although less common, the same may apply to code making use of preprocessor symbols: they must be defined in order for the code to be successfully analyzed.

Parallelware Trainer allows users to supply this information through the Analysis flags setting under Project configuration. These flags follow gcc/clang compiler flags syntax, being -I<header directory> and -D<symbol> the most used by far.

✉ Subscribe! Don’t miss our next blog post.

To make things easier, language-specific default analysis flags can be specified through the following environment variables:

• PWT_C_ANALYSIS_FLAGS
• PWT_CPP_ANALYSIS_FLAGS
• PWT_FORTRAN_ANALYSIS_FLAGS

These analysis flags will be used to analyze source code written in the corresponding programming language along with those specified in the project configuration, if any.

Setting default analysis flags through environment variables can be particularly useful for system administrators who want to free developers from the hassle of having to specify non-standard header locations. One very common example is the location of MPI headers in supercomputers. Let’s suppose that MPI is installed in a non-standard location, such as /global/mpich/include. The following would make Parallelware Trainer to look into that directory when searching for headers such as mpi.h during analyses of C source code:

$ export PWT_C_ANALYSIS_FLAGS=-I/global/mpich/include

Even more, several MPI distributions could be present and it is up to the developer to choose one by loading the appropriate Environment Module. By adding the previous environment variable setting to the corresponding module definition, the proper directory would be set for the user transparently.

GCC include path environment variables

Besides adding -I<header directory> to the analysis flags environment variables or project configuration settings, there is another way to add include paths to Parallelware Trainer analysis.

Parallelware Trainer honors gcc’s include-path related environment variables, namely CPATH, C_INCLUDE_PATH and CPLUS_INCLUDE_PATH. These variables are sometimes set in Environment Modules by taking them into account, Parallelware Trainer automatically benefits from such modules, making header files located in those paths available for analysis.

Example Modulefile

Environment Modules are widely used in supercomputers to easily load programs, development libraries, runtimes, etc. while preparing the proper environment for them which may include for instance loading required dependencies.

The following console dump shows the settings for a pwtrainer module which adds the Parallelware Trainer executable to the path, loads the gcc version 7.3 module, and uses the PWT_LICENSE_PATH and PWT_C_ANALYSIS_FLAGS environment variables to specify the license file and add the include path for OpenMPI:

$ module show pwtrainer
----------------------------------------------------------------------------
/software/Modules/modulefiles/pwtrainer/1.4.0:

module-whatis Parallelware Trainer version 1.4.0
prepend-path  PATH /packages/pwtrainer/1.4.0
module   	  load gcc/7.3
setenv        PWT_LICENSE_PATH /licensing/pwtrainer-1.4.0-multiuser.lic
setenv        PWT_C_ANALYSIS_FLAGS -I/software/openmpi/4.0.1-gcc7.3/include/
----------------------------------------------------------------------------

By loading the module and running Parallelware Trainer, the user should be able to analyze C source code including the mpi.h header and even invoke gcc as the build action for projects: 

$ module load pwtrainer
$ pwtrainer

✉ Subscribe! Code performance tips for your inbox.

---

A word of caution about environment variables

During training sessions, we’ve noticed that many users struggle with their environment variables settings. Typically, the problem comes from a lack of understanding of how environment variables work, particularly the fact that when a program is executed, it inherits the environment from which it was executed.

This means that when you launch Parallelware Trainer, the available environment variables are inherited from the process that executes it. Therefore, setting environment variables from a console outside of Parallelware Trainer after it is launched has no impact on it.

Also, the environment variables’ configuration of a console might differ from that of a graphical environment. Thus, you shouldn’t assume that when you launch Parallelware Trainer through the graphical environment, it will have the same variables available in your console. On the other hand, if you launch Parallelware Trainer from the console, those variables will be inherited; however, further changes you make to them from the console won’t get propagated to Parallelware Trainer.

On a side note, Parallelware Trainer also allows to set custom environment variables through the Advanced project configuration dialog. These will apply to commands executed from Parallelware Trainer such as the build, run and clean commands specified in the project configuration. For instance, this is commonly used to set the number of threads during the execution of OpenMP programs. Note that, as mentioned before, those commands will also inherit the Parallelware Trainer’s environment variables. 

---

More information about these variables is available in the Server installation section of the user manual.