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

/*******************************************************************************
 * Copyright (c) 2006, 2012 Intel 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:
 * Intel Corporation - Initial API and implementation
 *******************************************************************************/
package org.eclipse.cdt.managedbuilder.makegen;

import org.eclipse.core.runtime.IPath;

/**
 * @since 3.1
 *
 * A Tool dependency calculator may implement this interface or
 * IManagedDependencyCalculator or IManagedDependencyCommands.
 * An object implementing the interface is returned from a call to
 * IManagedDependencyGenerator2.getDependencySourceInfo.
 *
 * 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.
 *     See the IManagedDependencyCalculator interface for more information.
 *
 *  2. The build file generator and the tool-chain cooperate in creating and
 *     using separate "dependency" files.  The build file generator calls
 *     the dependency calculator to get the dependency file names and to get
 *     commands that need to be added to the build file.  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.
 *
 *     There are multiple ways that these separate dependency files can
 *     be created by the tool-chain and used by the builder.
 *
 *     a.  In some cases (e.g., Fortran 90 using modules) the dependency files
 *         must be created/updated prior to invoking the build of the project
 *         artifact (e.g., an application).  In this case, the dependency
 *         generation step must occur separately before the main build.
 *         Use the IManagedDependencyPreBuild interface defined in this file
 *         for this mode.
 *
 *     b.  In other cases (e.g., C/C++) the dependency files can be created as
 *         a side effect of the main build.  This implies that the up to date
 *         dependency files are not required for the current build, but for
 *         the next build.  C/C++ builds can be treated in this manner as is
 *         described in the following link:
 *         http://sourceware.org/automake/automake.html#Dependency-Tracking-Evolution
 *
 *         See the IManagedDependencyCommands interface for more information.
 *
 *
 * Note for GNU make: these separate dependency files are "include"d by
 *         a main makefile.  Make performs special processing on make files:
 *
 *         "To this end, after reading in all makefiles, make will consider
 *         each as a goal target and attempt to update it. If a makefile has a
 *         rule which says how to update it (found either in that very
 *         makefile or in another one)..., it will be updated if necessary.
 *         After all makefiles have been checked, if any have actually been
 *         changed, make starts with a clean slate and reads all the makefiles
 *         over again."
 *
 *         We can use this to ensure that the dependency files are up to date
 *         by adding rules to the make file for generating the dependency files.
 *         These rules are returned by the call to getDependencyCommands.
 *         However, this has a significant problem when we don't want to build
 *         the build target, but only want to "clean" the configuration,
 *         for example.  If we invoke make just to clean the configuration,
 *         make will still update the dependency files if necessary, thereby
 *         re-generating the dependency files only to immediately delete them.
 *         The workaround suggested by the make documentation is to check for
 *         an invocation using the "clean" target, and to not include the
 *         dependency files it that case.  For example,
 *
 *         ifneq ($(MAKECMDGOALS),clean)
 *         include $(DEPS)
 *         endif
 *
 *         The restriction with this is that it only works if "clean" is the only
 *         target specified on the make command line.  Therefore, the build
 *         "clean" step must be invoked separately.
 */

public interface IManagedDependencyPreBuild extends IManagedDependencyInfo {

	/**
	 * Returns the list of generated dependency files.
	 *
	 * The paths can be either relative to the top build directory, or absolute
	 * in the file system.
	 *
	 * @return IPath[]
	 */
	public IPath[] getDependencyFiles();

	/**
	 * Returns the name to be used in the build file to identify the separate
	 * build step.  Note that this name should be unique to the tool since
	 * multiple tools in a tool-chain may be using this method of
	 * dependency calculation.
	 *
	 * @return String
	 */
	public String getBuildStepName();

	/**
	 * Returns the command line(s) to be invoked in the separate
	 * dependencies pre-build step.
	 *
	 * @return String[]
	 */
	public String[] getDependencyCommands();

	/**
	 * Returns true if the command lines returned by this interface
	 * are not specific to the particular source file, but are only specific to,
	 * at most, the configuration and tool.  If the build context is a resource
	 * configuration, this method should return false if any of the command lines
	 * are different than if the build context were the parent configuration.
	 * This can be used by the build file generator in helping to determine if
	 * a "pattern" (generic) rule can be used.
	 *
	 * @return boolean
	 */
	public boolean areCommandsGeneric();
}