Document requirement of __precompile__

Fixes #13200

Author: yuyichao

base/docs/helpdb/Base.jl

@@ -10127,21 +10127,6 @@ no effect outside of compilation.
 """
 include_dependency
 
-"""
-    __precompile__(isprecompilable::Bool=true)
-
-Specify whether the file calling this function is precompilable. If `isprecompilable` is
-`true`, then `__precompile__` throws an exception when the file is loaded by
-`using`/`import`/`require` *unless* the file is being precompiled, and in a module file it
-causes the module to be automatically precompiled when it is imported. Typically,
-`__precompile__()` should occur before the `module` declaration in the file, or better yet
-`VERSION >= v"0.4" && __precompile__()` in order to be backward-compatible with Julia 0.3.
-
-If a module or file is *not* safely precompilable, it should call `__precompile__(false)` in
-order to throw an error if Julia attempts to precompile it.
-"""
-__precompile__
-
 """
     randn!([rng], A::Array{Float64,N})
 

base/loading.jl

@@ -239,6 +239,22 @@ precompilableerror(ex, c) = false
 # Call __precompile__ at the top of a file to force it to be precompiled (true), or
 # to be prevent it from being precompiled (false).  __precompile__(true) is
 # ignored except within "require" call.
+"""
+    __precompile__(isprecompilable::Bool=true)
+
+Specify whether the file calling this function is precompilable. If `isprecompilable` is
+`true`, then `__precompile__` throws an exception when the file is loaded by
+`using`/`import`/`require` *unless* the file is being precompiled, and in a module file it
+causes the module to be automatically precompiled when it is imported. Typically,
+`__precompile__()` should occur before the `module` declaration in the file, or better yet
+`VERSION >= v"0.4" && __precompile__()` in order to be backward-compatible with Julia 0.3.
+
+If a module or file is *not* safely precompilable, it should call `__precompile__(false)` in
+order to throw an error if Julia attempts to precompile it.
+
+`__precompile__()` should *not* be used in a module unless all of its dependencies are also
+using `__precompile__()`. Failure to do so can result in a runtime error when loading the module.
+"""
 function __precompile__(isprecompilable::Bool=true)
     if (myid() == 1 &&
         JLOptions().use_compilecache != 0 &&

doc/manual/modules.rst

@@ -282,6 +282,10 @@ therein.  If you know that it is *not* safe to precompile your module
 throw an error (and thereby prevent the module from being imported by
 any other precompiled module).
 
+``__precompile__()`` should *not* be used in a module unless all of its
+dependencies are also using ``__precompile__()``. Failure to do so can result
+in a runtime error when loading the module.
+
 In order to make your module work with precompilation,
 however, you may need to change your module to explicitly separate any
 initialization steps that must occur at *runtime* from steps that can

doc/stdlib/base.rst

@@ -142,6 +142,8 @@ Getting Around
 
    If a module or file is *not* safely precompilable, it should call ``__precompile__(false)`` in order to throw an error if Julia attempts to precompile it.
 
+   ``__precompile__()`` should *not* be used in a module unless all of its dependencies are also using ``__precompile__()``\ . Failure to do so can result in a runtime error when loading the module.
+
 .. function:: include(path::AbstractString)
 
    .. Docstring generated from Julia source

doc/stdlib/io-network.rst

@@ -150,7 +150,7 @@ General I/O
 
    .. Docstring generated from Julia source
 
-   Read binary data from a stream, filling in the argument ``array``\ .
+   Read binary data from a stream or file, filling in the argument ``array``\ .
 
 .. function:: readbytes!(stream, b::Vector{UInt8}, nb=length(b); all=true)
 

src/dump.c

@@ -1647,7 +1647,11 @@ static int jl_deserialize_verify_mod_list(ios_t *s)
             jl_errorf("invalid module path (%s does not name a module)", name);
         }
         if (m->uuid != uuid) {
-            jl_printf(JL_STDERR, "WARNING: Module %s uuid did not match cache file\n", name);
+            jl_printf(JL_STDERR,
+                      "WARNING: Module %s uuid did not match cache file\n"
+                      "  This is likely because module %s does not support"
+                      "  precompilation but is imported by a module that does.\n",
+                      name, name);
             return 0;
         }
     }