From d47971b9caa928b954203633fad2ef31628bf35f Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Thu, 31 Jul 2014 14:38:35 +0200 Subject: [PATCH] Corrects description of nimcache file naming. Refs #852. --- doc/backends.txt | 54 +++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/doc/backends.txt b/doc/backends.txt index adcd741490..c2dbb0af66 100644 --- a/doc/backends.txt +++ b/doc/backends.txt @@ -334,42 +334,40 @@ Nimcache and C like targets ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The C like backends will place their temporary ``.c``, ``.cpp`` or ``.m`` files -in the ``nimcache`` directory. The name of this files follows this logic: +in the ``nimcache`` directory. The naming of these files follows the pattern +``babelPackageName_`` + ``nimrodSource``: -* Filenames for 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 imported from `Babel packages + `_ 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 `_ is always imported automatically. Same for the `hashes module `_ which will be named - ``stdlib_hashes.c`` + ``stdlib_hashes.c``. The ``stdlib_`` prefix comes from the *fake* + ``lib/stdlib.babel`` file. -* Filenames for modules not part of the standard library and found - through additional paths specified with the ``--path`` compiler - switch will use as prefix their parent directory. For example, - the `rstgen module `_ will generate ``docutils_rstgen.c`` - because the `lib/packages/docutils directory - `_ is - not included in the standard library and you need to either write - ``import packages/docutils/rstgen`` or add - ``--path:"$lib/pkages/docutils`` to the compiler switches to be - able to use it. - -* Filenames for modules imported from `babel packages - `_ 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``. - -To find out about what paths are part of the default standard library, create a -dummy ``hello.nim`` file and run ``nimrod dump hello.nim``. This will display -the defined simbols and the list of paths for the standard library. +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