stdaux.h

Go to the documentation of this file.

/**
 * @file  stdaux.h
 * @brief Standard auxiliary functions.
 *
 * @note The file stdaux.h is automatically generated by BASIS from the
 *       file stdaux.h.in which is part of BASIS.
 *
 * Copyright (c) 2011 University of Pennsylvania. All rights reserved.<br />
 * See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file.
 *
 * Contact: SBIA Group <sbia-software at uphs.upenn.edu>
 */

#pragma once
#ifndef _SBIA_BASIS_STDAUX_H
#define _SBIA_BASIS_STDAUX_H


#include <string>
#include <vector>
#include <iostream>


namespace sbia
{

namespace basis
{


/// @addtogroup BasisCxxUtilities
/// @{


// ===========================================================================
// executable information
// ===========================================================================

/**
 * @brief Print version information.
 *
 * @param [in] name      Program name.
 * @param [in] copyright Copyright notice. Defaults to University of Pennsylvania
 *                       without year if NULL. If an empty string is given,
 *                       i.e., copyright = "", no copyright notice is written.
 * @param [in] license   License notice. Defaults to official software license
 *                       used at SBIA if NULL. If an empty string is given,
 *                       i.e., license = "", no license notice is written.
 */
void print_version(const char* name, const char* copyright = NULL, const char* license = NULL);

/**
 * @brief Print contact information.
 *
 * @param [in] contact Name of the contact. Defaults to
 *                     "SBIA Group <sbia-software at uphs.upenn.edu>".
 */
void print_contact(const char* contact = NULL);

// ===========================================================================
// installation directories
// ===========================================================================

/**
 * @brief Whether the executable was executed from within the build tree.
 *
 * @return Whether the executable was executed from within the build tree.
 */
bool executing_in_build_tree();

/**
 * @brief Get absolute path of installation directory.
 *
 * This function returns the absolute path of the installation prefix path.
 * If the installation was not moved after a "make install", the returned
 * directory corresponds to the value of the INSTALL_PREFIX CMake variable
 * as specified during the build of the executable file. Note, however,
 * that even when the installation tree was moved after the configuration
 * and build of the software, the correct path is returned as long as the
 * relative directory structure of the installation tree is maintained.
 * This is because the path is determined relative to the directory of the
 * executable itself, knowning in which path this executable is located
 * relative to the INSTALL_PREFIX.
 *
 * @note If the executable is executed from within the build tree, the
 *       returned path will not be correct. Therefore, only use this
 *       function when executing_in_build_tree() returns false. Otherwise,
 *       the configured absolute paths which are valid for the build tree
 *       have to be used. Note that the build tree is not supposed to be
 *       relocatable in any case as it is only a temporary directory tree
 *       and CMake requires it to be not moved anywhere else.
 *
 * @return Absolute path of top directory of installation tree.
 */
std::string get_installation_prefix();

/**
 * @brief Get absolute path of directory containing runtime executables.
 *
 * @return Absolute path of directory containing runtime executables.
 */
std::string get_runtime_directory();

/**
 * @brief Get absolute path of directory containing auxiliary executables.
 *
 * @return Absolute path of directory containing auxiliary executables.
 */
std::string get_libexec_directory();

/**
 * @brief Get absolute path of directory containing libraries.
 *
 * @return Absolute path of directory containing libraries.
 */
std::string get_library_directory();

/**
 * @brief Get absolute path of directory containing auxiliary data.
 *
 * @return Absolute path of directory containing auxiliary data.
 */
std::string get_data_directory();

// ===========================================================================
// executable file path of other build targets
// ===========================================================================

/**
 * @brief Get canonical path of executable file.
 *
 * This function uses the static instance of the class ExecutableTargetInfo
 * in order to obtain the required information to be able to determine the
 * absolute path of the executable file which was built and/or installed as
 * the specified build target.
 *
 * @note The BASIS path module provides a function also named get_executable_path()
 *       which can be used to get the canonical path of the calling executable.
 *
 * @sa ExecutableTargetInfo
 *
 * @param [in] target Name/UID of build target.
 *
 * @return Absolute path of executable file or an empty string if the build
 *         target is not known.
 */
std::string get_executable_path(const std::string& target);

// ===========================================================================
// command execution
// ===========================================================================

/**
 * @brief Execute command as subprocess.
 *
 * This function is a replacement for system() on Unix and is furthermore
 * less platform dependent. The first argument of the given command-line string
 * is mapped to an absolute executable file using get_executable_path() if the
 * given first argument is a know build target name. Otherwise, the command-line
 * is used unmodified.
 *
 * @param [in] cmd         Command-line given as double quoted string. Arguments
 *                         containing whitespaces have to be quoted using double
 *                         quotes. Use a backslash (\) to escape double quotes
 *                         inside an argument as well as to escape a backslash
 *                         itself (required if backslash at end of double quoted
 *                         argument, e.g., "this argument \\").
 * @param [in]  quiet      Turns off output of stdout of child process to stdout
 *                         of parent process.
 * @param [out] out        Output stream where command output is written to.
 * @param [in]  allow_fail If true, no exception is thrown if the exit code
 *                         of the child process is non-zero. Otherwise,
 *                         a SubprocessException object is thrown in that case.
 * @param [in]  verbose    Verbosity of output messages. Does not affect
 *                         verbosity of executed command.
 * @param [in]  simulate   Whether to simulate command execution only.
 *
 * @returns Exit code of command or -1 if subprocess creation failed.
 *
 * @throws SubprocessException If subprocess creation failed or command returned
 *                             a non-zero exit code while @p allow_fail is false.
 */
int execute_process(const std::string& cmd,
                    bool               quiet      = false,
                    // attention: stdout is a macro defined by windows.h
                    std::ostream*      out        = NULL,
                    bool               allow_fail = false,
                    int                verbose    = 0,
                    bool               simulate   = false);

/**
 * @brief Execute command as subprocess.
 *
 * This function is a replacement for system() on Unix and is furthermore
 * less platform dependent. The first argument of the given command-line string
 * is mapped to an absolute executable file using get_executable_path() if the
 * given first argument is a know build target name. Otherwise, the command-line
 * is used unmodified.
 *
 * @param [in,out] args       Command-line given as argument vector. The first
 *                            argument has to be either a build target name or the
 *                            name/path of the command to execute. Note that as a
 *                            side effect, the first argument of the input vector
 *                            is replaced by the absolute path of the actual
 *                            executable file if applicable.
 * @param [in]     quiet      Turns off output of stdout of child process to
 *                            stdout of parent process.
 * @param [out]    out        Output stream where command output is written to.
 * @param [in]     allow_fail If true, no exception is thrown if the exit code
 *                            of the child process is non-zero. Otherwise,
 *                            a SubprocessException object is thrown in that case.
 * @param [in]     verbose    Verbosity of output messages. Does not affect
 *                            verbosity of executed command.
 * @param [in]     simulate   Whether to simulate command execution only.
 *
 * @returns Exit code of command or -1 if subprocess creation failed.
 *
 * @throws SubprocessException If subprocess creation failed or command returned
 *                             a non-zero exit code while @p allow_fail is false.
 */
int execute_process(std::vector<std::string>& args,
                    bool                      quiet      = false,
                    // attention: stdout is a macro defined by windows.h
                    std::ostream*             out        = NULL,
                    bool                      allow_fail = false,
                    int                       verbose    = 0,
                    bool                      simulate   = false);


/// @}
// end of Doxygen group


} // namespace basis

} // namespace sbia


#endif // _SBIA_BASIS_STDAUX_H