From e28689c42f666b19a50fb9e62bafec3691c63d8c Mon Sep 17 00:00:00 2001 From: Alex Humesky Date: Mon, 10 Aug 2015 22:22:52 +0000 Subject: Updates documentation for bind, new_http_archive, and new_git_repository for consistency, accuracy, and clarity. -- MOS_MIGRATED_REVID=100320358 --- .../rules/workspace/NewGitRepositoryRule.java | 10 +++---- .../bazel/rules/workspace/NewHttpArchiveRule.java | 10 +++---- .../build/lib/rules/workspace/BindRule.java | 32 ++++++++++------------ 3 files changed, 24 insertions(+), 28 deletions(-) (limited to 'src/main/java/com/google') diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewGitRepositoryRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewGitRepositoryRule.java index 2a57a9bb24..8db1205c3d 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewGitRepositoryRule.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewGitRepositoryRule.java @@ -53,12 +53,12 @@ public class NewGitRepositoryRule implements RuleDefinition { */ .add(attr("tag", STRING)) /* - A file to use as a BUILD file for this directory. + The file to use as the BUILD file for this repository. ${SYNOPSIS}

This path is relative to the build's workspace. The file does not need to be named - BUILD, but can be (something like BUILD.new-repo-name may work well for distinguishing it - from the repository's actual BUILD files.

+ BUILD, but can be something like BUILD.new-repo-name to distinguish it + from the workspace's actual BUILD files.

*/ .add(attr("build_file", STRING).mandatory()) /* @@ -107,7 +107,7 @@ src/ openssl.h -

In the local repository, the user creates a ssl.BUILD file which contains the following +

In the local repository, the user creates a BUILD.ssl file which contains the following target definition:

@@ -126,7 +126,7 @@ new_git_repository(
     name = "my-ssl",
     remote = "http://example.com/openssl/openssl.git",
     tag = "v1.0.2",
-    build_file = "ssl.BUILD",
+    build_file = "BUILD.ssl",
 )
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewHttpArchiveRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewHttpArchiveRule.java index 7a10c17489..768b7c1977 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewHttpArchiveRule.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewHttpArchiveRule.java @@ -46,12 +46,12 @@ public class NewHttpArchiveRule implements RuleDefinition { */ .add(attr("sha256", STRING).mandatory()) /* - A file to use as a BUILD file for this directory. + The file to use as the BUILD file for this repository. ${SYNOPSIS}

This path is relative to the build's workspace. The file does not need to be named - BUILD, but can be (something like BUILD.new-repo-name may work well for distinguishing it - from the repository's actual BUILD files.

+ BUILD, but can be something like BUILD.new-repo-name to distinguish it + from the workspace's actual BUILD files.

*/ .add(attr("build_file", STRING).mandatory()) /* @@ -102,7 +102,7 @@ src/ openssl.h -

In the local repository, the user creates a ssl.BUILD file which contains the following +

In the local repository, the user creates a BUILD.ssl file which contains the following target definition:

@@ -121,7 +121,7 @@ new_http_archive(
     name = "my-ssl",
     url = "http://example.com/openssl.zip",
     sha256 = "03a58ac630e59778f328af4bcc4acb4f80208ed4",
-    build_file = "ssl.BUILD",
+    build_file = "BUILD.ssl",
 )
diff --git a/src/main/java/com/google/devtools/build/lib/rules/workspace/BindRule.java b/src/main/java/com/google/devtools/build/lib/rules/workspace/BindRule.java index 1d26ba8ffe..45acf445b0 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/workspace/BindRule.java +++ b/src/main/java/com/google/devtools/build/lib/rules/workspace/BindRule.java @@ -72,9 +72,10 @@ ${ATTRIBUTE_DEFINITION}

Examples

-

To give a target an alias, bind it in the WORKSPACE file. For example, suppose there is - a java_library target called //third_party/javacc-v2. This could be - aliased by adding the following to the WORKSPACE file:

+

To give a target an alias, bind it in the WORKSPACE file. For example, + suppose there is a java_library target called + //third_party/javacc-v2. This can be aliased by adding the following to the + WORKSPACE file:

 bind(
@@ -84,14 +85,14 @@ bind(

Now targets can depend on //external:javacc-latest instead of - //third_party/javacc-v2. If javacc-v3 is released, the binding can be updated and - all of the BUILD files depending on //external:javacc-latest will now depend on - javacc-v3 without needing to be edited.

+ //third_party/javacc-v2. If javacc-v3 is released, the bind rule can be + updated and all of the BUILD files depending on //external:javacc-latest will now + depend on javacc-v3 without needing to be edited.

-

Bind can also be used to refer to external repositories' targets. For example, if there is a - remote repository named @my-ssl imported in the WORKSPACE file. If the - @my-ssl repository has a cc_library target //src:openssl-lib, you - could make this target accessible for your program to depend on by using bind:

+

Bind can also be used to make targets in external repositories available to your workspace. + For example, if there is a remote repository named @my-ssl imported in the + WORKSPACE file and it has a cc_library target //src:openssl-lib, you can + create an alias for this target using bind:

 bind(
@@ -100,12 +101,7 @@ bind(
 )
-

BUILD files cannot use labels that include a repository name - ("@repository-name//package-name:target-name"), so the only way to depend on a target from - another repository is to bind it in the WORKSPACE file and then refer to it by its - aliased name in //external from a BUILD file.

- -

For example, in a BUILD file, the bound target could be used as follows:

+

Then, in a BUILD file in your workspace, the bound target can be used as follows:

 cc_library(
@@ -117,7 +113,7 @@ cc_library(

Within sign_in.cc and sign_in.h, the header files exposed by - //external:openssl can be referred to by their path relative to their repository + //external:openssl can be referred to using their path relative to their repository root. For example, if the rule definition for @my-ssl//src:openssl-lib looks like this:

@@ -129,7 +125,7 @@ cc_library( ) -

Then sign_in.cc's first lines might look like this:

+

Then sign_in.cc's includes might look like this:

 #include "sign_in.h"
-- 
cgit v1.2.3