From 2482eeeed48f23c39be162c9d3cea635253bc3ca Mon Sep 17 00:00:00 2001
From: Joey Yakimowich-Payne <jyapayne@gmail.com>
Date: Mon, 2 Jul 2018 11:33:08 +0900
Subject: [PATCH] Add docs for compiler switch

---
 changelog.md   |  3 +++
 doc/advopt.txt |  2 ++
 doc/nimc.rst   | 31 +++++++++++++++++++++++++++++++
 3 files changed, 36 insertions(+)

diff --git a/changelog.md b/changelog.md
index bbe526124..7c5c70ecf 100644
--- a/changelog.md
+++ b/changelog.md
@@ -185,4 +185,7 @@
 - Nintendo Switch was added as a new platform target. See [the compiler user guide](https://nim-lang.org/docs/nimc.html)
   for more info.
 
+- Compiler switch ``--uniqueMain`` was added. See [the compiler user guide](https://nim-lang.org/docs/nimc.html#linking-a-nim-generated-static-library-in-nim) for more info.
+
+
 ### Bugfixes
diff --git a/doc/advopt.txt b/doc/advopt.txt
index 685c8127d..c2d894976 100644
--- a/doc/advopt.txt
+++ b/doc/advopt.txt
@@ -34,6 +34,8 @@ Advanced options:
   -c, --compileOnly         compile Nim files only; do not assemble or link
   --noLinking               compile Nim and generated files but do not link
   --noMain                  do not generate a main procedure
+  --uniqueMain              generate a unique main function call which is usefull
+                            for linking to static libaries written in Nim
   --genScript               generate a compile script (in the 'nimcache'
                             subdirectory named 'compile_$$project$$scriptext'),
                             implies --compileOnly
diff --git a/doc/nimc.rst b/doc/nimc.rst
index a3adcc143..a03687684 100644
--- a/doc/nimc.rst
+++ b/doc/nimc.rst
@@ -430,6 +430,37 @@ on Linux::
 
   nim c --dynlibOverride:lua --passL:liblua.lib program.nim
 
+Linking a Nim generated static library in Nim
+=============================================
+
+By default, Nim generates a publicly visible main function in C that is always
+named the same thing (NimMain) in order to make it easy for clients written in
+other languages to link to Nim generated code. However, this causes issues
+when Nim clients want to link to Nim static libraries because of multiple
+definitions of the same function, which C doesn't allow.
+
+In order to work around this issue, a compiler flag exists that generates a
+unique name for ``NimMain`` by hashing the name of the module it's in and
+appending it to the end of the ``NimMain``, separated by an underscore.
+
+An example to compile a static library on Linux and then link it is as follows::
+
+  nim --noMain --uniqueMain --app:staticLib c static.nim
+  nim --passL:libstatic.a c main.nim
+
+Where an example of ``static.nim`` could be:
+
+.. code-block:: Nim
+  proc testing*(testInt: int): int {.cdecl, exportc.} =
+    return testInt + 100
+
+and an example of ``main.nim`` could be:
+
+.. code-block:: Nim
+  proc testing*(testInt: int): int {.importc, cdecl.}
+
+  echo testing(50) # Should output "150"
+
 
 Backend language options
 ========================