Merge pull request #1417 from gradha/pr_852_nimcache_naming

Documents nimcache naming and fixes ios example

doc/backends.txt

@@ -322,6 +322,64 @@ earlier, JavaScript doesn't require an initialisation call to ``NimMain`` or
 similar function and you can call the exported Nimrod proc directly.
 
 
+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``
+`compiler switch <nimrodc.html#command-line-switches>`_ to change it.
+
+Nimcache and C like targets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The C like backends will place their temporary ``.c``, ``.cpp`` or ``.m`` files
+in the ``nimcache`` directory. The naming of these files follows the pattern
+``babelPackageName_`` + ``nimrodSource``:
+
+* Filenames for modules imported from `Babel packages
+  <https://github.com/nimrod-code/babel>`_ will end up with
+  ``babelPackageName_module.c``. For example, if you import the
+  ``argument_parser`` module from the same name Babel package you
+  will end up with a ``argument_parser_argument_parser.c`` file
+  under ``nimcache``.  The name of the Babel package comes from the
+  ``proj.babel`` file, the actual contents are not read by the
+  compiler.
+
+* Filenames for non babel packages (like your project) will be
+  renamed from ``.nim`` to have the extension of your target backend
+  (from now on ``.c`` for these examples), but otherwise nothing
+  else will change. This will quickly break if your project consists
+  of a main ``proj.nim`` file which includes a ``utils/proj.nim``
+  file: both ``proj.nim`` files will generate the same name ``proj.c``
+  output in the ``nimcache`` directory overwriting themselves!
+
+* Filenames for modules found in the standard library will be named
+  ``stdlib_module.c``. Unless you are doing something special, you
+  will end up with at least ``stdlib_system.c``, since the `system
+  module <system.html>`_ is always imported automatically. Same for
+  the `hashes module <hashes.html>`_ which will be named
+  ``stdlib_hashes.c``. The ``stdlib_`` prefix comes from the *fake*
+  ``lib/stdlib.babel`` file.
+
+To find the name of a Babel package the compiler searches for a ``*.babel``
+file in the parent directory hierarchy of whatever module you are compiling.
+Even if you are in a subdirectory of your project, a parent ``*.babel`` file
+will influence the naming of the nimcache name. This means that on Unix systems
+creating the file ``~/foo.babel`` will automatically prefix all nimcache files
+not part of another package with the string ``foo_``.
+
+
+Nimcache and the Javascript target
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Unless you explicitly use the ``-o:filename.js`` switch as mentioned in the
+previous examples, the compiler will create a ``filename.js`` file in the
+``nimcache`` directory using the name of your input nimrod file. There are no
+other temporary files generated, the output is always a single self contained
+``.js`` file.
+
+
 Memory management
 =================
 

doc/nimrodc.txt

@@ -152,10 +152,12 @@ the first matching file is used.
 
 Generated C code directory
 --------------------------
-The generated files that Nimrod produces all go into a subdirectory called
-``nimcache`` in your project directory. This makes it easy to delete all
-generated files.
-
+The generated files that Nimrod produces all go into a subdirectory called
+``nimcache`` in your project directory. 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 `Nimrod Backend Integration document
+<backends.html#nimcache-naming-logic>`_.
+
 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.