diff options
Diffstat (limited to 'doc/backends.txt')
| -rw-r--r-- | doc/backends.txt | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/doc/backends.txt b/doc/backends.txt index 26576e733..c2dbb0af6 100644 --- a/doc/backends.txt +++ b/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 ================= |