Update cc_import rule documentation

1. Allowing .lib as interface library, which is necessary on Windows
2. Documenting cc_improt by giving specific example use cases.

Change-Id: Ia50850495a1e91fe913ad69f9119753c32f9b4a7
PiperOrigin-RevId: 178754145

3 files changed, 151 insertions, 25 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/cpp/BazelCcImportRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/cpp/BazelCcImportRule.java
index de582d01d4..835a5ff2a2 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/cpp/BazelCcImportRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/cpp/BazelCcImportRule.java
@@ -52,3 +52,118 @@ public final class BazelCcImportRule implements RuleDefinition {
         .build();
   }
 }
+
+/*<!-- #BLAZE_RULE (NAME = cc_import, TYPE = LIBRARY, FAMILY = C / C++) -->
+<p>
+<code>cc_import</code> rules allows users to import precompiled C/C++ libraries.
+</p>
+
+<p>
+The following are the typical use cases: <br/>
+
+1. Linking a static library
+<pre class="code">
+cc_import(
+  name = "mylib",
+  hdrs = ["mylib.h"],
+  static_library = "libmylib.a",
+  # If alwayslink is turned on,
+  # libmylib.a will be forcely linked into any binary that depends on it.
+  # alwayslink = 1,
+)
+</pre>
+
+2. Linking a shared library (Unix)
+<pre class="code">
+cc_import(
+  name = "mylib",
+  hdrs = ["mylib.h"],
+  shared_library = "libmylib.so",
+)
+</pre>
+
+3. Linking a shared library with interface library (Windows)
+<pre class="code">
+cc_import(
+  name = "mylib",
+  hdrs = ["mylib.h"],
+  # mylib.lib is a import library for mylib.dll which will be passed to linker
+  interface_library = "mylib.lib",
+  # mylib.dll will be available for runtime
+  shared_library = "mylib.dll",
+)
+</pre>
+
+4. Linking a shared library with <code>system_provided=1</code> (Windows)
+<pre class="code">
+cc_import(
+  name = "mylib",
+  hdrs = ["mylib.h"],
+  # mylib.lib is an import library for mylib.dll which will be passed to linker
+  interface_library = "mylib.lib",
+  # mylib.dll is provided by system environment, for example it can be found in PATH.
+  # This indicates that Bazel is not responsible for making mylib.dll available.
+  system_provided = 1,
+)
+</pre>
+
+5. Linking to static or shared library <br/>
+
+On Unix:
+<pre class="code">
+cc_import(
+  name = "mylib",
+  hdrs = ["mylib.h"],
+  static_library = "libmylib.a",
+  shared_library = "libmylib.so",
+)
+
+# first will link to libmylib.a
+cc_binary(
+  name = "first",
+  srcs = ["first.cc"],
+  deps = [":mylib"],
+  linkstatic = 1, # default value
+)
+
+# second will link to libmylib.so
+cc_binary(
+  name = "second",
+  srcs = ["second.cc"],
+  deps = [":mylib"],
+  linkstatic = 0,
+)
+</pre>
+
+On Windows:
+<pre class="code">
+cc_import(
+  name = "mylib",
+  hdrs = ["mylib.h"],
+  static_library = "libmylib.lib", # A normal static library
+  interface_library = "mylib.lib", # An import library for mylib.dll
+  shared_library = "mylib.dll",
+)
+
+# first will link to libmylib.lib
+cc_binary(
+  name = "first",
+  srcs = ["first.cc"],
+  deps = [":mylib"],
+  linkstatic = 1, # default value
+)
+
+# second will link to mylib.dll through mylib.lib
+cc_binary(
+  name = "second",
+  srcs = ["second.cc"],
+  deps = [":mylib"],
+  linkstatic = 0,
+)
+</pre>
+
+
+
+</p>
+
+<!-- #END_BLAZE_RULE -->*/
diff --git a/src/main/java/com/google/devtools/build/lib/rules/cpp/CcImportRule.java b/src/main/java/com/google/devtools/build/lib/rules/cpp/CcImportRule.java
index 262e4cc2ad..6529e5c4fb 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/cpp/CcImportRule.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/cpp/CcImportRule.java
@@ -35,28 +35,39 @@ public final class CcImportRule implements RuleDefinition {
     return builder
         /*<!-- #BLAZE_RULE($cc_import).ATTRIBUTE(static_library) -->
           A single precompiled static library.
-          Permited file types: <code>.a</code>, <code>.pic.a</code> or <code>.lib</code>
+          <p> Permitted file types:
+            <code>.a</code>,
+            <code>.pic.a</code>
+            or <code>.lib</code>
+          </p>
         <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
         .add(
             attr("static_library", LABEL)
-                .allowedFileTypes(CppFileTypes.ARCHIVE, CppFileTypes.PIC_ARCHIVE)
-        )
+                .allowedFileTypes(CppFileTypes.ARCHIVE, CppFileTypes.PIC_ARCHIVE))
         /*<!-- #BLAZE_RULE($cc_import).ATTRIBUTE(shared_library) -->
-          A single precompiled shared library
-          Permited file types: <code>.so</code>, <code>.dll</code> or <code>.dylib</code>
+          A single precompiled shared library. Bazel ensures it is available to the
+          binary that depends on it during runtime.
+          <p> Permitted file types:
+            <code>.so</code>,
+            <code>.dll</code>
+            or <code>.dylib</code>
+          </p>
         <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
-        .add(attr("shared_library", LABEL)
-            .allowedFileTypes(CppFileTypes.SHARED_LIBRARY)
-        )
-        /*<!-- #BLAZE_RULE($cc_import).ATTRIBUTE(shared_library) -->
-          A single interface library for linking the shared library
-          Permited file types: <code>.ifso</code>, <code>.tbd</code>, <code>.so</code> or
-          <code>.dylib</code>
+        .add(attr("shared_library", LABEL).allowedFileTypes(CppFileTypes.SHARED_LIBRARY))
+        /*<!-- #BLAZE_RULE($cc_import).ATTRIBUTE(interface_library) -->
+          A single interface library for linking the shared library.
+          <p> Permitted file types:
+            <code>.ifso</code>,
+            <code>.tbd</code>,
+            <code>.lib</code>,
+            <code>.so</code>
+            or <code>.dylib</code>
+          </p>
         <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
-        .add(attr("interface_library", LABEL)
-            .allowedFileTypes(
-                CppFileTypes.INTERFACE_SHARED_LIBRARY,
-                CppFileTypes.UNIX_SHARED_LIBRARY))
+        .add(
+            attr("interface_library", LABEL)
+                .allowedFileTypes(
+                    CppFileTypes.INTERFACE_SHARED_LIBRARY, CppFileTypes.UNIX_SHARED_LIBRARY))
         /*<!-- #BLAZE_RULE($cc_import).ATTRIBUTE(hdrs) -->
           The list of header files published by
           this precompiled library to be directly included by sources in dependent rules.
@@ -66,13 +77,12 @@ public final class CcImportRule implements RuleDefinition {
                 .orderIndependent()
                 .direct_compile_time_input()
                 .allowedFileTypes(CppFileTypes.CPP_HEADER))
-        /*<!-- #BLAZE_RULE(cc_import).ATTRIBUTE(system_provide) -->
-        If true, it indicates the shared library required at runtime is provided by the system. In
+        /*<!-- #BLAZE_RULE(cc_import).ATTRIBUTE(system_provided) -->
+        If 1, it indicates the shared library required at runtime is provided by the system. In
         this case, <code>interface_library</code> should be specified and
         <code>shared_library</code> should be empty.
         <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
-        .add(
-            attr("system_provided", BOOLEAN))
+        .add(attr("system_provided", BOOLEAN))
         /*<!-- #BLAZE_RULE(cc_import).ATTRIBUTE(alwayslink) -->
         If 1, any binary that depends (directly or indirectly) on this C++
         precompiled library will link in all the object files archived in the static library,
@@ -81,11 +91,12 @@ public final class CcImportRule implements RuleDefinition {
         the binary, e.g., if your code registers to receive some callback
         provided by some service.
         <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
+        .add(attr("alwayslink", BOOLEAN))
         .add(
-            attr("alwayslink", BOOLEAN))
-        .add(attr("data", LABEL_LIST).cfg(DATA)
-            .allowedFileTypes(FileTypeSet.ANY_FILE)
-            .dontCheckConstraints())
+            attr("data", LABEL_LIST)
+                .cfg(DATA)
+                .allowedFileTypes(FileTypeSet.ANY_FILE)
+                .dontCheckConstraints())
         .build();
   }
 
diff --git a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppFileTypes.java b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppFileTypes.java
index fd2c60fcc9..c63f7d8e00 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppFileTypes.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppFileTypes.java
@@ -134,7 +134,7 @@ public final class CppFileTypes {
   public static final FileType SHARED_LIBRARY = FileType.of(".so", ".dylib", ".dll");
   // Unix shared libraries can be passed to linker, but not .dll on Windows
   public static final FileType UNIX_SHARED_LIBRARY = FileType.of(".so", ".dylib");
-  public static final FileType INTERFACE_SHARED_LIBRARY = FileType.of(".ifso", ".tbd");
+  public static final FileType INTERFACE_SHARED_LIBRARY = FileType.of(".ifso", ".tbd", ".lib");
   public static final FileType LINKER_SCRIPT = FileType.of(".ld", ".lds", ".ldscript");
 
   // Windows DEF file: https://msdn.microsoft.com/en-us/library/28d6s79h.aspx