Merge "Buck: add local_jar() to link direct to local Maven targets"

Documentation/dev-buck.txt

@@ -322,6 +322,47 @@ that artifact:
  )
 ----
 
+== Building against unpublished JARs, that change frequently
+
+If a dependent Gerrit library is undergoing active development it must be
+recompiled and the change must be reflected in the Buck build process. For
+example testing Gerrit against changed JGit snapshot version. After building
+JGit library, the artifacts are created in local Maven build directory, e. g.:
+
+----
+  mvn package
+  /home/<user>/projects/jgit/org.eclipse.jgit/target/org.eclipse.jgit-3.3.0-SNAPSHOT.jar
+  /home/<user>/projects/jgit/org.eclipse.jgit/target/org.eclipse.jgit-3.3.0-SNAPSHOT-sources.jar
+----
+
+If as usual, installation of the build artifacts takes place in local maven
+repository, then the Buck build must fetch them from there with normal
+`download_file.py` process. Disadvantage of this approach is that Buck cache
+invalidation must occur to refresh the artifacts after next
+change-compile-install round trip.
+
+To shorten that workflow and take the installation of the artifacts to the
+local Maven repository and fetching it again from there out of the picture,
+`local_jar()` method is used instead of `maven_jar()`:
+
+[source,python]
+----
+ local_jar(
+   name = 'jgit',
+   jar = '/home/<user>/projects/jgit/org.eclipse.jgit/target/org.eclipse.jgit-3.3.0-SNAPSHOT.jar',
+   src = '/home/<user>/projects/jgit/org.eclipse.jgit/target/org.eclipse.jgit-3.3.0-SNAPSHOT-sources.jar',
+   deps = [':ewah']
+ )
+----
+
+This creates a symlink to the Buck targets direct against artifacts in
+another project's Maven target directory:
+
+----
+  buck-out/gen/lib/jgit/jgit.jar ->
+  /home/<user>/projects/jgit/org.eclipse.jgit/target/org.eclipse.jgit-3.3.0-SNAPSHOT.jar
+----
+
 == Building against artifacts from custom Maven repositories
 
 To build against custom Maven repositories, two modes of operations are

lib/maven.defs

@@ -124,3 +124,37 @@ def maven_jar(
       source_jar = genfile(srcjar) if srcjar else None,
       visibility = visibility,
     )
+
+def local_jar(
+    name,
+    jar,
+    src = None,
+    deps = [],
+    visibility = ['PUBLIC']):
+  binjar = name + '.jar'
+  srcjar = name + '-src.jar'
+  genrule(
+    name = name + '__local_bin',
+    cmd = 'ln -s %s $OUT' % jar,
+    out = binjar)
+  if src:
+    genrule(
+      name = name + '__local_src',
+      cmd = 'ln -s %s $OUT' % src,
+      out = srcjar)
+    prebuilt_jar(
+      name = name + '_src',
+      deps = [':' + name + '__local_src'],
+      binary_jar = genfile(srcjar),
+      visibility = visibility,
+    )
+  else:
+    srcjar = None
+
+  prebuilt_jar(
+    name = name,
+    deps = deps + [':' + name + '__local_bin'],
+    binary_jar = genfile(binjar),
+    source_jar = genfile(srcjar) if srcjar else None,
+    visibility = visibility,
+  )