// file : build2/algorithm -*- C++ -*- // copyright : Copyright (c) 2014-2017 Code Synthesis Ltd // license : MIT; see accompanying LICENSE file #ifndef BUILD2_ALGORITHM #define BUILD2_ALGORITHM #include #include #include #include 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, // NULL means unspecified. const scope*, const optional& proj = nullopt); // As above but specify the target type as template argument. // template T& search (const dir_path& dir, const dir_path& out, const string& name, const string* ext, const 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, const scope&); // As above but only search for an already existing target. Unlike the // above version, this one can be called during the execute phase. // // Note that currently we return NULL for project-qualified names and // unknown target types. // const target* search_existing (const name&, const scope&, const dir_path& out = dir_path ()); // 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 (slock&, 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 (slock&, 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 match_delegate (slock&, action, target&, const rule&); // The standard prerequisite search and match implementations. They call // search() and then match() for each prerequisite in a loop omitting out of // project prerequisites for the clean operation. If this target is a member // of a group, then they first do this to the group's prerequisites. // void search_and_match_prerequisites (slock&, 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 (slock&, action, target&); // As above but omit prerequisites that are not in the specified scope. // void search_and_match_prerequisites (slock&, action, target&, const scope&); void search_and_match_prerequisite_members ( slock&, action, target&, const scope&); // 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 (slock&, action, target&); // Inject dependency on the target's directory fsdir{}, unless it is in the // src tree 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 (slock&, 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 synchrounous executor // implementation (but may still return target_state::busy is the target // is already being executed). Decrements the dependents count. // target_state execute (action, const target&); // As above but start asynchronous execution. Return target_state::unknown // if the asynchrounous execution has been started and target_state::busy if // the target has already been busy. // target_state execute_async (action, const target&, size_t start_count, atomic_count& task_count); // 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, const 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). It will also // wait for the completion if the target is busy. // target_state execute_direct (action, const target&); // The default prerequisite execute implementation. Call execute_async() on // each non-ignored (non-NULL) prerequisite target in a loop and then wait // for their completion. Return target_state::changed if any of them were // changed and target_state::unchanged otherwise. If a prerequisite's // execution is postponed, then set its pointer in prerequisite_targets to // NULL (since its state cannot be queried MT-safely). // // Note that this function can be used as a recipe. // target_state execute_prerequisites (action, const target&); // As above but iterates over the prerequisites in reverse. // target_state reverse_execute_prerequisites (action, const target&); // A version of the above that also determines whether the action needs to // be executed on the target based on the passed timestamp and filter. // // The filter is passed each prerequisite target and is expected to signal // which ones should be used for timestamp comparison. If the filter is // NULL, then all the prerequisites are used. // // Note that the return value is a pair with the second half indicating // whether any prerequisites were updated. This is used to handle the // situation where some prerequisites were updated but no update of the // target is necessary. In this case we still signal that the target was // (conceptually, but not physically) changed. This is important both to // propagate the fact that some work has been done and to also allow our // dependents to detect this case if they are up to something tricky (like // recursively linking liba{} prerequisites). // // Note that because we use mtime, this function should normally only be // used in the perform_update action. // using prerequisite_filter = function; pair execute_prerequisites (action, const target&, const timestamp&, const prerequisite_filter& = nullptr); // 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 pair execute_prerequisites (action, const target&, const timestamp&, const prerequisite_filter& = nullptr); pair execute_prerequisites (const target_type&, action, const target&, const timestamp&, const prerequisite_filter& = nullptr); template pair execute_prerequisites (const target_type&, action, const target&, const timestamp&, const prerequisite_filter& = nullptr); // Execute members of a group or similar prerequisite-like dependencies. // Similar in semantics to execute_prerequisites(). // target_state straight_execute_members (action, const target&, const target*[], size_t); target_state reverse_execute_members (action, const target&, const target*[], size_t); // Call straight or reverse depending on the current mode. // target_state execute_members (action, const target&, const target*[], size_t); template inline target_state straight_execute_members (action a, const target& t, const target* (&ts)[N]) { return straight_execute_members (a, t, ts, N); } template inline target_state reverse_execute_members (action a, const target& t, const target* (&ts)[N]) { return reverse_execute_members (a, t, ts, N); } template inline target_state execute_members (action a, const target& t, const target* (&ts)[N]) { return execute_members (a, t, ts, N); } // Return noop_recipe instead of using this function directly. // target_state noop_action (action, const target&); // Default action implementation which forwards to the prerequisites. // Use default_recipe instead of using this function directly. // target_state default_action (action, const target&); // Standard perform(clean) action implementation for the file target // (or derived). // target_state perform_clean (action, const target&); // As above, but also removes the auxiliary dependency database (.d file). // target_state perform_clean_depdb (action, const 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, const file&, initializer_list> extra); inline target_state clean_extra (action a, const file& f, initializer_list extra) { return clean_extra (a, f, {extra}); } } #include #endif // BUILD2_ALGORITHM