build/org.eclipse.cdt.managedbuilder.core/src/org/eclipse/cdt/managedbuilder/makegen/IManagedDependencyGenerator2.java

/*******************************************************************************
 * Copyright (c) 2005, 2006 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 * IBM   - Initial API and implementation of IManagedDependencyGenerator
 * Intel - Initial API and implementation of IManagedDependencyGenerator2
 *******************************************************************************/
package org.eclipse.cdt.managedbuilder.makegen;

import org.eclipse.cdt.managedbuilder.core.IBuildObject;
import org.eclipse.cdt.managedbuilder.core.IConfiguration;
import org.eclipse.cdt.managedbuilder.core.ITool;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IPath;

/**
 * @since 3.1
 *
 * A Tool dependency calculator must implement this interface.  This interface
 * replaces IManagedDependencyGenerator which is deprecated.
 *
 * Discussion of Dependency Calculation:
 *
 * There are two major, and multiple minor, modes of dependency calculation
 * supported by the MBS.  The major modes are:
 *
 *  1. The build file generator invokes tool integrator provided methods
 *     that calculate all dependencies using whatever method the tool
 *     integrator wants.  The build file generator then adds the dependencies
 *     to the build file using the appropriate build file syntax.
 *     This is a TYPE_CUSTOM dependency calculator as defined below.
 *     See the IManagedDependencyCalculator interface for more information.
 *
 *  2. The build file generator and the tool-chain cooperate in creating and
 *     using separate "dependency" files.  In this case, dependency calculation
 *     is done at "build time", rather than at "build file generation time" as
 *     in mode #1.  This currently supports the GNU concept of using .d files
 *     in GNU make.
 *     This is either a TYPE_BUILD_COMMANDS dependency calculator or a
 *     TYPE_PREBUILD_COMMANDS dependency calculator as defined below.
 *     See the IManagedDependencyCommands and IManagedDependencyPreBuild
 *     interfaces for more information.
 *
 */

public interface IManagedDependencyGenerator2 extends IManagedDependencyGeneratorType {

	/**
	 * Returns an instance of IManagedDependencyInfo for this source file.
	 * IManagedDependencyCalculator, IManagedDependencyCommands
	 * and IManagedDependencyPreBuild are all derived from
	 * IManagedDependencyInfo, and any one of the three can be returned.
	 * This is called when getCalculatorType returns TYPE_BUILD_COMMANDS,
	 * TYPE_CUSTOM or TYPE_PREBUILD_COMMANDS.
	 *
	 * @param source  The source file for which dependencies should be calculated
	 *    The IPath can be either relative to the project directory, or absolute in the file system.
	 * @param resource The IResource corresponding to the source file, or null if the file
	 * is not a workspace resource.
	 * @param buildContext  The IConfiguration or IResourceConfiguration that
	 *   contains the context in which the source file will be built
	 * @param tool  The tool associated with the source file
	 * @param topBuildDirectory  The top build directory of the configuration.  This is
	 *   the working directory for the tool.  This IPath is relative to the project directory.
	 * @return IManagedDependencyInfo
	 */
	public IManagedDependencyInfo getDependencySourceInfo(IPath source, IResource resource, IBuildObject buildContext,
			ITool tool, IPath topBuildDirectory);

	/**
	 * Returns an instance of IManagedDependencyInfo for this source file.
	 * IManagedDependencyCalculator, IManagedDependencyCommands
	 * and IManagedDependencyPreBuild are all derived from
	 * IManagedDependencyInfo, and any one of the three can be returned.
	 * This is called when getCalculatorType returns TYPE_BUILD_COMMANDS,
	 * TYPE_CUSTOM or TYPE_PREBUILD_COMMANDS.
	 *
	 * @param source  The source file for which dependencies should be calculated
	 *    The IPath can be either relative to the project directory, or absolute in the file system.
	 * @param buildContext  The IConfiguration or IResourceConfiguration that
	 *   contains the context in which the source file will be built
	 * @param tool  The tool associated with the source file
	 * @param topBuildDirectory  The top build directory of the configuration.  This is
	 *   the working directory for the tool.  This IPath is relative to the project directory.
	 * @return IManagedDependencyInfo
	 */
	public IManagedDependencyInfo getDependencySourceInfo(IPath source, IBuildObject buildContext, ITool tool,
			IPath topBuildDirectory);

	/**
	 * Returns the file extension used by dependency files created
	 * by this dependency generator.
	 * This is called when getCalculatorType returns TYPE_BUILD_COMMANDS or
	 * TYPE_PREBUILD_COMMANDS.
	 *
	 * @param buildContext  The IConfiguration that contains the context of the build
	 * @param tool  The tool associated with the dependency generator.
	 *
	 * @return String
	 */
	public String getDependencyFileExtension(IConfiguration buildContext, ITool tool);

	/**
	 * Called to allow the dependency calculator to post-process dependency files.
	 * This method is called after the build has completed for at least every
	 * dependency file that has changed, and possibly for those that have not
	 * changed as well.  It may also be called with dependency files created by
	 * another tool.  This method should be able to recognize dependency files
	 * that don't belong to it, or that it has already post-processed.
	 * This is called when getCalculatorType returns TYPE_BUILD_COMMANDS or
	 * TYPE_PREBUILD_COMMANDS.
	 *
	 * @param dependencyFile  The dependency file
	 *    The IPath can be either relative to the top build directory, or absolute in the file system.
	 * @param buildContext  The IConfiguration that contains the context of the build
	 * @param tool  The tool associated with the dependency generator.  Note that this is
	 *    not necessarily the tool that created the dependency file
	 * @param topBuildDirectory  The top build directory of the project.  This is
	 *   the working directory for the tool.
	 *
	 * @return boolean  True if the method modified the dependency (e.g., .d) file
	 */
	public boolean postProcessDependencyFile(IPath dependencyFile, IConfiguration buildContext, ITool tool,
			IPath topBuildDirectory);
}