'nimcache' defaults to ~/.cache on Posix; cleaned up documentation

changelog.md

@@ -20,7 +20,7 @@
 - The parser now warns about inconsistent spacing around binary operators as
   these can easily be confused with unary operators. This warning will likely
   become an error in the future.
-- The ``'c`` and ``'C'`` prefix for octal literals is now deprecated to
+- The ``'c`` and ``'C'`` suffix for octal literals is now deprecated to
   bring the language in line with the standard library (e.g. ``parseOct``).
 - The dot style for import paths (e.g ``import path.to.module`` instead of
   ``import path/to/module``) has been deprecated.
@@ -67,6 +67,9 @@
 
 - The undocumented ``#? braces`` parsing mode was removed.
 - The undocumented PHP backend was removed.
+- The default location of ``nimcache`` for the native code targets was
+  changed. Read [the compiler user guide](https://nim-lang.org/docs/nimc.html#generated-c-code-directory)
+  for more information.
 
 ### Library additions
 
@@ -91,7 +94,7 @@
 - ``parseOct`` and ``parseBin`` in parseutils now also support the ``maxLen`` argument similar to ``parseHexInt``
 - Added the proc ``flush`` for memory mapped files.
 - Added the ``MemMapFileStream``.
-- Added ``macros.copyLineInfo`` to copy lineInfo from other node
+- Added ``macros.copyLineInfo`` to copy lineInfo from other node.
 
 ### Library changes
 
@@ -161,11 +164,11 @@
 - The command syntax now supports keyword arguments after the first comma.
 
 - Thread-local variables can now be declared inside procs. This implies all
-  the effects of the `global` pragma.
+  the effects of the ``global`` pragma.
 
-- Nim now supports `except` clause in the export statement.
+- Nim now supports ``except`` clause in the export statement.
 
-- Range float types, example `range[0.0 .. Inf]`. More details in language manual.
+- Range float types, example ``range[0.0 .. Inf]``. More details in language manual.
 
 ### Tool changes
 

compiler/options.nim

@@ -480,9 +480,19 @@ proc disableNimblePath*(conf: ConfigRef) =
 
 include packagehandling
 
+proc getOsCacheDir(): string =
+  when defined(posix):
+    result = getHomeDir() / ".cache"
+  else:
+    result = getHomeDir() / genSubDir
+
 proc getNimcacheDir*(conf: ConfigRef): string =
-  result = if conf.nimcacheDir.len > 0: conf.nimcacheDir
+  result = if conf.nimcacheDir.len > 0:
-           else: shortenDir(conf, conf.projectPath) / genSubDir
+             conf.nimcacheDir
+           elif conf.cmd == cmdCompileToJS:
+             shortenDir(conf, conf.projectPath) / genSubDir
+           else: getOsCacheDir() / conf.projectName &
+             (if isDefined(conf, "release"): "_r" else: "_d")
 
 proc pathSubs*(conf: ConfigRef; p, config: string): string =
   let home = removeTrailingDirSep(os.getHomeDir())

doc/backends.txt

@@ -65,7 +65,6 @@ The JavaScript target
 ---------------------
 
 Nim can also generate `JavaScript`:idx: code through the ``js`` command.
-However, the JavaScript code generator is experimental!
 
 Nim targets JavaScript 1.5 which is supported by any widely used browser.
 Since JavaScript does not have a portable means to include another module,
@@ -77,7 +76,7 @@ available. This includes:
 * manual memory management (``alloc``, etc.)
 * casting and other unsafe operations (``cast`` operator, ``zeroMem``, etc.)
 * file management
-* most modules of the Standard library
+* most modules of the standard library
 * proper 64 bit integer arithmetic
 * unsigned integer arithmetic
 
@@ -87,9 +86,8 @@ However, the modules `strutils <strutils.html>`_, `math <math.html>`_, and
 
 To compile a Nim module into a ``.js`` file use the ``js`` command; the
 default is a ``.js`` file that is supposed to be referenced in an ``.html``
-file. However, you can also run the code with `nodejs`:idx:, a `software
+file. However, you can also run the code with `nodejs`:idx:
-platform for easily building fast, scalable network applications
+(`<http://nodejs.org>`_)::
-<http://nodejs.org>`_::
 
   nim js -d:nodejs -r examples/hallo.nim
 
@@ -330,8 +328,9 @@ Nimcache naming logic
 
 The `nimcache`:idx: directory is generated during compilation and will hold
 either temporary or final files depending on your backend target. The default
-name for the directory is ``nimcache`` but you can use the ``--nimcache``
+name for the directory depends on the used backend and on your OS but you can
-`compiler switch <nimc.html#command-line-switches>`_ to change it.
+use the ``--nimcache`` `compiler switch <nimc.html#command-line-switches>`_ to
+change it.
 
 Nimcache and C like targets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/nimc.rst

@@ -157,38 +157,27 @@ the first matching file is used.
 Generated C code directory
 --------------------------
 The generated files that Nim produces all go into a subdirectory called
-``nimcache`` in your project directory. This makes it easy to delete all
+``nimcache``. Its full path is
+
+- ``~/.cache/$projectname(_r|_d)`` on Posix
+- ``$HOME/nimcache/$projectname(_r|_d)`` on Windows.
+
+The ``_r`` suffix is used for release builds, ``_d`` is for debug builds.
+
+This makes it easy to delete all
 generated files. Files generated in this directory follow a naming logic which
 you can read about in the `Nim Backend Integration document
 <backends.html#nimcache-naming-logic>`_.
 
+The ``--nimcache``
+`compiler switch <nimc.html#command-line-switches>`_ can be used to
+to change the ``nimcache`` directory.
+
 However, the generated C code is not platform independent. C code generated for
 Linux does not compile on Windows, for instance. The comment on top of the
 C file lists the OS, CPU and CC the file has been compiled for.
 
 
-Compilation cache
-=================
-
-**Warning**: The compilation cache is still highly experimental!
-
-The ``nimcache`` directory may also contain so called `rod`:idx:
-or `symbol files`:idx:. These files are pre-compiled modules that are used by
-the compiler to perform `incremental compilation`:idx:. This means that only
-modules that have changed since the last compilation (or the modules depending
-on them etc.) are re-compiled. However, per default no symbol files are
-generated; use the ``--symbolFiles:on`` command line switch to activate them.
-
-Unfortunately due to technical reasons the ``--symbolFiles:on`` needs
-to *aggregate* some generated C code. This means that the resulting executable
-might contain some cruft even with dead code elimination. So
-the final release build should be done with ``--symbolFiles:off``.
-
-Due to the aggregation of C code it is also recommended that each project
-resides in its own directory so that the generated ``nimcache`` directory
-is not shared between different projects.
-
-
 Compiler Selection
 ==================