src/com/facebook/buck/rules/AbstractCachingBuildRule.java - buck - Git at Google

 /*
  * Copyright 2012-present Facebook, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may
  * not use this file except in compliance with the License. You may obtain
  * a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  * License for the specific language governing permissions and limitations
  * under the License.
  */

 package com.facebook.buck.rules;

 import com.facebook.buck.event.BuckEventBus;
 import com.facebook.buck.step.Step;
 import com.facebook.buck.step.StepFailedException;
 import com.facebook.buck.step.StepRunner;
 import com.facebook.buck.util.BuckConstant;
 import com.facebook.buck.util.DirectoryTraverser;
 import com.facebook.buck.util.DirectoryTraversers;
 import com.facebook.buck.util.MoreFutures;
 import com.facebook.buck.util.ProjectFilesystem;
 import com.google.common.annotations.Beta;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Charsets;
 import com.google.common.base.Function;
 import com.google.common.base.Optional;
 import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.ImmutableSortedSet;
 import com.google.common.collect.Lists;
 import com.google.common.io.Files;
 import com.google.common.util.concurrent.FutureCallback;
 import com.google.common.util.concurrent.Futures;
 import com.google.common.util.concurrent.ListenableFuture;
 import com.google.common.util.concurrent.SettableFuture;

 import java.io.File;
 import java.io.IOException;
 import java.util.List;
 import java.util.Set;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.atomic.AtomicBoolean;

 import javax.annotation.Nullable;

 /**
  * Abstract implementation of a {@link BuildRule} that can be cached. If its current {@link RuleKey}
  * matches the one on disk, then it has no work to do. It should also try to fetch its output from
  * an {@link ArtifactCache} to avoid doing any computation.
  * <p>
  * TODO(mbolin, simons): This should be converted from an abstract class that relies on inheritance
  * to a final class that takes an object that implements the following methods:
  * <ul>
  *   <li>getInputsToCompareToOutput()
  *   <li>buildInternal()
  *   <li>appendToRuleKey()
  *   <li>recordOutputFileDetailsAfterFetchFromArtifactCache()
  * </ul>
  * Ultimately, we plan to define a BuildRuleDescriptor, from which we will at least be able to
  * provide the implementation of getInputsToCompareToOutput() and appendToRuleKey() automatically.
  * How we plan to generify the ABI logic is up in the air.
  */
 @Beta
 public abstract class AbstractCachingBuildRule extends AbstractBuildRule implements BuildRule {

   /**
    * Lock used to ensure that the logic to kick off a build is performed at most once.
    */
   private final AtomicBoolean hasBuildStarted;

   /**
    * This is the value returned by {@link #build(BuildContext)}.
    * This is initialized by the constructor and marked as final because {@link #build(BuildContext)}
    * must always return the same value.
    */
   private final SettableFuture<BuildRuleSuccess> buildRuleResult;

   private final Function<String, String> pathRelativizer;

   /** @see #getInputsToCompareToOutput(BuildContext) */
   private Iterable<InputRule> inputsToCompareToOutputs;

   protected AbstractCachingBuildRule(BuildRuleParams buildRuleParams) {
       super(buildRuleParams);
     this.hasBuildStarted = new AtomicBoolean(false);
     this.buildRuleResult = SettableFuture.create();
     this.pathRelativizer = buildRuleParams.getPathRelativizer();
   }

   /**
    * This rule is designed to be used for precondition checks in subclasses. For example, before
    * running the tests associated with a build rule, it is reasonable to do a sanity check to
    * ensure that the rule has been built.
    */
   protected final synchronized boolean isRuleBuilt() {
     return MoreFutures.isSuccess(buildRuleResult);
   }

   @Override
   public BuildRuleSuccess.Type getBuildResultType() {
     Preconditions.checkState(isRuleBuilt());
     try {
       return buildRuleResult.get().getType();
     } catch (InterruptedException | ExecutionException e) {
       throw new RuntimeException(e);
     }
   }

   /**
    * Get the set of input files whose contents should be hashed for the purpose of determining
    * whether this rule is cached.
    * <p>
    * Note that the collection of inputs is specified as a list, because for some build rules
    * (such as {@link com.facebook.buck.shell.Genrule}), the order of the inputs is significant. If
    * the order of the inputs is not significant for the build rule, then the list should be
    * alphabetized so that lists with the same elements will be {@code .equals()} to one another.
    */
   abstract protected Iterable<String> getInputsToCompareToOutput();

   @Override
   public Iterable<InputRule> getInputs() {
     if (inputsToCompareToOutputs == null) {
       inputsToCompareToOutputs = InputRule.inputPathsAsInputRules(
           getInputsToCompareToOutput(), pathRelativizer);
     }
     return inputsToCompareToOutputs;
   }

   @Override
   protected RuleKey.Builder appendToRuleKey(RuleKey.Builder builder) {
     // For a rule that lists its inputs via a "srcs" argument, this may seem redundant, but it is
     // not. Here, the inputs are specified as InputRules, which means that the _contents_ of the
     // files will be hashed. In the case of .set("srcs", srcs), the list of strings itself will be
     // hashed. It turns out that we need both of these in order to construct a RuleKey correctly.
     return super.appendToRuleKey(builder)
         .setInputs("buck.inputs", getInputs());
   }

   @Override
   public final ListenableFuture<BuildRuleSuccess> build(final BuildContext context) {
     // We use hasBuildStarted as a lock so that we can minimize how much we need to synchronize.
     synchronized(hasBuildStarted) {
       if (hasBuildStarted.get()) {
         return buildRuleResult;
       } else {
         hasBuildStarted.set(true);
       }
     }

     // Build all of the deps first and then schedule a callback for this rule to build itself once
     // all of those rules are done building.
     try {
       // Invoke every dep's build() method and create an uber-ListenableFuture that represents the
       // successful completion of all deps.
       List<ListenableFuture<BuildRuleSuccess>> builtDeps =
           Lists.newArrayListWithCapacity(getDeps().size());
       for (BuildRule dep : getDeps()) {
         builtDeps.add(dep.build(context));
       }
       ListenableFuture<List<BuildRuleSuccess>> allBuiltDeps = Futures.allAsList(builtDeps);

       // Schedule this rule to build itself once all of the deps are built.
       Futures.addCallback(allBuiltDeps,
           new FutureCallback<List<BuildRuleSuccess>>() {

             @Override
             public void onSuccess(List<BuildRuleSuccess> deps) {
               buildOnceDepsAreBuilt(context);
             }

             @Override
             public void onFailure(Throwable failure) {
               recordBuildRuleFailure(failure,
                   BuildRuleStatus.FAIL,
                   CacheResult.MISS,
                   context.getEventBus());
             }
           },
           context.getExecutor());
     } catch (Throwable throwable) {
       // This is a defensive catch block: if buildRuleResult is never satisfied, then Buck will
       // hang because a callback that is waiting for this rule's future to complete will never be
       // executed.
       recordBuildRuleFailure(throwable,
           BuildRuleStatus.FAIL,
           CacheResult.MISS,
           context.getEventBus());
     }

     return buildRuleResult;
   }

   /**
    * Uses the deprecated {@link BuildContext#getProjectFilesystem()} method to get a
    * {@link ProjectFilesystem}. This is abstracted into its own method to reduce the reach of the
    * {@link SuppressWarnings} annotation.
    */
   @SuppressWarnings("deprecation")
   private ProjectFilesystem getProjectFilesystemFromBuildContext(BuildContext context) {
     return context.getProjectFilesystem();
   }

   /**
    * This method is invoked once all of this rule's dependencies are built.
    * <p>
    * This method should be executed on a fresh Runnable in BuildContext's ListeningExecutorService,
    * so there is no reason to schedule new work in a new Runnable.
    * <p>
    * All exit paths through this method should resolve {@link #buildRuleResult} before exiting. To
    * that end, this method should never throw an exception, or else Buck will hang waiting for
    * {@link #buildRuleResult} to be resolved.
    */
   private void buildOnceDepsAreBuilt(final BuildContext context) {
     BuckEventBus eventBus = context.getEventBus();
     ProjectFilesystem projectFilesystem = getProjectFilesystemFromBuildContext(context);

     // Record the start of the build.
     eventBus.post(BuildRuleEvent.started(AbstractCachingBuildRule.this));

     // Deciding whether we need to rebuild is tricky business. We want to rebuild as little as
     // possible while always being sound.
     //
     // For java_library rules that depend only on their first-order deps,
     // they only need to rebuild themselves if any of the following conditions hold:
     // (1) The definition of the build rule has changed.
     // (2) Any of the input files (which includes resources as well as .java files) have changed.
     // (3) The ABI of any of its dependent java_library rules has changed.
     //
     // For other types of build rules, we have to be more conservative when rebuilding. In those
     // cases, we rebuild if any of the following conditions hold:
     // (1) The definition of the build rule has changed.
     // (2) Any of the input files have changed.
     // (3) Any of the RuleKeys of this rule's deps have changed.
     //
     // Because a RuleKey for a rule will change if any of its transitive deps have changed, that
     // means a change in one of the leaves can result in almost all rules being rebuilt, which is
     // slow. Fortunately, we limit the effects of this when building Java code when checking the ABI
     // of deps instead of the RuleKey for deps.
     if (this instanceof AbiRule) {
       AbiRule abiRule = (AbiRule)this;

       Optional<RuleKey> ruleKeyNoDeps = abiRule.getRuleKeyWithoutDeps();
       Optional<RuleKey> cachedRuleKeyNoDeps = abiRule.getRuleKeyWithoutDepsOnDisk(projectFilesystem);
       if (ruleKeyNoDeps.isPresent() && ruleKeyNoDeps.equals(cachedRuleKeyNoDeps)) {
         // The RuleKey for the definition of this build rule and its input files has not changed.
         // Therefore, if the ABI of its deps has not changed, there is nothing to rebuild.
         Optional<Sha1HashCode> abiKeyForDeps = abiRule.getAbiKeyForDeps();
         Optional<Sha1HashCode> cachedAbiKeyForDeps = abiRule.getAbiKeyForDepsOnDisk(projectFilesystem);
         if (abiKeyForDeps.isPresent()
             && abiKeyForDeps.equals(cachedAbiKeyForDeps)
             && abiRule.initializeFromDisk(projectFilesystem)) {
           // Although no rebuild is required, we still need to write the updated RuleKey.
           try {
             writeSuccessFile(projectFilesystem);
           } catch (IOException e) {
             recordBuildRuleFailure(e, BuildRuleStatus.FAIL, CacheResult.HIT, eventBus);
             return;
           }

           recordBuildRuleSuccess(BuildRuleSuccess.Type.MATCHING_DEPS_ABI_AND_RULE_KEY_NO_DEPS,
               BuildRuleStatus.SUCCESS,
               CacheResult.HIT,
               eventBus);
           return;
         }
       }
     }

     // Compute the current RuleKey and compare it to the one stored on disk.
     RuleKey ruleKey = getRuleKey();
     Optional<RuleKey> cachedRuleKey = getRuleKeyOnDisk(projectFilesystem);

     // If the RuleKeys match, then there is nothing to build.
     if (cachedRuleKey.isPresent() && ruleKey.equals(cachedRuleKey.get())) {
       initializeFromDisk(projectFilesystem);
       context.logBuildInfo("[UNCHANGED %s]", getFullyQualifiedName());
       recordBuildRuleSuccess(BuildRuleSuccess.Type.MATCHING_RULE_KEY,
           BuildRuleStatus.SUCCESS,
           CacheResult.HIT,
           eventBus);
       return;
     }

     // TODO(mbolin): Make sure that all output files are deleted before proceeding. This is
     // particularly important for tests: their test result files must be deleted. Otherwise, we
     // might replace the artifact for the rule, but leave the old test result files in place. We
     // should organize our output directories so we can solve this for all rules at once.

     // Before deciding to build, check the ArtifactCache.
     String pathToOutputFile = getPathToOutputFile();
     boolean fromCache = pathToOutputFile != null
         && context.getArtifactCache().fetch(
             getRuleKey(),
             projectFilesystem.getFileForRelativePath(pathToOutputFile));
     CacheResult cacheResult = fromCache ? CacheResult.HIT : CacheResult.MISS;

     // Give the rule a chance to record metadata about the artifact.
     if (fromCache) {
       try {
         recordOutputFileDetailsAfterFetchFromArtifactCache(context.getArtifactCache(),
             projectFilesystem);
       } catch (IOException e) {
         recordBuildRuleFailure(e, BuildRuleStatus.FAIL, cacheResult, eventBus);
         return;
       }
     }

     // Run the steps to build this rule since it was not found in the cache.
     if (!fromCache) {
       try {
         executeCommandsNowThatDepsAreBuilt(context);
       } catch (IOException|StepFailedException e) {
         recordBuildRuleFailure(e, BuildRuleStatus.FAIL, cacheResult, eventBus);
         return;
       }
     }

     // Record that the build rule has built successfully.
     try {
       recordBuildRuleCompleted(projectFilesystem, context.getArtifactCache(), fromCache);
     } catch (IOException e) {
       // If we failed to record the success, then we are in a potentially bad state where we have a
       // new output but an old RuleKey record.
       // TODO(mbolin): Make a final attempt to clear the invalid RuleKey record.
       recordBuildRuleFailure(e, BuildRuleStatus.FAIL, cacheResult, eventBus);
       return;
     }

     // We made it to the end of the method! Record our success.
     BuildRuleSuccess.Type successType = fromCache ? BuildRuleSuccess.Type.FETCHED_FROM_CACHE
                                                   : BuildRuleSuccess.Type.BUILT_LOCALLY;
     recordBuildRuleSuccess(successType, BuildRuleStatus.SUCCESS, cacheResult, eventBus);
     return;
   }

   private void recordBuildRuleSuccess(BuildRuleSuccess.Type type,
       BuildRuleStatus buildRuleStatus,
       CacheResult cacheResult,
       BuckEventBus eventBus) {
     eventBus.post(BuildRuleEvent.finished(this, buildRuleStatus, cacheResult, Optional.of(type)));
     buildRuleResult.set(new BuildRuleSuccess(this, type));
   }

   private void recordBuildRuleFailure(Throwable failure,
       BuildRuleStatus buildRuleStatus,
       CacheResult cacheResult,
       BuckEventBus eventBus) {
     eventBus.post(BuildRuleEvent.finished(this,
         buildRuleStatus,
         cacheResult,
         Optional.<BuildRuleSuccess.Type>absent()));
     buildRuleResult.setException(failure);
   }

   /**
    * Return this rule's RuleKey from the previous run if it is available on disk.
    * <p>
    * Any sort of internal IOException will be masked via {@link Optional#absent()}.
    */
   @VisibleForTesting
   Optional<RuleKey> getRuleKeyOnDisk(ProjectFilesystem projectFilesystem) {
     Optional<File> successFile = projectFilesystem.getFileIfExists(getPathToSuccessFile());
     if (successFile.isPresent()) {
       try {
         String ruleKeyHash = Files.readFirstLine(successFile.get(), Charsets.US_ASCII);
         return Optional.of(new RuleKey(ruleKeyHash));
       } catch (IOException|NumberFormatException|NullPointerException e) {
         // As we transition into a new format for a .success file, old versions of .success files
         // may be lying around, which could throw any of these exceptions. When this happens, we
         // treat the .success file the same as if it were missing.
         return Optional.absent();
       }
     } else {
       return Optional.absent();
     }
   }

   /**
    * This method is invoked if the output file is successfully fetched from the
    * {@link ArtifactCache}. This is where a rule has the opportunity to record any relevant metadata
    * about the artifact.
    * <p>
    * The default implementation of this method is empty.
    * @param cache The {@link ArtifactCache} that was used to fetch the output file.
    * @param projectFilesystem to use to determine where a metadata file should be written.
    */
   protected void recordOutputFileDetailsAfterFetchFromArtifactCache(ArtifactCache cache,
       ProjectFilesystem projectFilesystem) throws IOException {
   }

   /**
    * Execute the commands for this build rule. Requires all dependent rules are already built
    * successfully.
    */
   private void executeCommandsNowThatDepsAreBuilt(BuildContext context)
       throws IOException, StepFailedException {
     context.logBuildInfo("[BUILDING %s]", getFullyQualifiedName());

     // Get and run all of the commands.
     List<Step> steps = buildInternal(context);
     StepRunner stepRunner = context.getStepRunner();
     for (Step step : steps) {
       stepRunner.runStepForBuildTarget(step, getBuildTarget());
     }
   }

   /**
    * When this method is invoked, all of its dependencies will have been built.
    */
   abstract protected List<Step> buildInternal(BuildContext context) throws IOException;

   /**
    * For a rule that is read from the build cache, it may have fields that would normally be
    * populated by executing the steps returned by {@link #buildInternal(BuildContext)}. Because
    * {@link #buildInternal(BuildContext)} is not invoked for cached rules, a rule may need to
    * implement this method to populate those fields in some other way. For a cached rule, this
    * method will be invoked just before the future returned by {@link #build(BuildContext)} is
    * resolved.
    * <p>
    * By default, this method does nothing except return {@code true}.
    * @param projectFilesystem can be used to load
    * @return whether the internal data structures were populated successfully.
    */
   protected boolean initializeFromDisk(ProjectFilesystem projectFilesystem) {
     return true;
   }

   /**
    * Record that the outputs for the build rule have been written. They may have been written by
    * either:
    * <ol>
    *   <li>The build rule executing all of its steps successfully.
    *   <li>The build rule pulling down the output artifacts via the ArtifactCache.
    * </ol>
    */
   private void recordBuildRuleCompleted(ProjectFilesystem projectFilesystem,
       ArtifactCache artifactCache,
       boolean fromCache)
       throws IOException {
     // Drop our cached output key, since it probably changed.
     resetOutputKey();

     // Write the success file.
     writeSuccessFile(projectFilesystem);

     // Store output to cache.
     String pathToOutputFile = getPathToOutputFile();
     if (pathToOutputFile != null && !fromCache) {
       File output = projectFilesystem.getFileForRelativePath(pathToOutputFile);
       artifactCache.store(getRuleKey(), output);
     }
   }

   /**
    * Write out a file that represents that this build rule succeeded, as well as the inputs that
    * were used. The last-modified time of this file, and its contents, will be used to determine
    * whether this rule should be cached.
    * @throws IOException
    */
   private void writeSuccessFile(ProjectFilesystem projectFilesystem) throws IOException {
     String path = getPathToSuccessFile();
     projectFilesystem.createParentDirs(path);
     Iterable<String> lines = getSuccessFileStringsForBuildRules();
     projectFilesystem.writeLinesToPath(lines, path);
   }

   private Iterable<String> getSuccessFileStringsForBuildRules() {
     // For now, the one and only line written to the .success file is the RuleKey hash.
     return ImmutableList.of(getRuleKey().toString());
   }

   @VisibleForTesting
   String getPathToSuccessFile() {
     return String.format("%s/%s.success/%s",
         BuckConstant.BIN_DIR,
         getBuildTarget().getBasePathWithSlash(),
         getBuildTarget().getShortName());
   }

   /**
    * Helper function for subclasses to create their lists of files for caching.
    */
   protected static void addInputsToSortedSet(@Nullable String pathToDirectory,
       ImmutableSortedSet.Builder<String> inputsToConsiderForCachingPurposes,
       DirectoryTraverser traverser) {
     if (pathToDirectory == null) {
       return;
     }
     Set<String> files = DirectoryTraversers.getInstance().findFiles(
         ImmutableSet.of(pathToDirectory), traverser);
     inputsToConsiderForCachingPurposes.addAll(files);
   }
 }
	/*
	* Copyright 2012-present Facebook, Inc.
	*
	* Licensed under the Apache License, Version 2.0 (the "License"); you may
	* not use this file except in compliance with the License. You may obtain
	* a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	* License for the specific language governing permissions and limitations
	* under the License.
	*/

	package com.facebook.buck.rules;

	import com.facebook.buck.event.BuckEventBus;
	import com.facebook.buck.step.Step;
	import com.facebook.buck.step.StepFailedException;
	import com.facebook.buck.step.StepRunner;
	import com.facebook.buck.util.BuckConstant;
	import com.facebook.buck.util.DirectoryTraverser;
	import com.facebook.buck.util.DirectoryTraversers;
	import com.facebook.buck.util.MoreFutures;
	import com.facebook.buck.util.ProjectFilesystem;
	import com.google.common.annotations.Beta;
	import com.google.common.annotations.VisibleForTesting;
	import com.google.common.base.Charsets;
	import com.google.common.base.Function;
	import com.google.common.base.Optional;
	import com.google.common.base.Preconditions;
	import com.google.common.collect.ImmutableList;
	import com.google.common.collect.ImmutableSet;
	import com.google.common.collect.ImmutableSortedSet;
	import com.google.common.collect.Lists;
	import com.google.common.io.Files;
	import com.google.common.util.concurrent.FutureCallback;
	import com.google.common.util.concurrent.Futures;
	import com.google.common.util.concurrent.ListenableFuture;
	import com.google.common.util.concurrent.SettableFuture;

	import java.io.File;
	import java.io.IOException;
	import java.util.List;
	import java.util.Set;
	import java.util.concurrent.ExecutionException;
	import java.util.concurrent.atomic.AtomicBoolean;

	import javax.annotation.Nullable;

	/**
	* Abstract implementation of a {@link BuildRule} that can be cached. If its current {@link RuleKey}
	* matches the one on disk, then it has no work to do. It should also try to fetch its output from
	* an {@link ArtifactCache} to avoid doing any computation.
	* <p>
	* TODO(mbolin, simons): This should be converted from an abstract class that relies on inheritance
	* to a final class that takes an object that implements the following methods:
	* <ul>
	* <li>getInputsToCompareToOutput()
	* <li>buildInternal()
	* <li>appendToRuleKey()
	* <li>recordOutputFileDetailsAfterFetchFromArtifactCache()
	* </ul>
	* Ultimately, we plan to define a BuildRuleDescriptor, from which we will at least be able to
	* provide the implementation of getInputsToCompareToOutput() and appendToRuleKey() automatically.
	* How we plan to generify the ABI logic is up in the air.
	*/
	@Beta
	public abstract class AbstractCachingBuildRule extends AbstractBuildRule implements BuildRule {

	/**
	* Lock used to ensure that the logic to kick off a build is performed at most once.
	*/
	private final AtomicBoolean hasBuildStarted;

	/**
	* This is the value returned by {@link #build(BuildContext)}.
	* This is initialized by the constructor and marked as final because {@link #build(BuildContext)}
	* must always return the same value.
	*/
	private final SettableFuture<BuildRuleSuccess> buildRuleResult;

	private final Function<String, String> pathRelativizer;

	/** @see #getInputsToCompareToOutput(BuildContext) */
	private Iterable<InputRule> inputsToCompareToOutputs;

	protected AbstractCachingBuildRule(BuildRuleParams buildRuleParams) {
	super(buildRuleParams);
	this.hasBuildStarted = new AtomicBoolean(false);
	this.buildRuleResult = SettableFuture.create();
	this.pathRelativizer = buildRuleParams.getPathRelativizer();
	}

	/**
	* This rule is designed to be used for precondition checks in subclasses. For example, before
	* running the tests associated with a build rule, it is reasonable to do a sanity check to
	* ensure that the rule has been built.
	*/
	protected final synchronized boolean isRuleBuilt() {
	return MoreFutures.isSuccess(buildRuleResult);
	}

	@Override
	public BuildRuleSuccess.Type getBuildResultType() {
	Preconditions.checkState(isRuleBuilt());
	try {
	return buildRuleResult.get().getType();
	} catch (InterruptedException \| ExecutionException e) {
	throw new RuntimeException(e);
	}
	}

	/**
	* Get the set of input files whose contents should be hashed for the purpose of determining
	* whether this rule is cached.
	* <p>
	* Note that the collection of inputs is specified as a list, because for some build rules
	* (such as {@link com.facebook.buck.shell.Genrule}), the order of the inputs is significant. If
	* the order of the inputs is not significant for the build rule, then the list should be
	* alphabetized so that lists with the same elements will be {@code .equals()} to one another.
	*/
	abstract protected Iterable<String> getInputsToCompareToOutput();

	@Override
	public Iterable<InputRule> getInputs() {
	if (inputsToCompareToOutputs == null) {
	inputsToCompareToOutputs = InputRule.inputPathsAsInputRules(
	getInputsToCompareToOutput(), pathRelativizer);
	}
	return inputsToCompareToOutputs;
	}

	@Override
	protected RuleKey.Builder appendToRuleKey(RuleKey.Builder builder) {
	// For a rule that lists its inputs via a "srcs" argument, this may seem redundant, but it is
	// not. Here, the inputs are specified as InputRules, which means that the _contents_ of the
	// files will be hashed. In the case of .set("srcs", srcs), the list of strings itself will be
	// hashed. It turns out that we need both of these in order to construct a RuleKey correctly.
	return super.appendToRuleKey(builder)
	.setInputs("buck.inputs", getInputs());
	}

	@Override
	public final ListenableFuture<BuildRuleSuccess> build(final BuildContext context) {
	// We use hasBuildStarted as a lock so that we can minimize how much we need to synchronize.
	synchronized(hasBuildStarted) {
	if (hasBuildStarted.get()) {
	return buildRuleResult;
	} else {
	hasBuildStarted.set(true);
	}
	}

	// Build all of the deps first and then schedule a callback for this rule to build itself once
	// all of those rules are done building.
	try {
	// Invoke every dep's build() method and create an uber-ListenableFuture that represents the
	// successful completion of all deps.
	List<ListenableFuture<BuildRuleSuccess>> builtDeps =
	Lists.newArrayListWithCapacity(getDeps().size());
	for (BuildRule dep : getDeps()) {
	builtDeps.add(dep.build(context));
	}
	ListenableFuture<List<BuildRuleSuccess>> allBuiltDeps = Futures.allAsList(builtDeps);

	// Schedule this rule to build itself once all of the deps are built.
	Futures.addCallback(allBuiltDeps,
	new FutureCallback<List<BuildRuleSuccess>>() {

	@Override
	public void onSuccess(List<BuildRuleSuccess> deps) {
	buildOnceDepsAreBuilt(context);
	}

	@Override
	public void onFailure(Throwable failure) {
	recordBuildRuleFailure(failure,
	BuildRuleStatus.FAIL,
	CacheResult.MISS,
	context.getEventBus());
	}
	},
	context.getExecutor());
	} catch (Throwable throwable) {
	// This is a defensive catch block: if buildRuleResult is never satisfied, then Buck will
	// hang because a callback that is waiting for this rule's future to complete will never be
	// executed.
	recordBuildRuleFailure(throwable,
	BuildRuleStatus.FAIL,
	CacheResult.MISS,
	context.getEventBus());
	}

	return buildRuleResult;
	}

	/**
	* Uses the deprecated {@link BuildContext#getProjectFilesystem()} method to get a
	* {@link ProjectFilesystem}. This is abstracted into its own method to reduce the reach of the
	* {@link SuppressWarnings} annotation.
	*/
	@SuppressWarnings("deprecation")
	private ProjectFilesystem getProjectFilesystemFromBuildContext(BuildContext context) {
	return context.getProjectFilesystem();
	}

	/**
	* This method is invoked once all of this rule's dependencies are built.
	* <p>
	* This method should be executed on a fresh Runnable in BuildContext's ListeningExecutorService,
	* so there is no reason to schedule new work in a new Runnable.
	* <p>
	* All exit paths through this method should resolve {@link #buildRuleResult} before exiting. To
	* that end, this method should never throw an exception, or else Buck will hang waiting for
	* {@link #buildRuleResult} to be resolved.
	*/
	private void buildOnceDepsAreBuilt(final BuildContext context) {
	BuckEventBus eventBus = context.getEventBus();
	ProjectFilesystem projectFilesystem = getProjectFilesystemFromBuildContext(context);

	// Record the start of the build.
	eventBus.post(BuildRuleEvent.started(AbstractCachingBuildRule.this));

	// Deciding whether we need to rebuild is tricky business. We want to rebuild as little as
	// possible while always being sound.
	//
	// For java_library rules that depend only on their first-order deps,
	// they only need to rebuild themselves if any of the following conditions hold:
	// (1) The definition of the build rule has changed.
	// (2) Any of the input files (which includes resources as well as .java files) have changed.
	// (3) The ABI of any of its dependent java_library rules has changed.
	//
	// For other types of build rules, we have to be more conservative when rebuilding. In those
	// cases, we rebuild if any of the following conditions hold:
	// (1) The definition of the build rule has changed.
	// (2) Any of the input files have changed.
	// (3) Any of the RuleKeys of this rule's deps have changed.
	//
	// Because a RuleKey for a rule will change if any of its transitive deps have changed, that
	// means a change in one of the leaves can result in almost all rules being rebuilt, which is
	// slow. Fortunately, we limit the effects of this when building Java code when checking the ABI
	// of deps instead of the RuleKey for deps.
	if (this instanceof AbiRule) {
	AbiRule abiRule = (AbiRule)this;

	Optional<RuleKey> ruleKeyNoDeps = abiRule.getRuleKeyWithoutDeps();
	Optional<RuleKey> cachedRuleKeyNoDeps = abiRule.getRuleKeyWithoutDepsOnDisk(projectFilesystem);
	if (ruleKeyNoDeps.isPresent() && ruleKeyNoDeps.equals(cachedRuleKeyNoDeps)) {
	// The RuleKey for the definition of this build rule and its input files has not changed.
	// Therefore, if the ABI of its deps has not changed, there is nothing to rebuild.
	Optional<Sha1HashCode> abiKeyForDeps = abiRule.getAbiKeyForDeps();
	Optional<Sha1HashCode> cachedAbiKeyForDeps = abiRule.getAbiKeyForDepsOnDisk(projectFilesystem);
	if (abiKeyForDeps.isPresent()
	&& abiKeyForDeps.equals(cachedAbiKeyForDeps)
	&& abiRule.initializeFromDisk(projectFilesystem)) {
	// Although no rebuild is required, we still need to write the updated RuleKey.
	try {
	writeSuccessFile(projectFilesystem);
	} catch (IOException e) {
	recordBuildRuleFailure(e, BuildRuleStatus.FAIL, CacheResult.HIT, eventBus);
	return;
	}

	recordBuildRuleSuccess(BuildRuleSuccess.Type.MATCHING_DEPS_ABI_AND_RULE_KEY_NO_DEPS,
	BuildRuleStatus.SUCCESS,
	CacheResult.HIT,
	eventBus);
	return;
	}
	}
	}

	// Compute the current RuleKey and compare it to the one stored on disk.
	RuleKey ruleKey = getRuleKey();
	Optional<RuleKey> cachedRuleKey = getRuleKeyOnDisk(projectFilesystem);

	// If the RuleKeys match, then there is nothing to build.
	if (cachedRuleKey.isPresent() && ruleKey.equals(cachedRuleKey.get())) {
	initializeFromDisk(projectFilesystem);
	context.logBuildInfo("[UNCHANGED %s]", getFullyQualifiedName());
	recordBuildRuleSuccess(BuildRuleSuccess.Type.MATCHING_RULE_KEY,
	BuildRuleStatus.SUCCESS,
	CacheResult.HIT,
	eventBus);
	return;
	}

	// TODO(mbolin): Make sure that all output files are deleted before proceeding. This is
	// particularly important for tests: their test result files must be deleted. Otherwise, we
	// might replace the artifact for the rule, but leave the old test result files in place. We
	// should organize our output directories so we can solve this for all rules at once.

	// Before deciding to build, check the ArtifactCache.
	String pathToOutputFile = getPathToOutputFile();
	boolean fromCache = pathToOutputFile != null
	&& context.getArtifactCache().fetch(
	getRuleKey(),
	projectFilesystem.getFileForRelativePath(pathToOutputFile));
	CacheResult cacheResult = fromCache ? CacheResult.HIT : CacheResult.MISS;

	// Give the rule a chance to record metadata about the artifact.
	if (fromCache) {
	try {
	recordOutputFileDetailsAfterFetchFromArtifactCache(context.getArtifactCache(),
	projectFilesystem);
	} catch (IOException e) {
	recordBuildRuleFailure(e, BuildRuleStatus.FAIL, cacheResult, eventBus);
	return;
	}
	}

	// Run the steps to build this rule since it was not found in the cache.
	if (!fromCache) {
	try {
	executeCommandsNowThatDepsAreBuilt(context);
	} catch (IOException\|StepFailedException e) {
	recordBuildRuleFailure(e, BuildRuleStatus.FAIL, cacheResult, eventBus);
	return;
	}
	}

	// Record that the build rule has built successfully.
	try {
	recordBuildRuleCompleted(projectFilesystem, context.getArtifactCache(), fromCache);
	} catch (IOException e) {
	// If we failed to record the success, then we are in a potentially bad state where we have a
	// new output but an old RuleKey record.
	// TODO(mbolin): Make a final attempt to clear the invalid RuleKey record.
	recordBuildRuleFailure(e, BuildRuleStatus.FAIL, cacheResult, eventBus);
	return;
	}

	// We made it to the end of the method! Record our success.
	BuildRuleSuccess.Type successType = fromCache ? BuildRuleSuccess.Type.FETCHED_FROM_CACHE
	: BuildRuleSuccess.Type.BUILT_LOCALLY;
	recordBuildRuleSuccess(successType, BuildRuleStatus.SUCCESS, cacheResult, eventBus);
	return;
	}

	private void recordBuildRuleSuccess(BuildRuleSuccess.Type type,
	BuildRuleStatus buildRuleStatus,
	CacheResult cacheResult,
	BuckEventBus eventBus) {
	eventBus.post(BuildRuleEvent.finished(this, buildRuleStatus, cacheResult, Optional.of(type)));
	buildRuleResult.set(new BuildRuleSuccess(this, type));
	}

	private void recordBuildRuleFailure(Throwable failure,
	BuildRuleStatus buildRuleStatus,
	CacheResult cacheResult,
	BuckEventBus eventBus) {
	eventBus.post(BuildRuleEvent.finished(this,
	buildRuleStatus,
	cacheResult,
	Optional.<BuildRuleSuccess.Type>absent()));
	buildRuleResult.setException(failure);
	}

	/**
	* Return this rule's RuleKey from the previous run if it is available on disk.
	* <p>
	* Any sort of internal IOException will be masked via {@link Optional#absent()}.
	*/
	@VisibleForTesting
	Optional<RuleKey> getRuleKeyOnDisk(ProjectFilesystem projectFilesystem) {
	Optional<File> successFile = projectFilesystem.getFileIfExists(getPathToSuccessFile());
	if (successFile.isPresent()) {
	try {
	String ruleKeyHash = Files.readFirstLine(successFile.get(), Charsets.US_ASCII);
	return Optional.of(new RuleKey(ruleKeyHash));
	} catch (IOException\|NumberFormatException\|NullPointerException e) {
	// As we transition into a new format for a .success file, old versions of .success files
	// may be lying around, which could throw any of these exceptions. When this happens, we
	// treat the .success file the same as if it were missing.
	return Optional.absent();
	}
	} else {
	return Optional.absent();
	}
	}

	/**
	* This method is invoked if the output file is successfully fetched from the
	* {@link ArtifactCache}. This is where a rule has the opportunity to record any relevant metadata
	* about the artifact.
	* <p>
	* The default implementation of this method is empty.
	* @param cache The {@link ArtifactCache} that was used to fetch the output file.
	* @param projectFilesystem to use to determine where a metadata file should be written.
	*/
	protected void recordOutputFileDetailsAfterFetchFromArtifactCache(ArtifactCache cache,
	ProjectFilesystem projectFilesystem) throws IOException {
	}

	/**
	* Execute the commands for this build rule. Requires all dependent rules are already built
	* successfully.
	*/
	private void executeCommandsNowThatDepsAreBuilt(BuildContext context)
	throws IOException, StepFailedException {
	context.logBuildInfo("[BUILDING %s]", getFullyQualifiedName());

	// Get and run all of the commands.
	List<Step> steps = buildInternal(context);
	StepRunner stepRunner = context.getStepRunner();
	for (Step step : steps) {
	stepRunner.runStepForBuildTarget(step, getBuildTarget());
	}
	}

	/**
	* When this method is invoked, all of its dependencies will have been built.
	*/
	abstract protected List<Step> buildInternal(BuildContext context) throws IOException;

	/**
	* For a rule that is read from the build cache, it may have fields that would normally be
	* populated by executing the steps returned by {@link #buildInternal(BuildContext)}. Because
	* {@link #buildInternal(BuildContext)} is not invoked for cached rules, a rule may need to
	* implement this method to populate those fields in some other way. For a cached rule, this
	* method will be invoked just before the future returned by {@link #build(BuildContext)} is
	* resolved.
	* <p>
	* By default, this method does nothing except return {@code true}.
	* @param projectFilesystem can be used to load
	* @return whether the internal data structures were populated successfully.
	*/
	protected boolean initializeFromDisk(ProjectFilesystem projectFilesystem) {
	return true;
	}

	/**
	* Record that the outputs for the build rule have been written. They may have been written by
	* either:
	* <ol>
	* <li>The build rule executing all of its steps successfully.
	* <li>The build rule pulling down the output artifacts via the ArtifactCache.
	* </ol>
	*/
	private void recordBuildRuleCompleted(ProjectFilesystem projectFilesystem,
	ArtifactCache artifactCache,
	boolean fromCache)
	throws IOException {
	// Drop our cached output key, since it probably changed.
	resetOutputKey();

	// Write the success file.
	writeSuccessFile(projectFilesystem);

	// Store output to cache.
	String pathToOutputFile = getPathToOutputFile();
	if (pathToOutputFile != null && !fromCache) {
	File output = projectFilesystem.getFileForRelativePath(pathToOutputFile);
	artifactCache.store(getRuleKey(), output);
	}
	}

	/**
	* Write out a file that represents that this build rule succeeded, as well as the inputs that
	* were used. The last-modified time of this file, and its contents, will be used to determine
	* whether this rule should be cached.
	* @throws IOException
	*/
	private void writeSuccessFile(ProjectFilesystem projectFilesystem) throws IOException {
	String path = getPathToSuccessFile();
	projectFilesystem.createParentDirs(path);
	Iterable<String> lines = getSuccessFileStringsForBuildRules();
	projectFilesystem.writeLinesToPath(lines, path);
	}

	private Iterable<String> getSuccessFileStringsForBuildRules() {
	// For now, the one and only line written to the .success file is the RuleKey hash.
	return ImmutableList.of(getRuleKey().toString());
	}

	@VisibleForTesting
	String getPathToSuccessFile() {
	return String.format("%s/%s.success/%s",
	BuckConstant.BIN_DIR,
	getBuildTarget().getBasePathWithSlash(),
	getBuildTarget().getShortName());
	}

	/**
	* Helper function for subclasses to create their lists of files for caching.
	*/
	protected static void addInputsToSortedSet(@Nullable String pathToDirectory,
	ImmutableSortedSet.Builder<String> inputsToConsiderForCachingPurposes,
	DirectoryTraverser traverser) {
	if (pathToDirectory == null) {
	return;
	}
	Set<String> files = DirectoryTraversers.getInstance().findFiles(
	ImmutableSet.of(pathToDirectory), traverser);
	inputsToConsiderForCachingPurposes.addAll(files);
	}
	}