Add new tools/upstream/upstream-diff script.

This is a more flexible version of the 'meld' command that
was previously in the .tsv produced by libcore-compare-upstreams
The code that produces that .tsv has been changed to call the
new script.

The new script ads the following features:

 1.) Compare multiple files against upstream in a single command
     (this will launch multiple 'meld' processes in sequence):
     ./upstream-diff java/util/ArrayList.java java/util/LinkedList
 2.) Specify files to compare via their fully qualified name
     rather than the relative path of the .java file:
     ./upstream-diff java.util.ArrayList
 3.) Use a diff/merge tool other than meld:
     ./upstream-diff -d kdiff3 java.util.ArrayList
     ./upstream-diff -d diff java.util.ArrayList
 4.) Customize repositories to diff against, eg. three-way merge
     for integrating upstream changes:
     ./upstream-diff -r 7u40,ojluni,8u121-b13 java.util.ArrayList

Test: libcore/tools/upstream/upstream-diff java.nio.ByteBuffer
Test: make libcore-compare-upstreams && java -jar \
      ${ANDROID_HOST_OUT}/framework/libcore-compare-upstreams.jar \
      > ~/compare-upstreams.tsv

Change-Id: I5bc2354049f0a9a087dce588a441b09ea531bc3a

2 files changed, 95 insertions, 5 deletions

diff --git a/tools/upstream/src/main/java/libcore/CompareUpstreams.java b/tools/upstream/src/main/java/libcore/CompareUpstreams.java
index dc00f2457c..fa6bd4fbe9 100644
--- a/tools/upstream/src/main/java/libcore/CompareUpstreams.java
+++ b/tools/upstream/src/main/java/libcore/CompareUpstreams.java
@@ -230,11 +230,7 @@ public class CompareUpstreams {
             if (!comparisons.get(0).equals("identical")) {
                 Path expectedUpstreamPath = expectedUpstream.pathFromRepository(relPath);
                 if (expectedUpstreamPath != null) {
-                    diffCommand = String.format(Locale.US, "meld \"%s\" \"%s\"",
-                            "${ANDROID_BUILD_TOP}/libcore/"
-                                    + standardRepositories.ojluni().pathFromRepository(relPath),
-                            "${OJLUNI_UPSTREAMS}/" + expectedUpstream.name() + "/" + relPath);
-                            //"${OPENJDK_HOME}/" + expectedUpstreamPath;
+                    diffCommand = "${ANDROID_BUILD_TOP}/libcore/tools/upstream/upstream-diff " + relPath;
                 } else {
                     diffCommand = "FILE MISSING";
                 }
diff --git a/tools/upstream/upstream-diff b/tools/upstream/upstream-diff
new file mode 100755
index 0000000000..f52fdb5b03
--- /dev/null
+++ b/tools/upstream/upstream-diff
@@ -0,0 +1,94 @@
+#!/usr/bin/python
+#
+# Copyright (C) 2017 The Android Open Source Project
+#
+# 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.
+
+"""
+Compares one or more corresponding files from ojluni against one or
+more upstream or from upstreams against each other.
+The repositories (default: ojluni vs. expected current upstream) and
+the diff tool (default: meld) can be specified by command line options.
+
+This tool is for libcore maintenance; if you're not maintaining libcore,
+you won't need it (and might not have access to some of the instructions
+below).
+
+The naming of the repositories (expected, ojluni, 7u40, 8u121-b13,
+9b113+, 9+181) is based on the directory name where corresponding
+snapshots are stored when following the instructions at
+http://go/libcore-o-verify
+
+This in turn derives from the instructions at the top of:
+libcore/tools/upstream/src/main/java/libcore/CompareUpstreams.java
+
+Possible uses:
+
+To verify that ArrayList has been updated to the expected upstream
+and that all local patches carry change markers, we compare that
+file from ojluni against the expected upstream (the default):
+  upstream-diff java/util/ArrayList.java
+
+To verify multiple files:
+
+  upstream-diff java.util.ArrayList java.util.LinkedList
+
+Use a three-way merge to integrate changes from 9+181 into ArrayList:
+  upstream-diff -r 8u121-b13,ojluni,9+181 java/util/ArrayList.java
+or to investigate which version of upstream introduced a change:
+  upstream-diff -r 7u40,8u60,8u121-b13 java/util/ArrayList.java
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+
+def run_diff(diff, repositories, rel_paths):
+    # Root of checked-out Android sources, set by the "lunch" command.
+    android_build_top = os.environ['ANDROID_BUILD_TOP']
+    # Root of repository snapshots. See go/libcore-o-verify for how you'd want to set this.
+    ojluni_upstreams = os.environ['OJLUNI_UPSTREAMS']
+    for rel_path in rel_paths:
+        if not rel_path.endswith('.java'):
+            # Might be a fully qualified class name
+            rel_path = rel_path.replace('.', '/') + '.java'
+        paths = []
+        for repository in repositories:
+            if repository == "ojluni":
+                paths.append('%s/libcore/ojluni/src/main/java/%s' % (android_build_top, rel_path))
+            else:
+                paths.append('%s/%s/%s' % (ojluni_upstreams, repository, rel_path))
+        subprocess.call([diff] + paths)
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Compare files between libcore/ojluni and ${OJLUNI_UPSTREAMS}.')
+    parser.add_argument('-r', '--repositories', default='ojluni,expected',
+                    help='Comma-separated list of >= 2 repositories to compare.')
+    parser.add_argument('-d', '--diff', default='meld',
+                        help='Application to use for diffing.')
+    parser.add_argument('rel_path', nargs="+",
+                        help='File to compare: either a relative path below '
+                             'libcore/ojluni/src/main/java, or a fully qualified class name.')
+    args = parser.parse_args()
+    repositories = args.repositories.split(',')
+    if (len(repositories) < 2):
+        print('Expected >= 2 repositories to compare, got: ' + str(repositories))
+        parser.print_help()
+        sys.exit(1)
+    run_diff(args.diff, repositories, args.rel_path)
+
+if __name__ == "__main__":
+    main()
+