program_wrapper.hpp

//--------------------------------------------------------------------------------------------------
// Copyright (c) 2018 Marcus Geelnard
//
// This software is provided 'as-is', without any express or implied warranty. In no event will the
// authors be held liable for any damages arising from the use of this software.
//
// Permission is granted to anyone to use this software for any purpose, including commercial
// applications, and to alter it and redistribute it freely, subject to the following restrictions:
//
//  1. The origin of this software must not be misrepresented; you must not claim that you wrote
//     the original software. If you use this software in a product, an acknowledgment in the
//     product documentation would be appreciated but is not required.
//
//  2. Altered source versions must be plainly marked as such, and must not be misrepresented as
//     being the original software.
//
//  3. This notice may not be removed or altered from any source distribution.
//--------------------------------------------------------------------------------------------------

#ifndef BUILDCACHE_PROGRAM_WRAPPER_HPP_
#define BUILDCACHE_PROGRAM_WRAPPER_HPP_

#include <base/file_utils.hpp>
#include <base/string_list.hpp>
#include <cache/cache.hpp>
#include <cache/expected_file.hpp>
#include <sys/sys_utils.hpp>

#include <string>

namespace bcache {
/// @brief The base class for all program wrappers.
///
/// Specialized program wrappers inherit from this class and implement the relevant virtual methods
/// that constitute the "wrapper API".
///
/// This class also implements the entire program wrapping mechanism, with cache lookups etc.
class program_wrapper_t {
public:
  virtual ~program_wrapper_t() = default;

  /// @brief Try to wrap a program command.
  /// @param[out] return_code The command return code (if handled).
  /// @returns true if the command was recognized and handled.
  bool handle_command(int& return_code);

  /// @brief Check if this class implements a wrapper for the given command.
  /// @returns true if this wrapper can handle the command.
  virtual bool can_handle_command() = 0;

protected:
  /// @brief A helper class for managing wrapper capabilities.
  class capabilities_t {
  public:
    capabilities_t() = default;
    capabilities_t(const string_list_t& cap_strings);

    bool create_target_dirs() const {
      return m_create_target_dirs;
    }

    bool direct_mode() const {
      return m_direct_mode;
    }

    bool hard_links() const {
      return m_hard_links;
    }

  private:
    bool m_create_target_dirs = false;
    bool m_direct_mode = false;
    bool m_hard_links = false;
  };

  // This constructor is called by derived classes.
  program_wrapper_t(const file::exe_path_t& exe_path, const string_list_t& args);

  /// @brief Resolve arguments on the command line.
  ///
  /// This method is called after @c can_handle_command, but before calling other methods that rely
  /// on the command line arguments. This gives a wrapper the opportunity to resolve special
  /// arguments so that they can be properly interpretade by later steps.
  ///
  /// The primary use case of this method is to implement support for so called response files,
  /// which contain further command line arguments (this is common on Windows to work around the
  /// relativlely small command line length limit).
  ///
  /// @throws runtime_error if the request could not be completed.
  virtual void resolve_args();

  /// @brief Generate a list of supported capabilites.
  ///
  /// The list of capabilites can contain zero or more of the following (case sensitive) strings:
  ///
  /// | String             | Meaning                                 |
  /// | ------------------ | --------------------------------------- |
  /// | create_target_dirs | Request creation of missing output dirs |
  /// | direct_mode        | Supports direct mode                    |
  /// | force_direct_mode  | Turns on direct mode for the wrapper    |
  /// | hard_links         | Can use hard links for cached files     |
  ///
  /// In order to support direct mode, @c get_input_files() and @c get_implicit_input_files() need
  /// to be implemented.
  ///
  /// @returns a list of supported capabilites.
  /// @throws runtime_error if the request could not be completed.
  /// @note Capabilites are "opt-in". If this method is not implemented or returns an empty list,
  /// all capabilites will be treated as "not supported".
  virtual string_list_t get_capabilities();

  /// @brief Get the paths to the files that are to be generated by the command.
  /// @returns the files that are expected to be generated by this command.
  /// @throws runtime_error if the request could not be completed.
  virtual std::map<std::string, expected_file_t> get_build_files();

  /// @brief Get a string that uniquely identifies the program.
  /// @returns a program ID string.
  /// @throws runtime_error if the request could not be completed.
  virtual std::string get_program_id();

  /// @brief Get relevant command line arguments for hashing.
  /// @returns filtered command line arguments.
  /// @throws runtime_error if the request could not be completed.
  ///
  /// @note The purpose of this function is to create a list of arguments that is suitable for
  /// hashing (i.e. uniquely identifying) the program options. As such, things like absolute file
  /// paths and compilation defines should be excluded (since they are resolved in the preprocess
  /// step).
  virtual string_list_t get_relevant_arguments();

  /// @brief Get relevant environment variables for hashing.
  /// @returns relevant environment variables and their values.
  /// @throws runtime_error if the request could not be completed.
  ///
  /// @note The purpose of this function is to create a list of environment variables that may
  /// affect program output.
  virtual std::map<std::string, std::string> get_relevant_env_vars();

  /// @brief Get the paths to the input files for the command.
  /// @returns the files that are used as primary input.
  /// @throws runtime_error if the request could not be completed.
  /// @note Only used in direct mode.
  virtual string_list_t get_input_files();

  /// @brief Generate the preprocessed source text.
  /// @returns the preprocessed source code file as a string, or an empty string if the operation
  /// failed.
  /// @throws runtime_error if the request could not be completed.
  virtual std::string preprocess_source();

  /// @brief Get a list of paths to implicit input files.
  ///
  /// This method is only used in direct mode, and the main use case is for collecting a list of
  /// all include files for C/C++ builds.
  /// @returns the list of implicit input files.
  /// @throws runtime_error if the request could not be completed.
  ///
  /// @note The @c preprocess_source method has been called before calling this method (so the list
  /// can be collected during the preprocessing step and later be returned by this method).
  /// @note Only used in direct mode.
  virtual string_list_t get_implicit_input_files();

  /// @brief Run the actual command (when there is a cache miss).
  /// @returns the run result for the child process.
  virtual sys::run_result_t run_for_miss();

  const file::exe_path_t& m_exe_path;
  const string_list_t& m_unresolved_args;
  string_list_t m_args;

  /// @brief Active capabilities
  ///
  /// The capabilities in this object are only active (true) when they are both supported by the
  /// wrapper and are active in the user configuration.
  capabilities_t m_active_capabilities;

private:
  std::string get_program_id_cached();

  cache_t m_cache;
};
}  // namespace bcache

#endif  // BUILDCACHE_PROGRAM_WRAPPER_HPP_