tcov Directories and Environment Variables

When you compile a program for tcov and run the program, the running program generates a profile bucket. If a previous profile bucket exists, the program uses that profile bucket. If a profile bucket does not exist, it creates the profile bucket.

The profile bucket specifies the directory where the profile output is generated. The name and location of the profile output are controlled by defaults that you can modify with environment variables.

tcov uses the same defaults and environment variables that are used by the compiler options that you use to gather profile feedback: -xprofile=collect and -xprofile=use. For more information about these compiler options, see the documentation for your compiler.

The default profile bucket the program creates is named after the executable with a ".profile" extension and is created in the directory where the executable is run. Therefore, if you are in /home/joe, and run a program called /usr/bin/xyz, the default behavior is to create a profile bucket called xyz.profile in /home/joe.

The environment variables that you set to modify the defaults are:

• SUN_PROFDATA

Can be used to specify the name of the profile bucket at runtime. The value of this variable is always appended to the value of SUN_PROFDATA_DIR if both variables are set.

• SUN_PROFDATA_DIR

Can be used to specify the name of the directory containing the profile bucket. It is used at runtime and in the tcov command.

• TCOVDIR

TCOVDIR is supported as a synonym for SUN_PROFDATA_DIR to maintain backward compatibility. Any setting of SUN_PROFDATA_DIR causes TCOVDIR to be ignored. If both SUN_PROFDATA_DIR and TCOVDIR are set, a warning is displayed when the profile bucket is generated.

TCOVDIR is used at runtime by a program compiled with -xprofile=tcov and it is used by the tcov command.

Overriding the Default Definitions

To override the default, use the environment variables to change the profile bucket:

1. Change the name of the profile bucket by using the SUN_PROFDATA environment variable.

2. Change the directory where the profile-bucket is placed by using the SUN_PROFDATA_DIR environment variable.

The environment variables override the default location and name of the profile bucket. Both can be overridden independently. For example, if you only choose to set SUN_PROFDATA_DIR, the profile bucket will go into the directory where you set SUN_PROFDATA_DIR. The default name (which is the executable name followed by a ".profile") will still be the name used for the profile bucket.

Absolute and Relative Pathnames

There are two forms of directories you can specify by using SUN_PROFDATA_DIR on the Profile Feedback compile line: absolute pathnames (which start with a `/'), and relative pathnames. If you use an absolute pathname, the profile bucket is dropped into that directory. If you specify a relative pathname, then it is relative to the current working directory where the executable is being run.

For example, if you are in /home/joe and run a program called /usr/bin/xyz with SUN_PROFDATA_DIR set to .. , then the profile bucket is called /home/joe/../xyz.profile. The value specified in the environment variable was relative, and therefore, it was relative to /home/joe. Also, the default profile bucket name is used, which is named after the executable.

TCOVDIR and SUN_PROFDATA_DIR

The previous version of tcov (enabled by compiling with the -xa or -a flag) used an environment variable called TCOVDIR. TCOVDIR specified the directory where the tcov counter files go to instead of next to the source files. To retain compatibility with this environment variable, the new SUN_PROFDATA_DIR environment variable behaves like the TCOVDIR environment variable. If both variables are set, a warning is output and SUN_PROFDATA_DIR takes precedence over TCOVDIR.

For -xprofile=tcov

By default the profile bucket is called <argv[0]>.profile in the current directory.

If you set SUN_PROFDATA, the profile bucket is called $SUN_PROFDATA, wherever it is located.

If you set SUN_PROFDATA_DIR, the profile bucket is placed in the specified directory.

SUN_PROFDATA and SUN_PROFDATA_DIR are independent. If both are specified, the profile bucket name is generated by using SUN_PROFDATA_DIR to find the profile bucket and, SUN_PROFDATA is used to name the profile bucket in that directory.

A UNIX process can change its current working directory during the execution of a program. The current working directory used to generate the profile bucket is the current working directory of the program at exit. In the rare case where a program actually does change its current working directory during execution, you can use the environment variables to control where the profile bucket is generated.

For the tcov Program

The -xprofile=bucket option specifies the name of the profile bucket to use for the tcov profile. SUN_PROFDATA_DIR or TCOVDIR are prepended to this argument, if they are set.