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.

examples/cross_calculator/ios/cross-calculator.xcodeproj/project.pbxproj

@@ -13,7 +13,7 @@
 		D531424D15BC87B6005EFF20 /* AppDelegate.m in Sources */ = {isa = PBXBuildFile; fileRef = D531424A15BC87B6005EFF20 /* AppDelegate.m */; };
 		D531424E15BC87B6005EFF20 /* main.m in Sources */ = {isa = PBXBuildFile; fileRef = D531424B15BC87B6005EFF20 /* main.m */; };
 		D531427215BC94B1005EFF20 /* backend.m in Sources */ = {isa = PBXBuildFile; fileRef = D531426F15BC94B1005EFF20 /* backend.m */; };
-		D531427415BC94B1005EFF20 /* system.m in Sources */ = {isa = PBXBuildFile; fileRef = D531427115BC94B1005EFF20 /* system.m */; };
+		D531427415BC94B1005EFF20 /* stdlib_system.m in Sources */ = {isa = PBXBuildFile; fileRef = D531427115BC94B1005EFF20 /* stdlib_system.m */; };
 		D5B6F94815FA8D4C0084A85B /* NRViewController.m in Sources */ = {isa = PBXBuildFile; fileRef = D5B6F94615FA8D4C0084A85B /* NRViewController.m */; };
 /* End PBXBuildFile section */
 
@@ -30,7 +30,7 @@
 		D531426715BC91EF005EFF20 /* tags.sh */ = {isa = PBXFileReference; lastKnownFileType = text.script.sh; name = tags.sh; path = scripts/tags.sh; sourceTree = "<group>"; };
 		D531426815BC91EF005EFF20 /* xcode_prebuild.sh */ = {isa = PBXFileReference; lastKnownFileType = text.script.sh; name = xcode_prebuild.sh; path = scripts/xcode_prebuild.sh; sourceTree = "<group>"; };
 		D531426F15BC94B1005EFF20 /* backend.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = backend.m; path = build/nimcache/backend.m; sourceTree = "<group>"; };
-		D531427115BC94B1005EFF20 /* system.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = system.m; path = build/nimcache/system.m; sourceTree = "<group>"; };
+		D531427115BC94B1005EFF20 /* stdlib_system.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = stdlib_system.m; path = build/nimcache/stdlib_system.m; sourceTree = "<group>"; };
 		D592E19015C7120F005258EA /* backend.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = backend.h; path = build/nimcache/backend.h; sourceTree = "<group>"; };
 		D592E19115C71415005258EA /* nimbase.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = nimbase.h; path = build/nimcache/nimbase.h; sourceTree = "<group>"; };
 		D5B6F94515FA8D4C0084A85B /* NRViewController.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = NRViewController.h; path = src/NRViewController.h; sourceTree = "<group>"; };
@@ -135,7 +135,7 @@
 				D592E19015C7120F005258EA /* backend.h */,
 				D531426F15BC94B1005EFF20 /* backend.m */,
 				D592E19115C71415005258EA /* nimbase.h */,
-				D531427115BC94B1005EFF20 /* system.m */,
+				D531427115BC94B1005EFF20 /* stdlib_system.m */,
 			);
 			name = nimrod;
 			sourceTree = "<group>";
@@ -229,7 +229,7 @@
 				D531424D15BC87B6005EFF20 /* AppDelegate.m in Sources */,
 				D531424E15BC87B6005EFF20 /* main.m in Sources */,
 				D531427215BC94B1005EFF20 /* backend.m in Sources */,
-				D531427415BC94B1005EFF20 /* system.m in Sources */,
+				D531427415BC94B1005EFF20 /* stdlib_system.m in Sources */,
 				D5B6F94815FA8D4C0084A85B /* NRViewController.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -259,11 +259,7 @@
 				GCC_WARN_ABOUT_MISSING_PROTOTYPES = YES;
 				GCC_WARN_ABOUT_RETURN_TYPE = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 3.0;
-				OTHER_LDFLAGS = (
-					"-weak_library",
-					/usr/lib/libSystem.B.dylib,
-				);
+				IPHONEOS_DEPLOYMENT_TARGET = 4.3;
 				SDKROOT = iphoneos;
 				TARGETED_DEVICE_FAMILY = "1,2";
 			};
@@ -284,12 +280,8 @@
 				GCC_WARN_ABOUT_MISSING_PROTOTYPES = YES;
 				GCC_WARN_ABOUT_RETURN_TYPE = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 3.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 4.3;
 				OTHER_CFLAGS = "-DNS_BLOCK_ASSERTIONS=1";
-				OTHER_LDFLAGS = (
-					"-weak_library",
-					/usr/lib/libSystem.B.dylib,
-				);
 				SDKROOT = iphoneos;
 				TARGETED_DEVICE_FAMILY = "1,2";
 				VALIDATE_PRODUCT = YES;

examples/cross_calculator/ios/scripts/xcode_prebuild.sh

@@ -22,7 +22,7 @@ DEST_NIMBASE=build/nimcache/nimbase.h
 if [ -d src ]
 then
 	$PATH_TO_NIMROD objc --noMain  --app:lib \
-		--nimcache:build/nimcache --compileOnly \
+		--nimcache:./build/nimcache --compileOnly \
 		--header --cpu:i386 ../nimrod_backend/backend.nim
 	if [ "${PATH_TO_NIMBASE}" -nt "${DEST_NIMBASE}" ]
 	then