basis.h

Go to the documentation of this file.

/**
 * @file  basis.h
 * @brief BASIS utilities of BASIS project of BASIS package.
 *
 * @note The basis.h module was automatically generated by BASIS from the
 *       template file basis.h.in which is part of the BASIS installation.
 *
 * This header file includes the header files of the remaining BASIS utilities.
 * Hence, it is sufficient to only include this header file.
 *
 * Copyright (c) 2011, 2012 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>
 *
 * @ingroup BasisCxxUtilities
 */

#pragma once
#ifndef _BASIS_BASIS_BASIS_H
#define _BASIS_BASIS_BASIS_H

#include <basis/utilities.h> // project-independent utilities


/// @addtogroup BasisCxxUtilities
/// @{


namespace basis {


// ===========================================================================
// constants
// ===========================================================================

/// @brief The project name.
extern const char* PROJECT;
/// @brief The version string given as "<major>.<minor>.<patch>".
extern const char* VERSION;
/// @brief The major version number.
extern const unsigned int VERSION_MAJOR;
/// @brief The minor version number.
extern const unsigned int VERSION_MINOR;
/// @brief The patch number.
extern const unsigned int VERSION_PATCH;
/// @brief Complete version information as output by --version option.
extern const char* RELEASE;
/// @brief Default copyright of executables.
extern const char* COPYRIGHT;
/// @brief Default license of executables.
extern const char* LICENSE;
/// @brief Default contact to use for help output of executables.
extern const char* CONTACT;

// ===========================================================================
// package directories
// ===========================================================================

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

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

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

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

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

/**
 * @brief Print contact information.
 *
 * @param [in] contact Name of contact. If @c NULL, CONTACT is used.
 */
void print_contact(const char* contact = NULL);

/**
 * @brief Print version information including copyright and license notices.
 *
 * @param [in] name      Name of executable. Should not be set programmatically
 *                       to the first argument of the @c main() function, but
 *                       a string literal instead.
 * @param [in] version   Version of executable, e.g., release of project
 *                       this executable belongs to. Defaults to RELEASE.
 * @param [in] project   Name of project this executable belongs to.
 *                       If @c NULL, defaults to PROJECT. If an empty string,
 *                       no project information is printed.
 * @param [in] copyright The copyright notice, excluding the common prefix
 *                       "Copyright (c) " and suffix ". All rights reserved.".
 *                       If @c NULL, COPYRIGHT is used. If an empty string,
 *                       no copyright notice is printed.
 * @param [in] license   Information regarding licensing. If @c NULL, LICENSE
 *                       is used. If an empty string, no license information
 *                       is printed.
 */
void print_version(const char* name,
                   const char* version   = NULL,
                   const char* project   = NULL,
                   const char* copyright = NULL,
                   const char* license   = NULL);

/**
 * @brief Get UID of build target.
 *
 * The UID of a build target is its name prepended by a namespace identifier
 * which should be unique for each project.
 *
 * @param [in] name Name of build target.
 *
 * @returns UID of named build target.
 */
std::string targetuid(const std::string& name);

/**
 * @brief Determine whether a given build target is known.
 *
 * @param [in] name Name of build target.
 *
 * @returns Whether the named target is a known executable target.
 */
bool istarget(const std::string& name);

/**
 * @brief Get absolute path of executable file.
 *
 * This function determines the absolute file path of an executable. If no
 * arguments are given, the absolute path of this executable is returned.
 * If the command names a known executable build target, the absolute path to
 * the corresonding built (and installed) executable file is returned.
 * Otherwise, the named command is searched in the system @c PATH and its
 * absolute path returned if found. If the executable is not found, an
 * empty string is returned.
 *
 * @todo This function currently makes use of the which command implemented
 *       in Python and called as subprocess in order to search a command
 *       in the system @c PATH. This which command is part of BASIS and
 *       can also be used on Windows. However, a native C++ implementation
 *       would be desireable.
 *
 * @param [in] name Name of command or @c NULL.
 *
 * @returns Absolute path of executable or an empty string if not found.
 *          If @p name is @c NULL, the path of this executable is returned.
 *
 * @sa exename()
 * @sa exedir()
 */
std::string exepath(const std::string& name = std::string());

/**
 * @brief Get name of executable file.
 *
 * @note The name of the executable may or may not include the file name
 *       extension depending on the executable type and operating system.
 *       Hence, this function is neither an equivalent to
 *       os::path::basename(exepath()) nor os::path::filename(exepath()).
 *       In particular, on Windows, the .exe and .com extension is not
 *       included in the returned executable name.
 *
 * @param [in] name Name of command or @c NULL.
 *
 * @returns Name of executable file or an empty string if not found.
 *          If @p name is @c NULL, the name of this executable is returned.
 *
 * @sa exepath()
 */
std::string exename(const std::string& name = std::string());

/**
 * @brief Get directory of executable file.
 *
 * @param [in] name Name of command or @c NULL.
 *
 * @returns Absolute path of directory containing executable or an empty string if not found.
 *          If @p name is @c NULL, the directory of this executable is returned.
 *
 * @sa exepath()
 */
std::string exedir(const std::string& name = std::string());

// ===========================================================================
// 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 exepath() 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 SubprocessError If subprocess creation failed or command returned
 *                         a non-zero exit code while @p allow_fail is false.
 */
int execute(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 exepath() 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.
 * @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 SubprocessError If subprocess creation failed or command returned
 *                         a non-zero exit code while @p allow_fail is false.
 */
int execute(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 namespaces


/// @}
// end of Doxygen group


#endif // _BASIS_BASIS_BASIS_H