path: root/build2/algorithm

// file      : build2/algorithm -*- C++ -*-
// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

#ifndef BUILD2_ALGORITHM
#define BUILD2_ALGORITHM

#include <build2/types>
#include <build2/utility>

#include <build2/target>
#include <build2/operation>

namespace build2
{
  class scope;
  class prerequisite;
  class prerequisite_key;

  // The default prerequisite search implementation. It first calls the
  // target-type-specific search function. If that doesn't yeld anything,
  // it creates a new target.
  //
  target&
  search (prerequisite&);

  // As above but specify the prerequisite to search as a key.
  //
  target&
  search (const prerequisite_key&);

  // As above but override the target type. Useful for searching for
  // target group members where we need to search for a different
  // target type.
  //
  target&
  search (const target_type&, const prerequisite_key&);

  // As above but specify the prerequisite to search as individual key
  // components. Scope can be NULL if the directory is absolute.
  //
  target&
  search (const target_type& type,
          const dir_path& dir,
          const dir_path& out,
          const string& name,
          const string* ext,
          scope*);

  // As above but specify the target type as template argument.
  //
  template <typename T>
  T&
  search (const dir_path& dir,
          const dir_path& out,
          const string& name,
          const string* ext,
          scope*);

  // Search for a target identified by the name. The semantics
  // is "as if" we first created a prerequisite based on this
  // name in exactly the same way as the parser would and then
  // searched based on this prerequisite.
  //
  target&
  search (name, scope&);

  // Match and apply a rule to the action/target with ambiguity
  // detection. Increment the target's dependents count, which
  // means that you should call this function with the intent
  // to also call execute(). In case of optimizations that would
  // avoid calling execute(), call unmatch() to indicate this.
  //
  void
  match (action, target&);

  // Note that calling this function only makes sense if the
  // target itself doesn't have its own dependents.
  //
  void
  unmatch (action, target&);

  // Match (but do not apply) a rule to the action/target with
  // ambiguity detection. Note that this function does not touch
  // the dependents count.
  //
  void
  match_only (action, target&);

  // Match a "delegate rule" from withing another rules' apply() function
  // skipping recursive matches (thus the third argument). Return recipe and
  // recipe action (if any). Note that unlike match(), this call doesn't
  // increment the dependents count. See also the companion
  // execute_delegate().
  //
  pair<recipe, action>
  match_delegate (action, target&, const rule&);

  // The standard prerequisite search and match implementations. They call
  // search_and_match_*() versions below passing non-empty directory for
  // the clean operation.
  //
  void
  search_and_match_prerequisites (action, target&);

  // If we are cleaning, this function doesn't go into group members,
  // as an optimization (the group should clean everything up).
  //
  void
  search_and_match_prerequisite_members (action, target&);

  // The actual prerequisite search and match implementations. They call
  // search() and then match() for each prerequisite in a loop. If this
  // target is a member of a group, then they first do this to the group's
  // prerequisites.
  //
  // If the directory argument is not empty, then they ignore (do not
  // match) prerequisites that are not in the same or its subdirectory.
  //
  void
  search_and_match_prerequisites (action, target&, const dir_path&);

  void
  search_and_match_prerequisite_members (action, target&, const dir_path&);

  // Unless already available, match, and, if necessary, execute the group
  // in order to obtain its members list. Note that even after that the
  // member's list might still not be available (e.g., if some wildcard/
  // fallback rule matched).
  //
  group_view
  resolve_group_members (action, target&);

  // Inject dependency on the target's directory fsdir{}, unless it is in the
  // src tree, root of the project, or is outside of any project (say, for
  // example, an installation directory). If the parent argument is true, then
  // inject the parent directory of a target that is itself a directory (name
  // is empty). Return the injected target or NULL. Normally this function is
  // called from the rule's apply() function.
  //
  fsdir*
  inject_fsdir (action, target&, bool parent = true);

  // Execute the action on target, assuming a rule has been matched
  // and the recipe for this action has been set. This is the default
  // executor implementation. Decrements the dependents count.
  //
  target_state
  execute (action, target&);

  // Execute the recipe obtained with match_delegate(). Note that
  // the target's state is neither checked nor updated by this
  // function. In other words, the appropriate usage is to call
  // this function from another recipe and to factor the obtained
  // state into the one returned.
  //
  target_state
  execute_delegate (const recipe&, action, target&);

  // A special version of the above that should be used for "direct"
  // and "now" execution, that is, side-stepping the normal target-
  // prerequisite relationship (so no dependents count is decremented)
  // and execution order (so this function will never return postponed
  // target state).
  //
  target_state
  execute_direct (action, target&);

  // The default prerequisite execute implementation. It calls execute()
  // on each non-ignored (non-NULL) prerequisite target in a loop. If this
  // target is a member of a group, then it first does this to the group's
  // prerequisites. Returns target_state::changed if any of them were
  // changed and target_state::unchanged otherwise. Note that this
  // function can be used as a recipe.
  //
  target_state
  execute_prerequisites (action, target&);

  // As above but iterates over the prerequisites in reverse.
  //
  target_state
  reverse_execute_prerequisites (action, target&);

  // A version of the above that also determines whether the action
  // needs to be executed on the target based on the passed mtime
  // timestamp.
  //
  // Note that because we use mtime, this function should normally
  // only be used in the perform_update action.
  //
  bool
  execute_prerequisites (action, target&, const timestamp&);

  // Another version of the above that does two extra things for the caller:
  // it determines whether the action needs to be executed on the target based
  // on the passed timestamp and, if so, finds a prerequisite of the specified
  // type (e.g., a source file). If there are multiple prerequisites of this
  // type, then the first is returned (this can become important if additional
  // prerequisites of the same type may get injected).
  //
  template <typename T>
  T*
  execute_prerequisites (action, target&, const timestamp&);

  target*
  execute_prerequisites (const target_type&,
                         action, target&, const timestamp&);

  template <typename T>
  T*
  execute_prerequisites (const target_type&,
                         action, target&, const timestamp&);

  // Return noop_recipe instead of using this function directly.
  //
  target_state
  noop_action (action, target&);

  // Default action implementation which forwards to the prerequisites.
  // Use default_recipe instead of using this function directly.
  //
  target_state
  default_action (action, target&);

  // Standard perform(clean) action implementation for the file target
  // (or derived).
  //
  target_state
  perform_clean (action, target&);

  // As above, but also removes the auxiliary dependency database (.d file).
  //
  target_state
  perform_clean_depdb (action, target&);

  // Helper for custom perform(clean) implementations that cleans extra files
  // and directories (recursively) specified as a list of either absolute
  // paths or "path derivation directives". The directive string can be NULL,
  // or empty in which case it is ignored. If the last character in a
  // directive is '/', then the resulting path is treated as a directory
  // rather than a file.  The directive can start with zero or more '-'
  // characters which indicate the number of extensions that should be
  // stripped before the new extension (if any) is added (so if you want to
  // strip the extension, specify just "-"). For example:
  //
  // clean_extra (a, t, {".d", ".dlls/", "-.dll"});
  //
  // The extra files/directories are removed first in the specified order
  // followed by the ad hoc group member, then target itself, and, finally,
  // the prerequisites in the reverse order.
  //
  // You can also clean extra files derived from adhoc group members.
  //
  target_state
  clean_extra (action, file&,
               initializer_list<initializer_list<const char*>> extra);

  inline target_state
  clean_extra (action a, file& f, initializer_list<const char*> extra)
  {
    return clean_extra (a, f, {extra});
  }
}

#include <build2/algorithm.ixx>

#endif // BUILD2_ALGORITHM