Adds some documentation specific to the `make` rule. (#1050)

foreign_cc/make.bzl

@@ -94,7 +94,9 @@ def _attrs():
         "targets": attr.string_list(
             doc = (
                 "A list of targets within the foreign build system to produce. An empty string (`\"\"`) will result in " +
-                "a call to the underlying build system with no explicit target set"
+                "a call to the underlying build system with no explicit target set. However, in order to extract build " +
+                "outputs, you must execute at least an equivalent of make install, and have your make file copy the build " +
+                "outputs into the directory specified by `install_prefix`."
             ),
             mandatory = False,
             default = ["", "install"],
@@ -107,7 +109,18 @@ make = rule(
         "Rule for building external libraries with GNU Make. " +
         "GNU Make commands (make and make install by default) are invoked with PREFIX=\"install\" " +
         "(by default), and other environment variables for compilation and linking, taken from Bazel C/C++ " +
-        "toolchain and passed dependencies."
+        "toolchain and passed dependencies. " +
+        "Not all Makefiles will work equally well here, and some may require patching." +
+        "Your Makefile must either support passing the install prefix using the PREFIX flag, or " +
+        "it needs to have a different way to pass install prefix to it. An equivalent of " +
+        "make install MUST be specified as one of the targets." +
+        "This is because all the paths with param names prefixed by out_* are expressed " +
+        "as relative to INSTALLDIR, not the source directory." +
+        "That is, if you execute only make, but not make install, this rule will not be able " +
+        "to pick up any build outputs. Finally, your make install rule must dereference symlinks " +
+        "to ensure that the installed files don't end up being symlinks to files in the sandbox. " +
+        "For example, installation lines like `cp $SOURCE $DEST` must become `cp -L $SOURCE $DEST`, " +
+        "as the -L will ensure that symlinks are dereferenced."
     ),
     attrs = _attrs(),
     fragments = CC_EXTERNAL_RULE_FRAGMENTS,

foreign_cc/private/framework.bzl

@@ -139,7 +139,7 @@ CC_EXTERNAL_RULE_ATTRIBUTES = {
         default = [],
     ),
     "out_bin_dir": attr.string(
-        doc = "Optional name of the output subdirectory with the binary files, defaults to 'bin'.",
+        doc = "Optional name of the output subdirectory with the binary files, defaults to 'bin'. ",
         mandatory = False,
         default = "bin",
     ),