taucmdr.cf.software.tau_installation module

TAU software installation management.

TAU is the core software package of TAU Commander.

class taucmdr.cf.software.tau_installation.TauInstallation(sources, target_arch, target_os, compilers, minimal=False, application_linkage='dynamic', openmp_support=False, pthreads_support=False, tbb_support=False, mpi_support=False, mpi_libraries=None, openacc_support=False, caf_support=False, cuda_support=False, cuda_prefix=None, opencl_support=False, opencl_prefix=None, shmem_support=False, shmem_libraries=None, mpc_support=False, uses_python=False, source_inst='never', compiler_inst='never', keep_inst_files=False, reuse_inst_files=False, select_file=None, baseline=False, profile='tau', trace='none', sample=False, metrics=None, measure_io=False, measure_mpi=False, measure_openmp='ignore', measure_opencl=False, measure_cuda=False, measure_level_zero=False, measure_shmem=False, measure_heap_usage=False, measure_system_load=False, measure_memory_alloc=False, measure_comm_matrix=False, measure_callsite=False, callpath_depth=100, throttle=True, metadata_merge=True, throttle_per_call=10, throttle_num_calls=100000, sample_resolution='line', sampling_period=0, track_memory_footprint=False, update_nightly=False, ptts=False, ptts_post=False, ptts_sample_flags=None, ptts_restart=False, ptts_start=None, ptts_stop=None, ptts_report_flags=None, tags=None, forced_makefile=None, dyninst=False, mpit=False, unwinder='libunwind', unwind_depth=0)

Bases: Installation

Encapsulates a TAU installation.

TAU is an enormous, organic, complex piece of software so this class is unusually complex to consider all the corner cases. This is where most of the systemization of TAU is actually implemented so it can get ugly.

_check_X11()

_check_java()

_compiler_tags()

_configure_sets_ompt_header()

Returns True if TAU’s configure copies omp-tools.h from an OMPT directory into its tree.

TAU 2.35.2 and earlier nightlies never set ompt_header, so they don’t copy the header and need -I<ompt prefix>/include to compile their OMPT support.

_find_cupti_prefix()

Find the CUPTI installation directory within the CUDA toolkit.

Checks the same paths that TAU’s configure script checks when auto-detecting CUPTI from a -cuda=<dir> argument.

Returns:

Path to the CUPTI base directory, or None if not found.

Return type:

str

_get_install_tag()

_get_max_metrics()

_incompatible_tags()

Returns a set of makefile tags incompatible with the specified config.

_links_system_libunwind()

Returns True if TAU’s configure links macOS’s libunwind for this TAU architecture.

_makefile_tags(makefile)

_match_makefile(config_tags)

_newest_nightly(src_dir)

Find the newest TAU nightly archive in src_dir, after downloading a new one if updating.

Returns:

(path to the archive, its date as YYYY-MM-DD).

Return type:

tuple

_ompt_prefix()

Returns the OMPT installation prefix passed to TAU’s configure.

Returns None if OMPT is not enabled, or if TAU uses the compiler’s own OMPT runtime (Intel 19 and later).

_prep_data_analysis_tools()

Checks that data analysis tools are installed, or installs them if needed.

_requests_pthread()

_rewrite_launcher_appfile_cmd(cmd, tau_exec)

static _sanitize_environment(env)

Unsets any TAU environment variables that were set by the user.

A user’s preexisting TAU configuration may conflict with the configuration specified by the TAU Commander project. This routine lets us work in a clean environment without disrupting the user’s shell environment.

Parameters:

env (dict) – Environment variables.

Returns:

env without TAU environment variables.

Return type:

dict

_select_flags(header, libglobs, user_libraries, wrap_cc, wrap_cxx, wrap_fc)

_show_jumpshot(fmt, paths, env)

_show_paraprof(fmt, paths, env)

_show_pprof(fmt, paths, env)

_show_unknown(tool)

_show_vampir(fmt, paths, env)

_unwind_flags(libunwind)

Returns TAU’s configure options for the stack unwinder.

_useropts()

_verify_dependency_paths(tau_makefile)

_verify_iowrapper(tau_makefile)

_verify_tau_libs(tau_makefile)

classmethod check_env_compat()

Checks the current shell environment for incompatible libraries or modules.

Other instrumentation packages like Darshan can conflict with TAU. This routine checks that no conflicting packages are active in the current environment.

Raises:

ConfigurationError – TAU cannot be used in the current environment.

compile(compiler, compiler_args)

Executes a compilation command.

Sets TAU environment variables and configures TAU compiler wrapper command line arguments to match specified configuration, then executes the compiler command.

Parameters:

• compiler (InstalledCompiler) – A compiler command.

• compiler_args (list) – Compiler command line arguments.

Raises:

ConfigurationError – Compilation failed.

Returns:

Compiler return value (always 0 if no exception raised).

Return type:

int

compiletime_config(compiler, opts=None, env=None)

Configures environment for compilation with TAU.

Modifies incoming command line arguments and environment variables for the TAU compiler wrapper scripts.

Parameters:

• opts (list) – Command line options.

• env (dict) – Environment variables.

Returns:

(opts, env) updated to support TAU.

Return type:

tuple

configure()

Configures TAU

Executes TAU’s configuration script with appropriate arguments to support the specified configuration.

Raises:

SoftwareConfigurationError – TAU’s configure script failed.

create_ppk_file(dest, src, remove_existing=True)

Write a PPK file at dest from the data at src.

Parameters:

• dest (str) – Path to the PPK file to create.

• src (str) – Directory containing TAU profiles to convert to PPK format.

• remove_existing (bool) – If True, delete dest before writing it.

get_application_command(launcher_cmd, application_cmds)

Build a command line to launch an application under TAU.

Sometimes TAU needs to use tau_exec, sometimes not. This routine also handles backend launch commands like aprun.

application_cmds may be an empty list if the application is launched via a configuration file, e.g. mpirun --app myapp.cfg.

Parameters:

• launcher_cmd (list) – Application launcher with command line arguments, e.g. ['mpirun', '-np', '4'].

• application_cmds (list) – List of application command with command line arguments (list of list), e.g. [['./a.out', '-g', 'hello'], [':', '-np', '2', './b.out', 'foobar']]

Returns:

(cmd, env) where cmd is the new command line and env is a dictionary of environment

variables to set before running the application command.

Return type:

tuple

get_compiler_command(compiler)

Get the compiler wrapper command for the given compiler.

Parameters:

compiler (InstalledCompiler) – A compiler to find a wrapper for.

Returns:

Command for TAU compiler wrapper without path or arguments.

Return type:

str

static get_data_format(path)

Guess the data format of a file path.

Look at a file’s extension and guess what kind of performance data it might be.

Parameters:

path (str) – File path.

Returns:

String indicating the data format.

Return type:

str

Raises:

ConfigurationError – Cannot determine the file’s data format.

get_makefile()

Returns an absolute path to a TAU_MAKEFILE.

The file returned should supply all requested measurement features and application support features specified in the constructor.

Returns:

A file path that could be used to set the TAU_MAKEFILE environment

variable, or None if a suitable makefile couldn’t be found.

Return type:

str

classmethod get_minimal()

Creates a minimal TAU configuration for working with legacy data analysis tools.

Returns:

Object handle for the TAU installation.

Return type:

TauInstallation

get_python_version(python_path)

static get_shared_dir(tau_makefile)

Get the shared library directory that corresponds to a given TAU Makefile

Parameters:

tau_makefile (str) – path to a TAU Makefile

Returns:

the path to a TAU shared library directory containing the shared libraries that would be used by the TAU configuration represented by the Makefile.

Return type:

str

get_tags()

Get tags for this TAU installation.

Each TAU configuration (makefile, library, Python bindings, etc.) is identified by its tags. Tags can appear in the makefile name in any order so the order of the tags returned by this function will likely not match the order they appear in the makefile name or tau_exec command line.

Returns:

Makefile tags, e.g. set(‘papi’, ‘pdt’, ‘icpc’)

Return type:

set

install(force_reinstall=False)

Installs TAU.

Configures, compiles, and installs TAU with all necessary makefiles and libraries.

Parameters:

force_reinstall (bool) – Set to True to force reinstall even if TAU is already installed and working.

Raises:

SoftwarePackageError – TAU failed installation or did not pass verification after it was installed.

installation_sequence()

static is_profile_format(fmt)

Return True if fmt is a string indicating a profile data format.

static is_trace_format(fmt)

Return True if fmt is a string indicating a trace data format.

make_install()

Installs TAU to self.install_prefix.

Executes ‘make install’ to build and install TAU.

Raises:

SoftwarePackageError – ‘make install’ failed.

make_install_minimal()

Build and install only the TraceInput library and TAU utilities.

Unlike make_install(), this does not compile all of TAU. Utility build failures are ignored since only a subset may be needed.

merge_tau_trace_files(prefix)

Use tau_treemerge.pl to merge multiple TAU trace files into a single edf and a single trc file.

The new edf file and trc file are written to prefix.

Parameters:

prefix (str) – Path to the directory containing *.trc and *.edf files.

rewrite(rewrite_package, executable, inst_file)

Use a binary rewriting tool to instrument an executable.

Parameters:

• rewrite_package (str) – Rewriting backend (‘dyninst’, ‘pebil’, or ‘maqao’).

• executable (str) – Path to the executable to instrument.

• inst_file (str) – Path for the instrumented output file.

Raises:

ConfigurationError – The rewriting tool failed to instrument the executable.

runtime_config(opts=None, env=None)

Configures environment for execution with TAU.

Modifies incoming command line arguments and environment variables for the TAU library and tau_exec script.

Parameters:

• opts (list) – Command line options.

• env (dict) – Environment variables.

Returns:

(opts, env) updated to support TAU.

Return type:

tuple

show_data_files(dataset, profile_tools=None, trace_tools=None)

Displays profile and trace data.

Opens one more more data analysis tools to display the specified data files.

Parameters:

• dataset (dict) – Lists of paths to data files indexed by data format. See get_data_format.

• profile_tools (list) – Visualization or data processing tools for profiles.

• trace_tools (list) – Visualization or data processing tools for traces.

Raises:

ConfigurationError – An error occurred while displaying a data file.

tau_metrics()

List TAU metrics available on this target.

Returns a list of (name, description) tuples.

Returns:

List of event name/description tuples.

Return type:

list

tau_trace_to_slog2(trc, edf, slog2)

Convert a TAU trace file to SLOG2 format.

Parameters:

• trc (str) – Path to the trc file.

• edf (str) – Path to the edf file.

• slog2 (str) – Path to the slog2 file to create.

uid_items()

List items affecting this installation’s UID.

Most packages only care about changes in source archive, target, or C/C++ compilers. More sensitive packages (e.g. Score-P or TAU) can override this function.

Returns:

An ordered list of items affecting this installation’s UID.

Changing the order of this list will change the UID.

Return type:

list

verify()

Check if the installation at install_prefix is valid.

A valid installation provides all expected files and commands. Subclasses may wish to perform additional checks.

Raises:

SoftwarePackageError – Describes why the installation is invalid.

taucmdr.cf.software.tau_installation._dated_nightlies(src_dir)

taucmdr.cf.software.tau_installation.complete_nightly_names(src_dir)

Give dated names to each TAU nightly archive in src_dir and link tau-nightly.tgz to the newest.

Parameters:

src_dir (str) – A storage level’s source archive directory.

Returns:

Names of the files created or replaced.

Return type:

list

Raises:

OSError – src_dir couldn’t be changed.

taucmdr.cf.software.tau_installation.dated_nightly_name(archive)

Return the dated name for a TAU nightly archive.

Parameters:

archive (str) – Path to the archive.

Returns:

tau-nightly-<YYYY-MM-DD>.tgz.

Return type:

str

taucmdr.cf.software.tau_installation.python_build_paths(python_path)

Find the C header and libpython directories of a Python interpreter.

TAU’s Python support compiles against the interpreter’s headers and links against its libpython.

Parameters:

python_path (str) – Absolute path to a Python interpreter.

Returns:

(include_dir, lib_dir).

Return type:

tuple

Raises:

ConfigurationError – The interpreter has no C headers, or its libpython couldn’t be found.

taucmdr.cf.software.tau_installation.tau_install_layout(path: str) → tuple[str, str]

Find the TAU installation that a file in its bin or lib directory belongs to.

TAU installs its files as <prefix>/<arch>/bin/* and <prefix>/<arch>/lib/*, e.g. its makefiles as <prefix>/<arch>/lib/Makefile.tau-*. Links are resolved first, so a file given through a link, like the <prefix>/bin and <prefix>/lib that Spack adds, is found in its real <arch> directory. <arch> is usually the TAU architecture, but TAU’s -exec-prefix option can rename it.

Parameters:

path (str) – Path to a file in a TAU installation’s bin or lib directory, e.g. a TAU makefile.

Returns:

The installation prefix and the name of its <arch> directory.

Return type:

tuple

taucmdr.cf.software.tau_installation.tau_makefile_arch(makefile: str) → str | None

Return the TAU architecture a TAU makefile was configured for (its TAU_ARCH), or None if it’s not set.

taucmdr.cf.software.tau_installation.tau_makefile_target(makefile: str) → dict[str, str | None]

Find the target configuration a TAU makefile was built for.

Parameters:

makefile (str) – Path to a TAU makefile.

Raises:

ConfigurationError – The makefile can’t be read, its TAU_ARCH is missing, unknown, or ambiguous, or a compiler it names is found but can’t be identified. A compiler that isn’t found is skipped instead.

Returns:

Target attribute values by attribute name: the host architecture and OS, the TAU installation, and the compilers (with any compilers they wrap) and package directories the makefile names.

Return type:

dict