Recover from class files and Analysis object getting out of sync.

The #958 describes a scenario where partially successful results are
produced in form of class files written to disk. However, if compilation
fails down the road we do not record any new compilation results (products)
in Analysis object. This leads to Analysis object and disk contents to get
out of sync.

One way to solve this problem is to use transactional ClassfileManager that
commits changes to class files on disk only when entire incremental
compilation session is successful. Otherwise, new class files are rolled
back to previous state.

The other way to solve this problem is to record time stamps of class files
in Analysis object. This way, incremental compiler can detect that class
files and Analysis object got out of sync and recover from that by
recompiling corresponding sources.

This commit uses latter solution which enables simpler (non-transactional)
ClassfileManager to handle scenario from #958.

Fixes #958
simplified settings core example (as per `util/collection` `SettingsExample`)
Generate an error when the incremental compiler is given relative source files.  Fixes #923.

Review by @gkossakowski
Fix type error in example code

Fix #971.

Note that this is no complete fix, because this solution uses an
operator which is not any more described in the guide for 0.13.
More detailed logging of incremental compiler's invalidation logic.

The following events are logged:

  * invalidation of source file due to macro definition
  * inclusion of dependency invalidated by inheritance; we log both
    nodes of dependency edge (dependent and dependency)

The second bullet helps to understand what's going on in case of
complex inheritance hierarchies like in Scala compiler.
Docs: correct substitution syntax when preceding character is symbol.  Fixes #970.
Fix source-dependencies/relative-source-error to use explicit reloads.  Ref #923.
Represent api changes as values and cleanup APIChanges class.

The main motivation behind this commit is to reify information about
api changes that incremental compiler considers. We introduce a new
sealed class `APIChange` that has (at the moment) two subtypes:

  * APIChangeDueToMacroDefinition - as the name explains, this represents
    the case where incremental compiler considers an api to be changed
    just because given source file contains a macro definition
  * SourceAPIChange - this represents the case of regular api change;
    at the moment it's just a simple wrapper around value representing
    source file but in the future it will get expanded to contain more
    detailed information about API changes (e.g. collection of changed
    name hashes)

The APIChanges becomes just a collection of APIChange instances.
In particular, I removed `names` field that seems to be a dead code in
incremental compiler. The `NameChanges` class and methods that refer to
it in `SameAPI` has been deprecated.

The Incremental.scala has been adapted to changed signature of APIChanges
class. The `sameSource` method returns representation of APIChange
(if there's one) instead of just simple boolean. One notable change is
that information about APIChanges is pushed deeper into invalidation logic.
This will allow us to treat the APIChangeDueToMacroDefinition case properly
once name hashing scheme arrives.

This commit shouldn't change any behavior and is purely a refactoring.
Merge pull request #941 from gkossakowski/apichanges-refactor

More detailed logging and APIChanges refactoring
Desugar case class IncOptions in binary compatible way.

Expand case class `IncOptions` in binary compatible way so we can have
better control of methods like `unapply` when new fields are added.

Great precaution has been taken to ensure that this commit doesn't break
binary compatibility. I took a dump of javap output before and after
this change for both the class and it's companion object.
The diff is presented below:

diff -u ~/inc-options-before ~/inc-options-after
--- /Users/grek/inc-options-before	2013-11-03 14:48:45.000000000 +0100
+++ /Users/grek/inc-options-after	2013-11-03 15:53:10.000000000 +0100
@@ -9,7 +9,11 @@
     public static java.lang.String transitiveStepKey();
     public static sbt.inc.IncOptions setTransactional(sbt.inc.IncOptions, java.io.File);
     public static sbt.inc.IncOptions defaultTransactional(java.io.File);
+    public static scala.Option unapply(sbt.inc.IncOptions);
+    public static sbt.inc.IncOptions apply(int, double, boolean, boolean, int, scala.Option, scala.Function0);
     public static sbt.inc.IncOptions Default();
+    public static scala.Function1 tupled();
+    public static scala.Function1 curried();
     public int transitiveStep();
     public double recompileAllFraction();
     public boolean relationsDebug();

diff -u inc-options-module-before inc-options-module-after
--- inc-options-module-before	2013-11-03 14:48:55.000000000 +0100
+++ inc-options-module-after	2013-11-12 21:00:41.000000000 +0100
@@ -3,6 +3,9 @@
     public static final sbt.inc.IncOptions$ MODULE$;
     public static {};
     public sbt.inc.IncOptions Default();
+    public final java.lang.String toString();
+    public sbt.inc.IncOptions apply(int, double, boolean, boolean, int, scala.Option, scala.Function0);
+    public scala.Option unapply(sbt.inc.IncOptions);
     public sbt.inc.IncOptions defaultTransactional(java.io.File);
     public sbt.inc.IncOptions setTransactional(sbt.inc.IncOptions, java.io.File);
     public java.lang.String transitiveStepKey();
@@ -13,7 +16,5 @@
     public java.lang.String apiDiffContextSize();
     public sbt.inc.IncOptions fromStringMap(java.util.Map);
     public java.util.Map toStringMap(sbt.inc.IncOptions);
-    public sbt.inc.IncOptions apply(int, double, boolean, boolean, int, scala.Option, scala.Function0);
-    public scala.Option unapply(sbt.inc.IncOptions);
 }

The first diff shows that there are just more static forwarders defined
for top-level companion object and that is binary compatible change.

The second diff shows that there are just a few minor differences in
order in which `unapply`, `apply` and bridge method for `apply` are
defined. Also, there's a new `toString` declaration. All those changes are
binary compatible.

All methods that are generated for a case class are marked as deprecated
and will be removed in the future.
Add specialized copy methods to IncOptions class.

Add methods that allow one to set a new value to one of the fields of
IncOptions class. These methods are meant to be an alternative to
copy method that is hard to keep binary compatible when new fields are
added to the class.

Each copying method is related to one field of the class so when new
fields are added existing methods (and their signatures) are unaffected.
Make recompilation on macro definition optional.

Introduce a new incremental compiler option that controls
incremental compiler's treatment of macro definitions and their clients.
The current strategy is that whenever a source file containing a macro
definition is touched it will cause recompilation of all direct
dependencies of that file.

That strategy has proven to be too conservative for some projects like
Scala compiler of specs2 leading to too many source files being recompiled.
We make this behavior optional by introducing a new option
`recompileOnMacroDef` in `IncOptions` class. The default value is set to
`true` which preserves the previous behavior.
Mark fields storing keys in IncOptions as private.

It was an omission in the original commit that introduced them and didn't
mark them as private. They are purely an implementation detail and should
be hidden. We hiding them now.
Merge pull request #976 from gkossakowski/macro-handling

Make recompilation on macro definition optional