Clarify cljs.analyzer/cache-file docstring

add `cljs.closure/aot-cache-core` helper, prep for CLJS-897 and
CLJS-899.

`cljs.compiler/compile-file` is now :cache-analysis aware. Previously
compilation would not write out analysis cache files.

Author: swannodette

src/clj/cljs/analyzer.clj

@@ -1886,6 +1886,8 @@ argument, which the reader will use in any emitted errors."
         ret))))
 
 (defn cache-file
+  "Given a ClojureScript source file returns the _output_ path to the analysis
+   cache file."
   ([src] (cache-file src "out"))
   ([src output-dir]
    (if-let [core-cache

src/clj/cljs/closure.clj

@@ -1552,6 +1552,16 @@ should contain the source for the given namespace name."
           goog-ns
           (str goog-ns))))))
 
+(defn aot-cache-core []
+  (let [src (io/file "src" "cljs" "cljs" "core.cljs")
+        dest (io/file "src" "aot_cljs" "cljs" "core.js")]
+    (util/mkdirs dest)
+    (env/with-compiler-env (env/default-compiler-env)
+      (comp/compile-file src dest
+        {:source-map true
+         :cache-analysis true
+         :output-dir "src/aot_cljs"}))))
+
 (comment
 
   (println (build '[(ns hello.core)

src/clj/cljs/compiler.clj

@@ -1072,6 +1072,9 @@
                         (fn [{:keys [recompile visited]}]
                           {:recompile (into recompile (ana/ns-dependents ns))
                            :visited   (conj visited ns)})))
+                    (when (true? (:cache-analysis opts))
+                      (ana/write-analysis-cache ns
+                        (ana/cache-file src (util/output-directory opts))))
                     ret))
                 (do
                   (when-not (contains? (::ana/namespaces @env/*compiler*) ns)