Add bucklets documentation
Change-Id: I7d491127cd93e7b28b02bd8070a8deaf49de48b4
diff --git a/java7.bucklet b/java7.bucklet
index 488fba4..c7996ca 100644
--- a/java7.bucklet
+++ b/java7.bucklet
@@ -1,4 +1,25 @@
-# see https://github.com/facebook/buck/pull/67
+# Current Buck version lacks support to overwrite Java version
+# in .buckconfig file, under Java section, e. g.:
+#
+# [java]
+# src_roots = java, resources
+# source = 7
+# target = 7
+#
+# Instead, the documentaion suggests to provide Java version in
+# each and every java_library() call.
+#
+# This bucklet overwrites the definition of original java_library
+# and java_test rules.
+#
+# Example: this bucklet must be used in .buckconfig file, under
+# include section to ensure, that this file is seen before others:
+#
+# [buildfile]
+# includes = //bucklets/java7.bucklet
+#
+# @See https://github.com/facebook/buck/pull/67
+#
original_java_library = java_library
def java_library(
name,
diff --git a/java8.bucklet b/java8.bucklet
index 1fb22aa..d7ebe06 100644
--- a/java8.bucklet
+++ b/java8.bucklet
@@ -1,4 +1,25 @@
-# see https://github.com/facebook/buck/pull/67
+# Current Buck version lacks support to overwrite Java version
+# in .buckconfig file, under Java section, e. g.:
+#
+# [java]
+# src_roots = java, resources
+# source = 8
+# target = 8
+#
+# Instead, the documentaion suggests to provide Java version in
+# each and every java_library() call.
+#
+# This bucklet overwrites the definition of original java_library
+# and java_test rules.
+#
+# Example: this bucklet must be used in .buckconfig file, under
+# include section to ensure, that this file is seen before others:
+#
+# [buildfile]
+# includes = //bucklets/java8.bucklet
+#
+# @See https://github.com/facebook/buck/pull/67
+#
original_java_library = java_library
def java_library(
name,
diff --git a/java_doc.bucklet b/java_doc.bucklet
index 8df3f85..426ef45 100644
--- a/java_doc.bucklet
+++ b/java_doc.bucklet
@@ -1,3 +1,17 @@
+# This bucklet simplifies creation of Javadocs
+#
+# Example:
+#
+# java_doc(
+# name = 'javadoc',
+# title = 'Gitiles API Documentation',
+# pkg = 'com.google.gitiles',
+# paths = ['gitiles-servlet/src/main/java'],
+# srcs = glob([n + '**/*.java' for n in SRCS]),
+# deps = DEPS,
+# visibility = ['PUBLIC'],
+# )
+#
def java_doc(
name,
title,
diff --git a/java_library2.bucklet b/java_library2.bucklet
index 8fe78e8..8bfc5ab 100644
--- a/java_library2.bucklet
+++ b/java_library2.bucklet
@@ -1,7 +1,20 @@
# Compiles a Java library with additional compile-time dependencies
# that do not show up as transitive dependencies to java_library()
# or java_binary() rule that depends on this library.
-# work around for: https://github.com/facebook/buck/issues/63
+#
+# Example: servlet library needs to be compiled against servlet API
+# but this dependency must not become a transitive dependency.
+#
+# java_library2(
+# name = 'gitiles-servlet',
+# srcs = SRCS,
+# resources = RSRC,
+# deps = DEPS,
+# compile_deps = ['//lib:servlet-api'],
+# visibility = ['PUBLIC'],
+# )
+# @See: https://github.com/facebook/buck/issues/63
+#
def java_library2(
name,
srcs = [],
diff --git a/java_sources.bucklet b/java_sources.bucklet
index 0b3974e..b2c6a19 100644
--- a/java_sources.bucklet
+++ b/java_sources.bucklet
@@ -1,3 +1,13 @@
+# This bucklet simplifies creation of Java source archives
+#
+# Example:
+#
+# java_sources(
+# name = 'src',
+# srcs = SRCS + RSRC,
+# visibility = ['PUBLIC'],
+# )
+#
def java_sources(
name,
srcs,
diff --git a/local_jar.bucklet b/local_jar.bucklet
index 8131daa..6e06ce9 100644
--- a/local_jar.bucklet
+++ b/local_jar.bucklet
@@ -8,17 +8,19 @@
# local Maven repository and fetching it again from there out of the picture,
# `local_jar()` method is used:
#
+# Example:
+#
# 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',
+# src_jar = '/home/<user>/projects/jgit/org.eclipse.jgit/target/org.eclipse.jgit-3.3.0-SNAPSHOT-sources.jar',
# deps = [':ewah']
# )
-
+#
def local_jar(
name,
jar,
- src = None,
+ src_jar = None,
deps = [],
visibility = ['PUBLIC']):
binjar = name + '.jar'
@@ -27,10 +29,10 @@
name = name + '__local_bin',
cmd = 'ln -s %s $OUT' % jar,
out = binjar)
- if src:
+ if src_jar:
genrule(
name = name + '__local_src',
- cmd = 'ln -s %s $OUT' % src,
+ cmd = 'ln -s %s $OUT' % src_jar,
out = srcjar)
prebuilt_jar(
name = name + '_src',
diff --git a/maven_jar.bucklet b/maven_jar.bucklet
index 19a06f9..b5c6335 100644
--- a/maven_jar.bucklet
+++ b/maven_jar.bucklet
@@ -1,6 +1,32 @@
#
# Fetch artifacts from Maven repository
-# see: https://github.com/facebook/buck/issues/64
+#
+# name: (required) The name of the rule.
+# id: (required) Maven group id, artifact id and version in the form: g:a:v
+# exclude: (defaults to []) Rules to exlude from resulting maven JAR
+# exclude_java_sources: (default to False) should java source be included
+# unsign: (default to False): should this archive be unsigned
+# deps: (defaults to []) Rules (usually other java_library rules) that are
+# included as transitive dependency of this Maven JAR
+# exported_deps: (defaults to []) Whether or not depending on this rule should
+# also transitively pull in all of its dependencies.
+# sha1: SHA-1 of binary artifact
+# bin_sha1: SHA-1 of binary artifact
+# src_sha1: SHA-1 of src artifact
+# repository: (default to MAVEN_CENTRAL) repository name
+# attach_source: (default to True): should the sources be fetched
+# visibility (defaults to ['PUBLIC']) List of build target patterns that
+# identify the build rules that can include this rule in its deps.
+#
+# Example:
+#
+# maven_jar(
+# name = 'guava',
+# id = 'com.google.guava:guava:16.0',
+# sha1 = 'aca09d2e5e8416bf91550e72281958e35460be52',
+# )
+#
+# @See: https://github.com/facebook/buck/issues/64
#
GERRIT = 'GERRIT:'
diff --git a/maven_package.bucklet b/maven_package.bucklet
index 0e865b6..8bd6720 100644
--- a/maven_package.bucklet
+++ b/maven_package.bucklet
@@ -1,17 +1,16 @@
-# Copyright (C) 2013 The Android Open Source Project
+# Install and deploy artifacts into local and remote Maven repositories
#
-# 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
+# Example:
#
-# http://www.apache.org/licenses/LICENSE-2.0
+# maven_package(
+# repository = 'gerrit-api-repository',
+# url = 'gs://gerrit-api/release',
+# version = '1.0',
+# jar = {'gitiles-servlet': '//gitiles-servlet:servlet'},
+# src = {'gitiles-servlet': '//gitiles-servlet:src'},
+# doc = {'gitiles-servlet': '//gitiles-servlet:javadoc'},
+# )
#
-# 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.
-
def maven_package(
version,
repository = None,
diff --git a/war.bucklet b/war.bucklet
index 2987e05..8341e2d 100644
--- a/war.bucklet
+++ b/war.bucklet
@@ -1,3 +1,16 @@
+# This bucklet simplifies creation of war archives.
+#
+# Example:
+#
+# war(
+# name = 'gitiles',
+# libs = ['//gitiles-servlet:servlet'],
+# context = [
+# ':recourses.zip',
+# ],
+# visibility = ['PUBLIC']
+# )
+#
def war(
name,
libs = [],
