ExecutableTargetInfo.h

Go to the documentation of this file.

/**
 * @file  ExecutableTargetInfo.h
 * @brief Declaration of ExecutableTargetInfo module.
 *
 * @note The file ExecutableTargetInfo.h is automatically generated by BASIS
 *       from the file ExecutableTargetInfo.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_EXECUTABLETARGETINFO_H
#define _SBIA_BASIS_EXECUTABLETARGETINFO_H


#include <string>
#include <map>


namespace sbia
{

namespace basis
{


/**
 * @brief Provides information about executable build targets.
 *
 * Within source code of a BASIS project, other SBIA executables are called
 * only indirectly using the build target name which must be fixed and unique
 * within the lab. The name of the output executable file of these targets may
 * however vary and be finally set by BASIS, for example, depending on
 * whether the project is build as part of a superproject or not. Therefore,
 * each BASIS CMake function may adjust the output name in order to resolve
 * name conflicts with other targets or SBIA executables.
 *
 * The idea is that a target name is supposed to be stable and known to the
 * developer as soon as the target is added to a CMakeLists.txt file, while
 * the name of the actual executable file is not known a priori as it is set
 * by the BASIS CMake functions during the configure step. Thus, the developer
 * should not rely on a particular name of the executable file. Instead, they
 * can rely on the name of the corresponding build target which was chosen by
 * themselves when adding the target to the build configuration.
 *
 * In order to get the actual file path of the built executable file, the
 * function get_executable_path() is provided by the stdaux.h module.
 * This function uses the static singleton instance of this class in order to
 * map the given build target name to the name of the built and optionally
 * installed executable. The code which initializes the required maps is
 * generated automatically during the configuration of the build system.
 *
 * @note This class is not intended to be subclassed.
 *
 * @sa get_executable_path()
 *
 * @ingroup BasisCxxUtilities
 */
class ExecutableTargetInfo
{
    // -----------------------------------------------------------------------
    // typedefs
private:

    typedef std::map <std::string, std::string> MapType;
    typedef MapType::const_iterator             MapIterator;

    // -----------------------------------------------------------------------
    // construction / destruction
private:

    /**
     * @brief Constructor.
     *
     * Initializes the data members. The initialization code is in particular
     * generated by BASIS during the configuration of the build system.
     */
    ExecutableTargetInfo();

    /// @brief Destructor.
    ~ExecutableTargetInfo();

    // -----------------------------------------------------------------------
    // public interface
public:

    /**
     * @brief Get static instance of this module.
     *
     * @attention This method is not thread-safe!
     *
     * @return Static instance of this class.
     */
    static const ExecutableTargetInfo& instance();

    /**
     * @brief Get UID of build target.
     *
     * In order to be able to distinguish build targets with identical name
     * but which are built as part of different BASIS projects, the UID of
     * a build target is composed of the build target name as given as
     * argument to the basis_add_* CMake functions and a namespace identifier
     * (i.e., the project name in lowercase letters). If the specified build
     * target name is neither known by this module nor a build target UID yet,
     * this method prepends the namespace identifier corresponding to the
     * project this module was built from, assuming that the caller refers
     * to another target within the same project.
     *
     * @param [in] target Name/UID of build target.
     *
     * @returns UID of build target.
     */
    std::string get_target_uid(const std::string& target) const;

    /**
     * @brief Determine whether a given build target is known.
     *
     * @param [in] target Name/UID of build target.
     *
     * @returns Whether the given build target is known by this module.
     */
    bool is_known_target(const std::string& target) const;

    /**
     * @brief Get name of executable file without path.
     *
     * @param [in] target Name/UID of build target.
     *
     * @return Name of built executable file without path.
     */
    std::string get_executable_name(const std::string& target) const;

    /**
     * @brief Get absolute path of output directory of executable in build tree.
     *
     * @param [in] target Name/UID of build target.
     *
     * @return Absolute path of build tree directory where built executable is
     *         located or an empty string if build target is not known.
     */
    std::string get_build_directory(const std::string& target) const;

    /**
     * @brief Get absolute path of directory where built executable is installed.
     *
     * @param [in] target Name/UID of build target.
     *
     * @return Absolute path of executable's installation directory or
     *         an empty string if build target is not known.
     */
    std::string get_installation_directory(const std::string& target) const;

    // -----------------------------------------------------------------------
    // unsupported methods
private:

    /**
     * @brief Copy constructor.
     *
     * @note Intentionally not implemented.
     */
    ExecutableTargetInfo(const ExecutableTargetInfo&);

    /**
     * @brief Assignment operator.
     *
     * @note Intentionally not implemented.
     */
    void operator=(const ExecutableTargetInfo&);

    // -----------------------------------------------------------------------
    // members
private:

    /// Maps build target names to executable file names.
    MapType _exec_names;
    /// Maps build target names to output directories in build tree.
    MapType _build_dirs;
    /// Maps build target names to installation directories relative to
    /// installation prefix as returned by GetInstallationPrefix().
    MapType _install_dirs;

}; // class ExecutableTargetInfo


} // namespace basis

} // namespace sbia


#endif // _SBIA_BASIS_EXECUTABLETARGETINFO_H