홈 탐색 도움말
로그인
levovix
/
Nim
의 미러 https://github.com/nim-lang/Nim
Watch 1
Star 0
포크 1
파일 이슈 0 위키
브렌치: gh-pages
브랜치 태그
Nim
/
nimc.html

nimc.html 109 KB
고유링크 히스토리 Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574 
  1. <?xml version="1.0" encoding="utf-8" ?>
    2. 

  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    3. 

  3. <!--  This file is generated by Nim. -->
    4. 

  4. <html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
    5. 

  5. <head>
    6. 

  6. <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    7. 

  7. <meta name="viewport" content="width=device-width, initial-scale=1.0">
    8. 

  8. <title>Nim Compiler User Guide</title>
    9. 

  9. 

  10. <!-- Google fonts -->
    11. 

  11. <link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
    12. 

  12. <link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
    13. 

  13. 

  14. <!-- Favicon -->
    15. 

  15. <link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
    16. 

  16. <link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">
    17. 

  17. 

  18. <!-- CSS -->
    19. 

  19. <link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">
    20. 

  20. 

  21. <!-- JS -->
    22. 

  22. <script type="text/javascript" src="dochack.js?v=2.3.1"></script>
    23. 

  23. </head>
    24. 

  24. <body>
    25. 

  25.   <div class="document" id="documentId">
    26. 

  26.     <div class="container">
    27. 

  27.       <h1 class="title">Nim Compiler User Guide</h1>
    28. 

  28.       <div class="row">
    29. 

  29.   <div class="three columns">
    30. 

  30.     <div class="theme-select-wrapper">
    31. 

  31.       <label for="theme-select">Theme:&nbsp;</label>
    32. 

  32.       <select id="theme-select" onchange="setTheme(this.value)">
    33. 

  33.         <option value="auto">🌗 Match OS</option>
    34. 

  34.         <option value="dark">🌑 Dark</option>
    35. 

  35.         <option value="light">🌕 Light</option>
    36. 

  36.       </select>
    37. 

  37.     </div>
    38. 

  38.     <div id="global-links">
    39. 

  39.       <ul class="simple-boot">
    40. 

  40.         <li><a href="manual.html">Manual</a></li>
    41. 

  41.         <li><a href="lib.html">Standard library</a></li>
    42. 

  42.         <li> <a id="indexLink" href="theindex.html">Index</a></li>
    43. 

  43.         <li><a href="compiler/theindex.html">Compiler docs</a></li>
    44. 

  44.         <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
    45. 

  45.         <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
    46. 

  46.       </ul>
    47. 

  47.     </div>
    48. 

  48.     <div id="searchInputDiv">
    49. 

  49.       Search: <input type="search" id="searchInput"
    50. 

  50.         oninput="search()" />
    51. 

  51.     </div>
    52. 

  52.     <div class="search-groupby">
    53. 

  53.   Group by:
    54. 

  54.   <select onchange="groupBy(this.value)">
    55. 

  55.     <option value="section">Section</option>
    56. 

  56.     <option value="type">Type</option>
    57. 

  57.   </select>
    58. 

  58. </div>
    59. 

  59. 

  60.     <ul class="simple simple-toc" id="toc-list">
    61. 

  61.   <li><a class="reference" id="introduction_toc" href="#introduction">Introduction</a></li>
    62. 

  62. <li><a class="reference" id="compiler-usage_toc" href="#compiler-usage">Compiler Usage</a></li>
    63. 

  63. <ul class="simple"><li><a class="reference" id="compiler-usage-commandminusline-switches_toc" href="#compiler-usage-commandminusline-switches">Command-line switches</a></li>
    64. 

  64. <li><a class="reference" id="compiler-usage-list-of-warnings_toc" href="#compiler-usage-list-of-warnings">List of warnings</a></li>
    65. 

  65. <li><a class="reference" id="compiler-usage-list-of-hints_toc" href="#compiler-usage-list-of-hints">List of hints</a></li>
    66. 

  66. <li><a class="reference" id="compiler-usage-verbosity-levels_toc" href="#compiler-usage-verbosity-levels">Verbosity levels</a></li>
    67. 

  67. <li><a class="reference" id="compiler-usage-compileminustime-symbols_toc" href="#compiler-usage-compileminustime-symbols">Compile-time symbols</a></li>
    68. 

  68. <li><a class="reference" id="compiler-usage-configuration-files_toc" href="#compiler-usage-configuration-files">Configuration files</a></li>
    69. 

  69. <li><a class="reference" id="compiler-usage-search-path-handling_toc" href="#compiler-usage-search-path-handling">Search path handling</a></li>
    70. 

  70. <li><a class="reference" id="compiler-usage-generated-c-code-directory_toc" href="#compiler-usage-generated-c-code-directory">Generated C code directory</a></li>
    71. 

  71. </ul><li><a class="reference" id="compiler-selection_toc" href="#compiler-selection">Compiler Selection</a></li>
    72. 

  72. <li><a class="reference" id="crossminuscompilation_toc" href="#crossminuscompilation">Cross-compilation</a></li>
    73. 

  73. <li><a class="reference" id="crossminuscompilation-for-windows_toc" href="#crossminuscompilation-for-windows">Cross-compilation for Windows</a></li>
    74. 

  74. <li><a class="reference" id="crossminuscompilation-for-android_toc" href="#crossminuscompilation-for-android">Cross-compilation for Android</a></li>
    75. 

  75. <li><a class="reference" id="crossminuscompilation-for-ios_toc" href="#crossminuscompilation-for-ios">Cross-compilation for iOS</a></li>
    76. 

  76. <li><a class="reference" id="crossminuscompilation-for-nintendo-switch_toc" href="#crossminuscompilation-for-nintendo-switch">Cross-compilation for Nintendo Switch</a></li>
    77. 

  77. <li><a class="reference" id="gpu-compilation_toc" href="#gpu-compilation">GPU Compilation</a></li>
    78. 

  78. <li><a class="reference" id="dll-generation_toc" href="#dll-generation">DLL generation</a></li>
    79. 

  79. <li><a class="reference" id="additional-compilation-switches_toc" href="#additional-compilation-switches">Additional compilation switches</a></li>
    80. 

  80. <li><a class="reference" id="additional-features_toc" href="#additional-features">Additional Features</a></li>
    81. 

  81. <ul class="simple"><li><a class="reference" id="additional-features-linedir-option_toc" href="#additional-features-linedir-option">LineDir option</a></li>
    82. 

  82. <li><a class="reference" id="additional-features-stacktrace-option_toc" href="#additional-features-stacktrace-option">StackTrace option</a></li>
    83. 

  83. <li><a class="reference" id="additional-features-linetrace-option_toc" href="#additional-features-linetrace-option">LineTrace option</a></li>
    84. 

  84. </ul><li><a class="reference" id="dynliboverride_toc" href="#dynliboverride">DynlibOverride</a></li>
    85. 

  85. <li><a class="reference" id="backend-language-options_toc" href="#backend-language-options">Backend language options</a></li>
    86. 

  86. <li><a class="reference" id="nim-documentation-tools_toc" href="#nim-documentation-tools">Nim documentation tools</a></li>
    87. 

  87. <li><a class="reference" id="nim-idetools-integration_toc" href="#nim-idetools-integration">Nim idetools integration</a></li>
    88. 

  88. <li><a class="reference" id="nim-for-embedded-systems_toc" href="#nim-for-embedded-systems">Nim for embedded systems</a></li>
    89. 

  89. <ul class="simple"><li><a class="reference" id="nim-for-embedded-systems-nimallocpagesviamalloc_toc" href="#nim-for-embedded-systems-nimallocpagesviamalloc">nimAllocPagesViaMalloc</a></li>
    90. 

  90. </ul><li><a class="reference" id="nimpage256-slash-nimpage512-slash-nimpage1k_toc" href="#nimpage256-slash-nimpage512-slash-nimpage1k">nimPage256 / nimPage512 / nimPage1k</a></li>
    91. 

  91. <li><a class="reference" id="nimmemaligntiny_toc" href="#nimmemaligntiny">nimMemAlignTiny</a></li>
    92. 

  92. <li><a class="reference" id="thread-stack-size_toc" href="#thread-stack-size">Thread stack size</a></li>
    93. 

  93. <li><a class="reference" id="nim-for-realtime-systems_toc" href="#nim-for-realtime-systems">Nim for realtime systems</a></li>
    94. 

  94. <li><a class="reference" id="signal-handling-in-nim_toc" href="#signal-handling-in-nim">Signal handling in Nim</a></li>
    95. 

  95. <li><a class="reference" id="optimizing-for-nim_toc" href="#optimizing-for-nim">Optimizing for Nim</a></li>
    96. 

  96. <ul class="simple"><li><a class="reference" id="optimizing-for-nim-optimizing-string-handling_toc" href="#optimizing-for-nim-optimizing-string-handling">Optimizing string handling</a></li>
    97. 

  97. </ul>
    98. 

  98. </ul>
    99. 

  99. 

  100.   </div>
    101. 

  101.   <div class="nine columns" id="content">
    102. 

  102.     <a href="https://github.com/nim-lang/Nim/tree/devel/doc/nimc.md#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
    103. 

  103. <a href="https://github.com/nim-lang/Nim/edit/devel/doc/nimc.md#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
    104. 

  104. 

  105.     <div id="tocRoot"></div>
    106. 

  106.     
    107. 

  107.     <p class="module-desc"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Author:</th><td>Andreas Rumpf</td></tr>
    108. 

  108. <tr><th class="docinfo-name">Version:</th><td>2.3.1</td></tr>
    109. 

  109. </tbody></table><blockquote class="markdown-quote"><p>&quot;Look at you, hacker. A pathetic creature of meat and bone, panting and sweating as you run through my corridors. How can you challenge a perfect, immortal machine?&quot;</p></blockquote>
    110. 

  110. 

  111. <h1><a class="toc-backref" id="introduction" href="#introduction">Introduction</a></h1><p>This document describes the usage of the <em>Nim compiler</em> on the different supported platforms. It is not a definition of the Nim programming language (which is covered in the <a class="reference external" href="manual.html">manual</a>).</p>
    112. 

  112. <p>Nim is free software; it is licensed under the <a class="reference external" href="https://www.opensource.org/licenses/mit-license.php">MIT License</a>.</p>
    113. 

  113. 

  114. <h1><a class="toc-backref" id="compiler-usage" href="#compiler-usage">Compiler Usage</a></h1>
    115. 

  115. <h2><a class="toc-backref" id="compiler-usage-commandminusline-switches" href="#compiler-usage-commandminusline-switches">Command-line switches</a></h2><p>All options that take a <tt class="docutils literal"><span class="pre"><span class="Identifier">PATH</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">DIR</span></span></tt> argument are subject to path substitution:</p>
    116. 

  116. <ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">nim</span></span></tt>: The global nim prefix path</li>
    117. 

  117. <li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">lib</span></span></tt>: The stdlib path</li>
    118. 

  118. <li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">home</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Operator">~</span></span></tt>: The user's home path</li>
    119. 

  119. <li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">config</span></span></tt>: The directory of the module currently being compiled</li>
    120. 

  120. <li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">projectname</span></span></tt>: The project file's name without file extension</li>
    121. 

  121. <li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">projectpath</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">projectdir</span></span></tt>: The project file's path</li>
    122. 

  122. <li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">nimcache</span></span></tt>: The nimcache path</li>
    123. 

  123. </ul>
    124. 

  124. <p>Basic command-line switches are:</p>
    125. 

  125. <p>Usage:</p>
    126. 

  126. <pre>nim command [options] [projectfile] [arguments]</pre>
    127. 

  127. <p>Command:</p>
    128. 

  128. <div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">compile, c</span></tt></div><div class="option-list-description">compile project with default code generator (C)</div></div>
    129. 

  129. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">r</span></tt></div><div class="option-list-description">compile to $nimcache/projname, run with <tt class="docutils literal"><span class="pre">arguments</span></tt> using backend specified by <tt class="docutils literal"><span class="pre">--backend</span></tt> (default: c)</div></div>
    130. 

  130. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">doc</span></tt></div><div class="option-list-description">generate the documentation for inputfile for backend specified by <tt class="docutils literal"><span class="pre">--backend</span></tt> (default: c)</div></div>
    131. 

  131. </div><p>Arguments: arguments are passed to the program being run (if --run option is selected)</p>
    132. 

  132. <p>Options:</p>
    133. 

  133. <div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">-p, --path:PATH</span></tt></div><div class="option-list-description">add path to search paths</div></div>
    134. 

  134. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">-d, --define:SYMBOL(:VAL)</span></tt></div><div class="option-list-description">define a conditional symbol (Optionally: Define the value for that symbol, see: &quot;compile time define pragmas&quot;)</div></div>
    135. 

  135. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">-u, --undef:SYMBOL</span></tt></div><div class="option-list-description">undefine a conditional symbol</div></div>
    136. 

  136. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">-f, --forceBuild:on|off</span></tt></div><div class="option-list-description">force rebuilding of all modules</div></div>
    137. 

  137. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--stackTrace:on|off</span></tt></div><div class="option-list-description">turn stack tracing on|off</div></div>
    138. 

  138. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--lineTrace:on|off</span></tt></div><div class="option-list-description">turn line tracing on|off</div></div>
    139. 

  139. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--threads:on|off</span></tt></div><div class="option-list-description">turn support for multi-threading on|off</div></div>
    140. 

  140. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">-x, --checks:on|off</span></tt></div><div class="option-list-description">turn all runtime checks on|off</div></div>
    141. 

  141. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">-a, --assertions:on|off</span></tt></div><div class="option-list-description">turn assertions on|off</div></div>
    142. 

  142. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--opt:none|speed|size</span></tt></div><div class="option-list-description">optimize not at all or for speed|size Note: use -d:release for a release build!</div></div>
    143. 

  143. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--debugger:native</span></tt></div><div class="option-list-description">use native debugger (gdb)</div></div>
    144. 

  144. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--app:console|gui|lib|staticlib</span></tt></div><div class="option-list-description">generate a console app|GUI app|DLL|static library</div></div>
    145. 

  145. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">-r, --run</span></tt></div><div class="option-list-description">run the compiled program with given arguments</div></div>
    146. 

  146. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--eval:cmd</span></tt></div><div class="option-list-description">evaluate nim code directly; e.g.: <tt class="docutils literal"><span class="pre">nim --eval:&quot;echo 1&quot;</span></tt> defaults to <tt class="docutils literal"><span class="pre">e</span></tt> (nimscript) but customizable: <tt class="docutils literal"><span class="pre">nim r --eval:'for a in stdin.lines: echo a'</span></tt></div></div>
    147. 

  147. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--fullhelp</span></tt></div><div class="option-list-description">show all command line switches</div></div>
    148. 

  148. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">-h, --help</span></tt></div><div class="option-list-description">show this help</div></div>
    149. 

  149. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">-v, --version</span></tt></div><div class="option-list-description">show detailed version information</div></div>
    150. 

  150. </div><p>Note, single letter options that take an argument require a colon. E.g. -p:PATH. </p>
    151. 

  151. <hr />
    152. 

  152. <p>Advanced command-line switches are:</p>
    153. 

  153. Advanced commands:<div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">compileToC, cc</span></tt></div><div class="option-list-description">compile project with C code generator</div></div>
    154. 

  154. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">compileToCpp, cpp</span></tt></div><div class="option-list-description">compile project to C++ code</div></div>
    155. 

  155. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">compileToOC, objc</span></tt></div><div class="option-list-description">compile project to Objective C code</div></div>
    156. 

  156. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">js</span></tt></div><div class="option-list-description">compile project to Javascript</div></div>
    157. 

  157. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">e</span></tt></div><div class="option-list-description">run a Nimscript file</div></div>
    158. 

  158. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">md2html</span></tt></div><div class="option-list-description">convert a Markdown file to HTML use <tt class="docutils literal"><span class="pre">--docCmd:skip</span></tt> to skip compiling snippets</div></div>
    159. 

  159. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">rst2html</span></tt></div><div class="option-list-description">convert a reStructuredText file to HTML use <tt class="docutils literal"><span class="pre">--docCmd:skip</span></tt> to skip compiling snippets</div></div>
    160. 

  160. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">md2tex</span></tt></div><div class="option-list-description">convert a Markdown file to LaTeX</div></div>
    161. 

  161. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">rst2tex</span></tt></div><div class="option-list-description">convert a reStructuredText file to LaTeX</div></div>
    162. 

  162. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">doc2tex</span></tt></div><div class="option-list-description">extract the documentation to a LaTeX file</div></div>
    163. 

  163. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">jsondoc</span></tt></div><div class="option-list-description">extract the documentation to a json file</div></div>
    164. 

  164. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">ctags</span></tt></div><div class="option-list-description">create a tags file</div></div>
    165. 

  165. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">buildIndex</span></tt></div><div class="option-list-description">build an index for the whole documentation</div></div>
    166. 

  166. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">genDepend</span></tt></div><div class="option-list-description">generate a DOT file containing the module dependency graph</div></div>
    167. 

  167. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">dump</span></tt></div><div class="option-list-description">dump all defined conditionals and search paths see also: --dump.format:json (useful with: <tt class="docutils literal"><span class="pre">| jq</span></tt>)</div></div>
    168. 

  168. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">check</span></tt></div><div class="option-list-description">checks the project for syntax and semantics (can be combined with --defusages)</div></div>
    169. 

  169. </div><p>Runtime checks (see -x):</p>
    170. 

  170. <div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--objChecks:on|off</span></tt></div><div class="option-list-description">turn obj conversion checks on|off</div></div>
    171. 

  171. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--fieldChecks:on|off</span></tt></div><div class="option-list-description">turn case variant field checks on|off</div></div>
    172. 

  172. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--rangeChecks:on|off</span></tt></div><div class="option-list-description">turn range checks on|off</div></div>
    173. 

  173. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--boundChecks:on|off</span></tt></div><div class="option-list-description">turn bound checks on|off</div></div>
    174. 

  174. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--overflowChecks:on|off</span></tt></div><div class="option-list-description">turn int over-/underflow checks on|off</div></div>
    175. 

  175. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--floatChecks:on|off</span></tt></div><div class="option-list-description">turn all floating point (NaN/Inf) checks on|off</div></div>
    176. 

  176. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--nanChecks:on|off</span></tt></div><div class="option-list-description">turn NaN checks on|off</div></div>
    177. 

  177. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--infChecks:on|off</span></tt></div><div class="option-list-description">turn Inf checks on|off</div></div>
    178. 

  178. </div><p>Advanced options:</p>
    179. 

  179. <div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--defusages:FILE,LINE,COL</span></tt></div><div class="option-list-description">find the definition and all usages of a symbol</div></div>
    180. 

  180. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">-o:FILE, --out:FILE</span></tt></div><div class="option-list-description">set the output filename</div></div>
    181. 

  181. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--outdir:DIR</span></tt></div><div class="option-list-description">set the path where the output file will be written</div></div>
    182. 

  182. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--usenimcache</span></tt></div><div class="option-list-description">will use <tt class="docutils literal"><span class="pre">outdir=$$nimcache</span></tt>, whichever it resolves to after all options have been processed</div></div>
    183. 

  183. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--stdout:on|off</span></tt></div><div class="option-list-description">output to stdout</div></div>
    184. 

  184. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--colors:on|off</span></tt></div><div class="option-list-description">turn compiler messages coloring on|off</div></div>
    185. 

  185. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--filenames:abs|canonical|legacyRelProj</span></tt></div><div class="option-list-description">customize how filenames are rendered in compiler messages, defaults to <tt class="docutils literal"><span class="pre">abs</span></tt> (absolute)</div></div>
    186. 

  186. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--processing:dots|filenames|off</span></tt></div><div class="option-list-description">show files as they're being processed by nim compiler</div></div>
    187. 

  187. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--unitsep:on|off</span></tt></div><div class="option-list-description">use the ASCII unit separator (31) between error messages, useful for IDE-like tooling</div></div>
    188. 

  188. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--declaredLocs:on|off</span></tt></div><div class="option-list-description">show declaration locations in messages</div></div>
    189. 

  189. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--spellSuggest:num</span></tt></div><div class="option-list-description">show at most <tt class="docutils literal"><span class="pre">num &gt;= 0</span></tt> spelling suggestions on typos. if <tt class="docutils literal"><span class="pre">num</span></tt> is not specified (or <tt class="docutils literal"><span class="pre">auto</span></tt>), return an implementation defined set of suggestions.</div></div>
    190. 

  190. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--hints:on|off|list</span></tt></div><div class="option-list-description"><tt class="docutils literal"><span class="pre">on|off</span></tt> enables or disables hints. <tt class="docutils literal"><span class="pre">list</span></tt> reports which hints are selected.</div></div>
    191. 

  191. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--hint:X:on|off</span></tt></div><div class="option-list-description">turn specific hint X on|off. <tt class="docutils literal"><span class="pre">hint:X</span></tt> means <tt class="docutils literal"><span class="pre">hint:X:on</span></tt>, as with similar flags. <tt class="docutils literal"><span class="pre">all</span></tt> is the set of all hints (only <tt class="docutils literal"><span class="pre">all:off</span></tt> is supported).</div></div>
    192. 

  192. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--hintAsError:X:on|off</span></tt></div><div class="option-list-description">turn specific hint X into an error on|off</div></div>
    193. 

  193. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">-w:on|off|list, --warnings:on|off|list</span></tt></div><div class="option-list-description"><tt class="docutils literal"><span class="pre">on|off</span></tt> enables or disables warnings. <tt class="docutils literal"><span class="pre">list</span></tt> reports which warnings are selected.</div></div>
    194. 

  194. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--warning:X:on|off</span></tt></div><div class="option-list-description">turn specific warning X on|off. <tt class="docutils literal"><span class="pre">warning:X</span></tt> means <tt class="docutils literal"><span class="pre">warning:X:on</span></tt>, as with similar flags. <tt class="docutils literal"><span class="pre">all</span></tt> is the set of all warning (only <tt class="docutils literal"><span class="pre">all:off</span></tt> is supported).</div></div>
    195. 

  195. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--warningAsError:X:on|off</span></tt></div><div class="option-list-description">turn specific warning X into an error on|off</div></div>
    196. 

  196. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--styleCheck:off|hint|error</span></tt></div><div class="option-list-description">produce hints or errors for Nim identifiers that do not adhere to Nim's official style guide <a class="reference external" href="https://nim-lang.org/docs/nep1.html">https://nim-lang.org/docs/nep1.html</a></div></div>
    197. 

  197. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--styleCheck:usages</span></tt></div><div class="option-list-description">only enforce consistent spellings of identifiers, do not enforce the style on declarations</div></div>
    198. 

  198. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--showAllMismatches:on|off</span></tt></div><div class="option-list-description">show all mismatching candidates in overloading resolution</div></div>
    199. 

  199. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--lib:PATH</span></tt></div><div class="option-list-description">set the system library path</div></div>
    200. 

  200. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--import:PATH</span></tt></div><div class="option-list-description">add an automatically imported module see also <tt class="docutils literal"><span class="pre">patchFile</span></tt> in nimscript which offers more flexibility.</div></div>
    201. 

  201. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--include:PATH</span></tt></div><div class="option-list-description">add an automatically included module</div></div>
    202. 

  202. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--nimcache:PATH</span></tt></div><div class="option-list-description">set the path used for generated files see also <a class="reference external" href="https://nim-lang.org/docs/nimc.html#compiler-usage-generated-c-code-directory">https://nim-lang.org/docs/nimc.html#compiler-usage-generated-c-code-directory</a></div></div>
    203. 

  203. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">-c, --compileOnly:on|off</span></tt></div><div class="option-list-description">compile Nim files only; do not assemble or link</div></div>
    204. 

  204. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--noLinking:on|off</span></tt></div><div class="option-list-description">compile Nim and generated files but do not link</div></div>
    205. 

  205. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--noMain:on|off</span></tt></div><div class="option-list-description">do not generate a main procedure</div></div>
    206. 

  206. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--genScript:on|off</span></tt></div><div class="option-list-description">generate a compile script (in the 'nimcache' subdirectory named 'compile_$$project$$scriptext'), and a '.deps' file containing the dependencies; implies --compileOnly</div></div>
    207. 

  207. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--os:SYMBOL</span></tt></div><div class="option-list-description">set the target operating system (cross-compilation)</div></div>
    208. 

  208. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--cpu:SYMBOL</span></tt></div><div class="option-list-description">set the target processor (cross-compilation)</div></div>
    209. 

  209. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--debuginfo:on|off</span></tt></div><div class="option-list-description">enables debug information</div></div>
    210. 

  210. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">-t, --passC:OPTION</span></tt></div><div class="option-list-description">pass an option to the C compiler</div></div>
    211. 

  211. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">-l, --passL:OPTION</span></tt></div><div class="option-list-description">pass an option to the linker</div></div>
    212. 

  212. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--cc:SYMBOL</span></tt></div><div class="option-list-description">specify the C compiler</div></div>
    213. 

  213. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--cincludes:DIR</span></tt></div><div class="option-list-description">modify the C compiler header search path</div></div>
    214. 

  214. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--clibdir:DIR</span></tt></div><div class="option-list-description">modify the linker library search path</div></div>
    215. 

  215. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--clib:LIBNAME</span></tt></div><div class="option-list-description">link an additional C library (you should omit platform-specific extensions)</div></div>
    216. 

  216. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--project</span></tt></div><div class="option-list-description">document the whole project (doc)</div></div>
    217. 

  217. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--docRoot:path</span></tt></div><div class="option-list-description"><tt class="docutils literal"><span class="pre">nim doc --docRoot:/foo --project --outdir:docs /foo/sub/main.nim</span></tt> generates: docs/sub/main.html if path == @pkg, will use nimble file enclosing dir if path == @path, will use first matching dir in <tt class="docutils literal"><span class="pre">--path</span></tt> if path == @default (the default and most useful), will use best match among @pkg,@path. if these are nonexistent, will use project path</div></div>
    218. 

  218. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">-b, --backend:c|cpp|js|objc</span></tt></div><div class="option-list-description">sets backend to use with commands like <tt class="docutils literal"><span class="pre">nim doc</span></tt> or <tt class="docutils literal"><span class="pre">nim r</span></tt></div></div>
    219. 

  219. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--docCmd:cmd</span></tt></div><div class="option-list-description">if <tt class="docutils literal"><span class="pre">cmd == skip</span></tt>, skips runnableExamples else, runs runnableExamples with given options, e.g.: <tt class="docutils literal"><span class="pre">--docCmd:&quot;-d:foo --threads:on&quot;</span></tt></div></div>
    220. 

  220. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--docSeeSrcUrl:url</span></tt></div><div class="option-list-description">activate 'see source' for doc command (see doc.item.seesrc in config/nimdoc.cfg)</div></div>
    221. 

  221. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--docInternal</span></tt></div><div class="option-list-description">also generate documentation for non-exported symbols</div></div>
    222. 

  222. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--lineDir:on|off</span></tt></div><div class="option-list-description">generation of #line directive on|off</div></div>
    223. 

  223. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--embedsrc:on|off</span></tt></div><div class="option-list-description">embeds the original source code as comments in the generated output</div></div>
    224. 

  224. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--tlsEmulation:on|off</span></tt></div><div class="option-list-description">turn thread local storage emulation on|off</div></div>
    225. 

  225. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--implicitStatic:on|off</span></tt></div><div class="option-list-description">turn implicit compile time evaluation on|off</div></div>
    226. 

  226. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--trmacros:on|off</span></tt></div><div class="option-list-description">turn term rewriting macros on|off</div></div>
    227. 

  227. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--multimethods:on|off</span></tt></div><div class="option-list-description">turn multi-methods on|off</div></div>
    228. 

  228. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--hotCodeReloading:on|off</span></tt></div><div class="option-list-description">turn support for hot code reloading on|off</div></div>
    229. 

  229. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--excessiveStackTrace:on|off</span></tt></div><div class="option-list-description">stack traces use full file paths</div></div>
    230. 

  230. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--stackTraceMsgs:on|off</span></tt></div><div class="option-list-description">enable user defined stack frame msgs via <tt class="docutils literal"><span class="pre">setFrameMsg</span></tt></div></div>
    231. 

  231. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--skipCfg:on|off</span></tt></div><div class="option-list-description">do not read the nim installation's configuration file</div></div>
    232. 

  232. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--skipUserCfg:on|off</span></tt></div><div class="option-list-description">do not read the user's configuration file</div></div>
    233. 

  233. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--skipParentCfg:on|off</span></tt></div><div class="option-list-description">do not read the parent dirs' configuration files</div></div>
    234. 

  234. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--skipProjCfg:on|off</span></tt></div><div class="option-list-description">do not read the project's configuration file</div></div>
    235. 

  235. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--mm:orc|arc|refc|markAndSweep|boehm|go|none|regions</span></tt></div><div class="option-list-description">select which memory management to use; default is 'orc'</div></div>
    236. 

  236. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--exceptions:setjmp|cpp|goto|quirky</span></tt></div><div class="option-list-description">select the exception handling implementation</div></div>
    237. 

  237. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--index:on|off|only</span></tt></div><div class="option-list-description">docgen: turn index file generation on|off (<tt class="docutils literal"><span class="pre">only</span></tt> means not generate output files like HTML)</div></div>
    238. 

  238. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--noImportdoc:on|off</span></tt></div><div class="option-list-description">turn loading documentation <tt class="docutils literal"><span class="pre">.idx</span></tt> files on|off</div></div>
    239. 

  239. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--putenv:key=value</span></tt></div><div class="option-list-description">set an environment variable</div></div>
    240. 

  240. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--NimblePath:PATH</span></tt></div><div class="option-list-description">add a path for Nimble support</div></div>
    241. 

  241. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--noNimblePath</span></tt></div><div class="option-list-description">deactivate the Nimble path</div></div>
    242. 

  242. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--clearNimblePath</span></tt></div><div class="option-list-description">empty the list of Nimble package search paths</div></div>
    243. 

  243. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--cppCompileToNamespace:namespace</span></tt></div><div class="option-list-description">use the provided namespace for the generated C++ code, if no namespace is provided &quot;Nim&quot; will be used</div></div>
    244. 

  244. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--nimMainPrefix:prefix</span></tt></div><div class="option-list-description">use <tt class="docutils literal"><span class="pre">{prefix}NimMain</span></tt> instead of <tt class="docutils literal"><span class="pre">NimMain</span></tt> in the produced C/C++ code</div></div>
    245. 

  245. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--expandMacro:MACRO</span></tt></div><div class="option-list-description">dump every generated AST from MACRO</div></div>
    246. 

  246. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--expandArc:PROCNAME</span></tt></div><div class="option-list-description">show how PROCNAME looks like after diverse optimizations before the final backend phase (mostly ARC/ORC specific)</div></div>
    247. 

  247. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--excludePath:PATH</span></tt></div><div class="option-list-description">exclude a path from the list of search paths</div></div>
    248. 

  248. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--dynlibOverride:SYMBOL</span></tt></div><div class="option-list-description">marks SYMBOL so that dynlib:SYMBOL has no effect and can be statically linked instead; symbol matching is fuzzy so that --dynlibOverride:lua matches dynlib: &quot;liblua.so.3&quot;</div></div>
    249. 

  249. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--dynlibOverrideAll</span></tt></div><div class="option-list-description">disables the effects of the dynlib pragma</div></div>
    250. 

  250. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--listCmd</span></tt></div><div class="option-list-description">list the compilation commands; can be combined with <tt class="docutils literal"><span class="pre">--hint:exec:on</span></tt> and <tt class="docutils literal"><span class="pre">--hint:link:on</span></tt></div></div>
    251. 

  251. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--asm</span></tt></div><div class="option-list-description">produce assembler code</div></div>
    252. 

  252. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--parallelBuild:0|1|...</span></tt></div><div class="option-list-description">perform a parallel build value = number of processors (0 for auto-detect)</div></div>
    253. 

  253. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--incremental:on|off</span></tt></div><div class="option-list-description">only recompile the changed modules (experimental!)</div></div>
    254. 

  254. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--verbosity:0|1|2|3</span></tt></div><div class="option-list-description">set Nim's verbosity level (1 is default)</div></div>
    255. 

  255. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--errorMax:N</span></tt></div><div class="option-list-description">stop compilation after N errors; 0 means unlimited</div></div>
    256. 

  256. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--maxLoopIterationsVM:N</span></tt></div><div class="option-list-description">set max iterations for all VM loops</div></div>
    257. 

  257. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--maxCallDepthVM:N</span></tt></div><div class="option-list-description">set max call depth in the VM</div></div>
    258. 

  258. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--experimental:$1</span></tt></div><div class="option-list-description">enable experimental language feature</div></div>
    259. 

  259. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--legacy:$2</span></tt></div><div class="option-list-description">enable obsolete/legacy language feature</div></div>
    260. 

  260. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--benchmarkVM:on|off</span></tt></div><div class="option-list-description">turn benchmarking of VM code with cpuTime() on|off</div></div>
    261. 

  261. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--profileVM:on|off</span></tt></div><div class="option-list-description">turn compile time VM profiler on|off</div></div>
    262. 

  262. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--panics:on|off</span></tt></div><div class="option-list-description">turn panics into process terminations (default: off)</div></div>
    263. 

  263. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--deepcopy:on|off</span></tt></div><div class="option-list-description">enable 'system.deepCopy' for <tt class="docutils literal"><span class="pre">--mm:arc|orc</span></tt></div></div>
    264. 

  264. <div class="option-list-item"><div class="option-list-label"><tt><span class="option">--jsbigint64:on|off</span></tt></div><div class="option-list-description">toggle the use of BigInt for 64-bit integers for the JavaScript backend (default: on)</div></div>
    265. 

  265. <div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--nimBasePattern:nimbase.h</span></tt></div><div class="option-list-description">allows to specify a custom pattern for <tt class="docutils literal"><span class="pre">nimbase.h</span></tt></div></div>
    266. 

  266. </div>
    267. 

  267. <h2><a class="toc-backref" id="compiler-usage-list-of-warnings" href="#compiler-usage-list-of-warnings">List of warnings</a></h2><p>Each warning can be activated individually with <tt class="docutils literal"><span class="pre option">--warning:NAME:on|off</span></tt> or in a <tt class="docutils literal"><span class="pre"><span class="Identifier">push</span></span></tt> pragma with <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">warning</span><span class="Punctuation">[</span><span class="Identifier">NAME</span><span class="Punctuation">]</span><span class="Punctuation">:</span><span class="Identifier">on</span><span class="Operator">|</span><span class="Identifier">off</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt>.</p>
    268. 

  268. <table border="1" class="docutils"><tr><th>Name</th><th>Description</th></tr>
    269. 

  269. <tr><td>CannotOpenFile</td><td>Some file not essential for the compiler's working could not be opened.</td></tr>
    270. 

  270. <tr><td>OctalEscape</td><td>The code contains an unsupported octal sequence.</td></tr>
    271. 

  271. <tr><td>Deprecated</td><td>The code uses a deprecated symbol.</td></tr>
    272. 

  272. <tr><td>ConfigDeprecated</td><td>The project makes use of a deprecated config file.</td></tr>
    273. 

  273. <tr><td>SmallLshouldNotBeUsed</td><td>The letter 'l' should not be used as an identifier.</td></tr>
    274. 

  274. <tr><td>EachIdentIsTuple</td><td>The code contains a confusing <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> declaration.</td></tr>
    275. 

  275. <tr><td>CStringConv</td><td>Warn about dangerous implicit conversions to <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt>.</td></tr>
    276. 

  276. <tr><td>EnumConv</td><td>Warn about conversions from enum to enum.</td></tr>
    277. 

  277. <tr><td>AnyEnumConv</td><td>Warn about any conversions to an enum type.</td></tr>
    278. 

  278. <tr><td>HoleEnumConv</td><td>Warn about conversion to an enum with holes. These conversions are unsafe.</td></tr>
    279. 

  279. <tr><td>ResultUsed</td><td>Warn about the usage of the built-in <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> variable.</td></tr>
    280. 

  280. <tr><td>User</td><td>Some user-defined warning.</td></tr>
    281. 

  281. </table>
    282. 

  282. <h2><a class="toc-backref" id="compiler-usage-list-of-hints" href="#compiler-usage-list-of-hints">List of hints</a></h2><p>Each hint can be activated individually with <tt class="docutils literal"><span class="pre option">--hint:NAME:on|off</span></tt> or in a <tt class="docutils literal"><span class="pre"><span class="Identifier">push</span></span></tt> pragma with <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">hint</span><span class="Punctuation">[</span><span class="Identifier">NAME</span><span class="Punctuation">]</span><span class="Punctuation">:</span><span class="Identifier">on</span><span class="Operator">|</span><span class="Identifier">off</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt>.</p>
    283. 

  283. <table border="1" class="docutils"><tr><th>Name</th><th>Description</th></tr>
    284. 

  284. <tr><td>CC</td><td>Shows when the C compiler is called.</td></tr>
    285. 

  285. <tr><td>CodeBegin</td><td></td></tr>
    286. 

  286. <tr><td>CodeEnd</td><td></td></tr>
    287. 

  287. <tr><td>CondTrue</td><td></td></tr>
    288. 

  288. <tr><td>Conf</td><td>A config file was loaded.</td></tr>
    289. 

  289. <tr><td>ConvToBaseNotNeeded</td><td></td></tr>
    290. 

  290. <tr><td>ConvFromXtoItselfNotNeeded</td><td></td></tr>
    291. 

  291. <tr><td>Dependency</td><td></td></tr>
    292. 

  292. <tr><td>Exec</td><td>Program is executed.</td></tr>
    293. 

  293. <tr><td>ExprAlwaysX</td><td></td></tr>
    294. 

  294. <tr><td>ExtendedContext</td><td></td></tr>
    295. 

  295. <tr><td>GCStats</td><td>Dumps statistics about the Garbage Collector.</td></tr>
    296. 

  296. <tr><td>GlobalVar</td><td>Shows global variables declarations.</td></tr>
    297. 

  297. <tr><td>Link</td><td>Linking phase.</td></tr>
    298. 

  298. <tr><td>Name</td><td></td></tr>
    299. 

  299. <tr><td>Path</td><td>Search paths modifications.</td></tr>
    300. 

  300. <tr><td>Pattern</td><td></td></tr>
    301. 

  301. <tr><td>Performance</td><td></td></tr>
    302. 

  302. <tr><td>Processing</td><td>Artifact being compiled.</td></tr>
    303. 

  303. <tr><td>QuitCalled</td><td></td></tr>
    304. 

  304. <tr><td>Source</td><td>The source line that triggered a diagnostic message.</td></tr>
    305. 

  305. <tr><td>StackTrace</td><td></td></tr>
    306. 

  306. <tr><td>Success, SuccessX</td><td>Successful compilation of a library or a binary.</td></tr>
    307. 

  307. <tr><td>User</td><td></td></tr>
    308. 

  308. <tr><td>UserRaw</td><td></td></tr>
    309. 

  309. <tr><td>XDeclaredButNotUsed</td><td>Unused symbols in the code.</td></tr>
    310. 

  310. </table>
    311. 

  311. <h2><a class="toc-backref" id="compiler-usage-verbosity-levels" href="#compiler-usage-verbosity-levels">Verbosity levels</a></h2><table border="1" class="docutils"><tr><th>Level</th><th>Description</th></tr>
    312. 

  312. <tr><td>0</td><td>Minimal output level for the compiler.</td></tr>
    313. 

  313. <tr><td>1</td><td>Displays compilation of all the compiled files, including those imported by other modules or through the <a class="reference external" href=" manual.html#implementation-specific-pragmas-compile-pragma">compile pragma</a>. This is the default level.</td></tr>
    314. 

  314. <tr><td>2</td><td>Displays compilation statistics, enumerates the dynamic libraries that will be loaded by the final binary, and dumps to standard output the result of applying <a class="reference external" href=" filters.html">a filter to the source code</a> if any filter was used during compilation.</td></tr>
    315. 

  315. <tr><td>3</td><td>In addition to the previous levels dumps a debug stack trace for compiler developers.</td></tr>
    316. 

  316. </table>
    317. 

  317. <h2><a class="toc-backref" id="compiler-usage-compileminustime-symbols" href="#compiler-usage-compileminustime-symbols">Compile-time symbols</a></h2><p>Through the <tt class="docutils literal"><span class="pre option">-d:x</span></tt> or <tt class="docutils literal"><span class="pre option">--define:x</span></tt> switch you can define compile-time symbols for conditional compilation. The defined switches can be checked in source code with the <a class="reference external" href=" manual.html#statements-and-expressions-when-statement">when statement</a> and <a class="reference external" href="system.html#defined,untyped">defined proc</a>. The typical use of this switch is to enable builds in release mode (<tt class="docutils literal"><span class="pre option">-d:release</span></tt>) where optimizations are enabled for better performance. Another common use is the <tt class="docutils literal"><span class="pre option">-d:ssl</span></tt> switch to activate SSL sockets.</p>
    318. 

  318. <p>Additionally, you may pass a value along with the symbol: <tt class="docutils literal"><span class="pre option">-d:x=y</span></tt> which may be used in conjunction with the <a class="reference external" href="manual.html#implementation-specific-pragmas-compileminustime-define-pragmas">compile-time define pragmas</a> to override symbols during build time.</p>
    319. 

  319. <p>Compile-time symbols are completely <strong>case insensitive</strong> and underscores are ignored too. <tt class="docutils literal"><span class="pre option">--define:FOO</span></tt> and <tt class="docutils literal"><span class="pre option">--define:foo</span></tt> are identical.</p>
    320. 

  320. <p>Compile-time symbols starting with the <tt class="docutils literal"><span class="pre"><span class="Identifier">nim</span></span></tt> prefix are reserved for the implementation and should not be used elsewhere.</p>
    321. 

  321. <table border="1" class="docutils"><tr><th>Name</th><th>Description</th></tr>
    322. 

  322. <tr><td>nimStdSetjmp</td><td>Use the standard <tt class="docutils literal"><span class="pre"><span class="Identifier">setjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">/</span><span class="Identifier">longjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> library functions for setjmp-based exceptions. This is the default on most platforms.</td></tr>
    323. 

  323. <tr><td>nimSigSetjmp</td><td>Use <tt class="docutils literal"><span class="pre"><span class="Identifier">sigsetjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">/</span><span class="Identifier">siglongjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> for setjmp-based exceptions.</td></tr>
    324. 

  324. <tr><td>nimRawSetjmp</td><td>Use <tt class="docutils literal"><span class="pre"><span class="Identifier">_setjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">/</span><span class="Identifier">_longjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> on POSIX and <tt class="docutils literal"><span class="pre"><span class="Identifier">_setjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">/</span><span class="Identifier">longjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> on Windows, for setjmp-based exceptions. It's the default on BSDs and BSD-like platforms, where it's significantly faster than the standard functions.</td></tr>
    325. 

  325. <tr><td>nimBuiltinSetjmp</td><td>Use <tt class="docutils literal"><span class="pre"><span class="Identifier">__builtin_setjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">/</span><span class="Identifier">__builtin_longjmp</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> for setjmp-based exceptions. This will not work if an exception is being thrown and caught inside the same procedure. Useful for benchmarking.</td></tr>
    326. 

  326. </table>
    327. 

  327. <h2><a class="toc-backref" id="compiler-usage-configuration-files" href="#compiler-usage-configuration-files">Configuration files</a></h2><p><strong>Note:</strong> The <em>project file name</em> is the name of the <tt class="docutils literal"><span class="pre">.nim</span></tt> file that is passed as a command-line argument to the compiler.</p>
    328. 

  328. <p>The <tt class="docutils literal"><span class="pre"><span class="program">nim</span></span></tt> executable processes configuration files in the following directories (in this order; later files overwrite previous settings):</p>
    329. 

  329. <ol class="simple"><li><tt class="docutils literal"><span class="pre">$nim/config/nim.cfg</span></tt>, <tt class="docutils literal"><span class="pre">/etc/nim/nim.cfg</span></tt> (UNIX) or <tt class="docutils literal"><span class="pre">&lt;Nim's installation directory&gt;\config\nim.cfg</span></tt> (Windows). This file can be skipped with the <tt class="docutils literal"><span class="pre option">--skipCfg</span></tt> command line option.</li>
    330. 

  330. <li>If environment variable <tt class="docutils literal"><span class="pre"><span class="Identifier">XDG_CONFIG_HOME</span></span></tt> is defined, <tt class="docutils literal"><span class="pre">$XDG_CONFIG_HOME/nim/nim.cfg</span></tt> or <tt class="docutils literal"><span class="pre">~/.config/nim/nim.cfg</span></tt> (POSIX) or <tt class="docutils literal"><span class="pre">%APPDATA%/nim/nim.cfg</span></tt> (Windows). This file can be skipped with the <tt class="docutils literal"><span class="pre option">--skipUserCfg</span></tt> command line option.</li>
    331. 

  331. <li><tt class="docutils literal"><span class="pre">$parentDir/nim.cfg</span></tt> where <tt class="docutils literal"><span class="pre">$parentDir</span></tt> stands for any parent directory of the project file's path. These files can be skipped with the <tt class="docutils literal"><span class="pre option">--skipParentCfg</span></tt> command-line option.</li>
    332. 

  332. <li><tt class="docutils literal"><span class="pre">$projectDir/nim.cfg</span></tt> where <tt class="docutils literal"><span class="pre">$projectDir</span></tt> stands for the project file's path. This file can be skipped with the <tt class="docutils literal"><span class="pre option">--skipProjCfg</span></tt> command-line option.</li>
    333. 

  333. <li>A project can also have a project-specific configuration file named <tt class="docutils literal"><span class="pre">$project.nim.cfg</span></tt> that resides in the same directory as <tt class="docutils literal"><span class="pre">$project.nim</span></tt>. This file can be skipped with the <tt class="docutils literal"><span class="pre option">--skipProjCfg</span></tt> command-line option.</li>
    334. 

  334. </ol>
    335. 

  335. <p>Command-line settings have priority over configuration file settings.</p>
    336. 

  336. <p>The default build of a project is a <span id="debug-build_1">debug build</span>. To compile a <span id="release-build_1">release build</span> define the <tt class="docutils literal"><span class="pre"><span class="Identifier">release</span></span></tt> symbol:</p>
    337. 

  337. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">-d:release</span> <span class="Identifier">myproject.nim</span></pre></p>
    338. 

  338. <p>To compile a <span id="dangerous-release-build_1">dangerous release build</span> define the <tt class="docutils literal"><span class="pre"><span class="Identifier">danger</span></span></tt> symbol:</p>
    339. 

  339. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">-d:danger</span> <span class="Identifier">myproject.nim</span></pre></p>
    340. 

  340. 

  341. <h2><a class="toc-backref" id="compiler-usage-search-path-handling" href="#compiler-usage-search-path-handling">Search path handling</a></h2><p>Nim has the concept of a global search path (PATH) that is queried to determine where to find imported modules or include files. If multiple files are found an ambiguity error is produced.</p>
    342. 

  342. <p><tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">dump</span></span></tt> shows the contents of the PATH.</p>
    343. 

  343. <p>However before the PATH is used the current directory is checked for the file's existence. So if PATH contains <tt class="docutils literal"><span class="pre">$lib</span></tt> and <tt class="docutils literal"><span class="pre">$lib/bar</span></tt> and the directory structure looks like this:</p>
    344. 

  344. <pre>$lib/x.nim
    345. 

  345. $lib/bar/x.nim
    346. 

  346. foo/x.nim
    347. 

  347. foo/main.nim
    348. 

  348. other.nim</pre>
    349. 

  349. <p>And <tt class="docutils literal"><span class="pre"><span class="Identifier">main</span></span></tt> imports <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span><span class="Operator">/</span><span class="Identifier">x</span></span></tt> is imported. If <tt class="docutils literal"><span class="pre"><span class="Identifier">other</span></span></tt> imports <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> then both <tt class="docutils literal"><span class="pre">$lib/x.nim</span></tt> and <tt class="docutils literal"><span class="pre">$lib/bar/x.nim</span></tt> match but <tt class="docutils literal"><span class="pre">$lib/x.nim</span></tt> is used as it is the first match.</p>
    350. 

  350. 

  351. <h2><a class="toc-backref" id="compiler-usage-generated-c-code-directory" href="#compiler-usage-generated-c-code-directory">Generated C code directory</a></h2><p>The generated files that Nim produces all go into a subdirectory called <tt class="docutils literal"><span class="pre">nimcache</span></tt>. Its full path is</p>
    352. 

  352. <ul class="simple"><li><tt class="docutils literal"><span class="pre">$XDG_CACHE_HOME/nim/$projectname(_r|_d)</span></tt> or <tt class="docutils literal"><span class="pre">~/.cache/nim/$projectname(_r|_d)</span></tt> on Posix</li>
    353. 

  353. <li><tt class="docutils literal"><span class="pre">$HOME\nimcache\$projectname(_r|_d)</span></tt> on Windows.</li>
    354. 

  354. </ul>
    355. 

  355. <p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">_r</span></span></tt> suffix is used for release builds, <tt class="docutils literal"><span class="pre"><span class="Identifier">_d</span></span></tt> is for debug builds.</p>
    356. 

  356. <p>This makes it easy to delete all generated files.</p>
    357. 

  357. <p>The <tt class="docutils literal"><span class="pre option">--nimcache</span></tt> <a class="reference internal" href="#compiler-usage-commandminusline-switches">compiler switch</a> can be used to to change the <tt class="docutils literal"><span class="pre">nimcache</span></tt> directory.</p>
    358. 

  358. <p>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.</p>
    359. 

  359. 

  360. <h1><a class="toc-backref" id="compiler-selection" href="#compiler-selection">Compiler Selection</a></h1><p>To change the compiler from the default compiler (at the command line):</p>
    361. 

  361. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">--cc:llvm_gcc</span> <span class="option">--compile_only</span> <span class="Identifier">myfile.nim</span></pre></p>
    362. 

  362. <p>This uses the configuration defined in <tt class="docutils literal"><span class="pre">config\nim.cfg</span></tt> for <tt class="docutils literal"><span class="pre"><span class="program">llvm_gcc</span></span></tt>.</p>
    363. 

  363. <p>If nimcache already contains compiled code from a different compiler for the same project, add the <tt class="docutils literal"><span class="pre option">-f</span></tt> flag to force all files to be recompiled.</p>
    364. 

  364. <p>The default compiler is defined at the top of <tt class="docutils literal"><span class="pre">config\nim.cfg</span></tt>. Changing this setting affects the compiler used by <tt class="docutils literal"><span class="pre"><span class="program">koch</span></span></tt> to (re)build Nim.</p>
    365. 

  365. <p>To use the <tt class="docutils literal"><span class="pre"><span class="Identifier">CC</span></span></tt> environment variable, use <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">c</span> <span class="option">--cc:env</span> <span class="Identifier">myfile.nim</span></span></tt>. To use the <tt class="docutils literal"><span class="pre"><span class="Identifier">CXX</span></span></tt> environment variable, use <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">cpp</span> <span class="option">--cc:env</span> <span class="Identifier">myfile.nim</span></span></tt>. <tt class="docutils literal"><span class="pre option">--cc:env</span></tt> is available since Nim version 1.4.</p>
    366. 

  366. 

  367. <h1><a class="toc-backref" id="crossminuscompilation" href="#crossminuscompilation">Cross-compilation</a></h1><p>To cross compile, use for example:</p>
    368. 

  368. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">--cpu:i386</span> <span class="option">--os:linux</span> <span class="option">--compileOnly</span> <span class="option">--genScript</span> <span class="Identifier">myproject.nim</span></pre></p>
    369. 

  369. <p>Then move the C code and the compile script <tt class="docutils literal"><span class="pre"><span class="program">compile_myproject.sh</span></span></tt> to your Linux i386 machine and run the script.</p>
    370. 

  370. <p>Another way is to make Nim invoke a cross compiler toolchain:</p>
    371. 

  371. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">--cpu:arm</span> <span class="option">--os:linux</span> <span class="Identifier">myproject.nim</span></pre></p>
    372. 

  372. <p>For cross compilation, the compiler invokes a C compiler named like <tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">cpu</span><span class="Operator">.$</span><span class="Identifier">os</span><span class="Operator">.$</span><span class="Identifier">cc</span></span></tt> (for example <tt class="docutils literal"><span class="pre"><span class="Identifier">arm</span><span class="Operator">.</span><span class="Identifier">linux</span><span class="Operator">.</span><span class="Identifier">gcc</span></span></tt>) with options defined in <tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">cpu</span><span class="Operator">.$</span><span class="Identifier">os</span><span class="Operator">.$</span><span class="Identifier">cc</span><span class="Operator">.</span><span class="Identifier">options</span><span class="Operator">.</span><span class="Identifier">always</span></span></tt>. The configuration system is used to provide meaningful defaults. For example, for Linux on a 32-bit ARM CPU, your configuration file should contain something like:</p>
    373. 

  373. <pre>arm.linux.gcc.path = &quot;/usr/bin&quot;
    374. 

  374. arm.linux.gcc.exe = &quot;arm-linux-gcc&quot;
    375. 

  375. arm.linux.gcc.linkerexe = &quot;arm-linux-gcc&quot;
    376. 

  376. arm.linux.gcc.options.always = &quot;-w -fmax-errors=3&quot;</pre>
    377. 

  377. 

  378. <h1><a class="toc-backref" id="crossminuscompilation-for-windows" href="#crossminuscompilation-for-windows">Cross-compilation for Windows</a></h1><p>To cross-compile for Windows from Linux or macOS using the MinGW-w64 toolchain:</p>
    379. 

  379. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">-d:mingw</span> <span class="Identifier">myproject.nim</span>
    380. 

  380. <span class="Comment"># `nim r` also works, running the binary via `wine` or `wine64`:</span>
    381. 

  381. <span class="program">nim</span> <span class="option">r</span> <span class="option">-d:mingw</span> <span class="option">--eval:</span><span class="option">'import os; echo &quot;a&quot; / &quot;b&quot;'</span></pre></p>
    382. 

  382. <p>Use <tt class="docutils literal"><span class="pre option">--cpu:i386</span></tt> or <tt class="docutils literal"><span class="pre option">--cpu:amd64</span></tt> to switch the CPU architecture.</p>
    383. 

  383. <p>The MinGW-w64 toolchain can be installed as follows:</p>
    384. 

  384. <p><pre class="listing"><span class="program">apt</span> <span class="option">install</span> <span class="option">mingw-w64</span>   <span class="Comment"># Ubuntu</span>
    385. 

  385. <span class="program">yum</span> <span class="option">install</span> <span class="option">mingw32-gcc</span>
    386. 

  386. <span class="program">yum</span> <span class="option">install</span> <span class="option">mingw64-gcc</span> <span class="Comment"># CentOS - requires EPEL</span>
    387. 

  387. <span class="program">brew</span> <span class="option">install</span> <span class="option">mingw-w64</span>  <span class="Comment"># OSX</span></pre></p>
    388. 

  388. 

  389. <h1><a class="toc-backref" id="crossminuscompilation-for-android" href="#crossminuscompilation-for-android">Cross-compilation for Android</a></h1><p>There are two ways to compile for Android: terminal programs (Termux) and with the NDK (Android Native Development Kit).</p>
    390. 

  390. <p>The first one is to treat Android as a simple Linux and use <a class="reference external" href="https://wiki.termux.com">Termux</a> to connect and run the Nim compiler directly on android as if it was Linux. These programs are console-only programs that can't be distributed in the Play Store.</p>
    391. 

  391. <p>Use regular <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">c</span></span></tt> inside termux to make Android terminal programs.</p>
    392. 

  392. <p>Normal Android apps are written in Java, to use Nim inside an Android app you need a small Java stub that calls out to a native library written in Nim using the <a class="reference external" href="https://developer.android.com/ndk">NDK</a>. You can also use <a class="reference external" href="https://developer.android.com/ndk/samples/sample_na">native-activity</a> to have the Java stub be auto-generated for you.</p>
    393. 

  393. <p>Use <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">c</span> <span class="option">-c</span> <span class="option">--cpu:arm</span> <span class="option">--os:android</span> <span class="option">-d:androidNDK</span> <span class="option">--noMain:on</span></span></tt> to generate the C source files you need to include in your Android Studio project. Add the generated C files to CMake build script in your Android project. Then do the final compile with Android Studio which uses Gradle to call CMake to compile the project.</p>
    394. 

  394. <p>Because Nim is part of a library it can't have its own C-style <tt class="docutils literal"><span class="pre"><span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> so you would need to define your own <tt class="docutils literal"><span class="pre"><span class="Identifier">android_main</span></span></tt> and init the Java environment, or use a library like SDL2 or GLFM to do it. After the Android stuff is done, it's very important to call <tt class="docutils literal"><span class="pre"><span class="Identifier">NimMain</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> in order to initialize Nim's garbage collector and to run the top level statements of your program.</p>
    395. 

  395. <p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">NimMain</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Operator">.</span><span class="Punctuation">}</span>
    396. 

  396. <span class="Keyword">proc</span> <span class="Identifier">glfmMain</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">display</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">GLFMDisplay</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">exportc</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    397. 

  397.   <span class="Identifier">NimMain</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># initialize garbage collector memory, types and stack</span></pre></p>
    398. 

  398. <p>The name <tt class="docutils literal"><span class="pre"><span class="Identifier">NimMain</span></span></tt> can be influenced via the <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">nimMainPrefix</span><span class="Punctuation">:</span><span class="Identifier">prefix</span></span></tt> switch. Use <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">nimMainPrefix</span><span class="Punctuation">:</span><span class="Identifier">MyLib</span></span></tt> and the function to call is named <tt class="docutils literal"><span class="pre"><span class="Identifier">MyLibNimMain</span></span></tt>.</p>
    399. 

  399. 

  400. <h1><a class="toc-backref" id="crossminuscompilation-for-ios" href="#crossminuscompilation-for-ios">Cross-compilation for iOS</a></h1><p>To cross-compile for iOS you need to be on a macOS computer and use XCode. Normal languages for iOS development are Swift and Objective C. Both of these use LLVM and can be compiled into object files linked together with C, C++ or Objective C code produced by Nim.</p>
    401. 

  401. <p>Use <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">c</span> <span class="option">-c</span> <span class="option">--os:ios</span> <span class="option">--noMain:on</span></span></tt> to generate C files and include them in your XCode project. Then you can use XCode to compile, link, package and sign everything.</p>
    402. 

  402. <p>Because Nim is part of a library it can't have its own C-style <tt class="docutils literal"><span class="pre"><span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> so you would need to define <tt class="docutils literal"><span class="pre"><span class="Identifier">main</span></span></tt> that calls <tt class="docutils literal"><span class="pre"><span class="Identifier">autoreleasepool</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">UIApplicationMain</span></span></tt> to do it, or use a library like SDL2 or GLFM. After the iOS setup is done, it's very important to call <tt class="docutils literal"><span class="pre"><span class="Identifier">NimMain</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> to initialize Nim's garbage collector and to run the top-level statements of your program.</p>
    403. 

  403. <p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">NimMain</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Operator">.</span><span class="Punctuation">}</span>
    404. 

  404. <span class="Keyword">proc</span> <span class="Identifier">glfmMain</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">display</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">GLFMDisplay</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">exportc</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    405. 

  405.   <span class="Identifier">NimMain</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># initialize garbage collector memory, types and stack</span></pre></p>
    406. 

  406. <p>Note: XCode's &quot;make clean&quot; gets confused about the generated nim.c files, so you need to clean those files manually to do a clean build.</p>
    407. 

  407. <p>The name <tt class="docutils literal"><span class="pre"><span class="Identifier">NimMain</span></span></tt> can be influenced via the <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">nimMainPrefix</span><span class="Punctuation">:</span><span class="Identifier">prefix</span></span></tt> switch. Use <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">nimMainPrefix</span><span class="Punctuation">:</span><span class="Identifier">MyLib</span></span></tt> and the function to call is named <tt class="docutils literal"><span class="pre"><span class="Identifier">MyLibNimMain</span></span></tt>.</p>
    408. 

  408. 

  409. <h1><a class="toc-backref" id="crossminuscompilation-for-nintendo-switch" href="#crossminuscompilation-for-nintendo-switch">Cross-compilation for Nintendo Switch</a></h1><p>Simply add <tt class="docutils literal"><span class="pre option">--os:nintendoswitch</span></tt> to your usual <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">c</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">cpp</span></span></tt> command and set the <tt class="docutils literal"><span class="pre option">passC</span></tt> and <tt class="docutils literal"><span class="pre option">passL</span></tt> command line switches to something like:</p>
    410. 

  410. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="Identifier">...</span> <span class="option">--d:nimAllocPagesViaMalloc</span> <span class="option">--mm:orc</span> <span class="option">--passC=</span><span class="option">&quot;-I$DEVKITPRO/libnx/include&quot;</span> <span class="Identifier">...</span>
    411. 

  411. <span class="Identifier">--passL=</span><span class="option">&quot;-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx&quot;</span></pre></p>
    412. 

  412. <p>or setup a <tt class="docutils literal"><span class="pre">nim.cfg</span></tt> file like so:</p>
    413. 

  413. <pre>#nim.cfg
    414. 

  414. --mm:orc
    415. 

  415. --d:nimAllocPagesViaMalloc
    416. 

  416. --define:nimInheritHandles
    417. 

  417. --passC=&quot;-I$DEVKITPRO/libnx/include&quot;
    418. 

  418. --passL=&quot;-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx&quot;</pre>
    419. 

  419. <p>The devkitPro setup must be the same as the default with their new installer <a class="reference external" href="https://github.com/devkitPro/pacman/releases">here for Mac/Linux</a> or <a class="reference external" href="https://github.com/devkitPro/installer/releases">here for Windows</a>.</p>
    420. 

  420. <p>For example, with the above-mentioned config:</p>
    421. 

  421. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">--os:nintendoswitch</span> <span class="Identifier">switchhomebrew.nim</span></pre></p>
    422. 

  422. <p>This will generate a file called <tt class="docutils literal"><span class="pre">switchhomebrew.elf</span></tt> which can then be turned into an nro file with the <tt class="docutils literal"><span class="pre"><span class="program">elf2nro</span></span></tt> tool in the devkitPro release. Examples can be found at <a class="reference external" href="https://github.com/jyapayne/nim-libnx.git">the nim-libnx github repo</a>.</p>
    423. 

  423. <p>There are a few things that don't work because the devkitPro libraries don't support them. They are:</p>
    424. 

  424. <ol class="simple"><li>Waiting for a subprocess to finish. A subprocess can be started, but right now it can't be waited on, which sort of makes subprocesses a bit hard to use</li>
    425. 

  425. <li>Dynamic calls. Switch OS (Horizon) doesn't support dynamic libraries, so dlopen/dlclose are not available.</li>
    426. 

  426. <li>mqueue. Sadly there are no mqueue headers.</li>
    427. 

  427. <li>ucontext. No headers for these either. No coroutines for now :(</li>
    428. 

  428. <li>nl_types. No headers for this.</li>
    429. 

  429. <li>As mmap is not supported, the nimAllocPagesViaMalloc option has to be used.</li>
    430. 

  430. </ol>
    431. 

  431. 

  432. <h1><a class="toc-backref" id="gpu-compilation" href="#gpu-compilation">GPU Compilation</a></h1><p>Compiling for GPU computation can be achieved with <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">cc</span><span class="Punctuation">:</span><span class="Identifier">nvcc</span></span></tt> for CUDA with nvcc, or with <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">cc</span><span class="Punctuation">:</span><span class="Identifier">hipcc</span></span></tt> for AMD GPUs with HIP. Both compilers require building for C++ with <tt class="docutils literal"><span class="pre"><span class="Identifier">nim</span> <span class="Identifier">cpp</span></span></tt>.</p>
    433. 

  433. <p>Here's a very simple CUDA kernel example using emit, which can be compiled with <tt class="docutils literal"><span class="pre"><span class="Identifier">nim</span> <span class="Identifier">cpp</span> <span class="Operator">--</span><span class="Identifier">cc</span><span class="Punctuation">:</span><span class="Identifier">nvcc</span> <span class="Operator">--</span><span class="Identifier">define</span><span class="Punctuation">:</span><span class="StringLit">&quot;useMalloc&quot;</span> <span class="Identifier">hello_kernel</span><span class="Operator">.</span><span class="Identifier">nim</span></span></tt> assuming you have the CUDA toolkit installed.</p>
    434. 

  434. <p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;
    435. 

  435. __global__ void add(int a, int b) {
    436. 

  436.   int c;
    437. 

  437.   c = a + b;
    438. 

  438. }
    439. 

  439. &quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>
    440. 

  440. 

  441. <span class="Keyword">proc</span> <span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
    442. 

  442.   <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;
    443. 

  443.   add&lt;&lt;&lt;1,1&gt;&gt;&gt;(2,7);
    444. 

  444.   &quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>
    445. 

  445. 

  446. <span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
    447. 

  447. 

  448. <h1><a class="toc-backref" id="dll-generation" href="#dll-generation">DLL generation</a></h1><p><strong>Note</strong>: The same rules apply to <tt class="docutils literal"><span class="pre"><span class="Identifier">lib</span><span class="Operator">*.</span><span class="Identifier">so</span></span></tt> shared object files on UNIX. For better readability only the DLL version is described here.</p>
    449. 

  449. <p>Nim supports the generation of DLLs. However, there must be only one instance of the GC per process/address space. This instance is contained in <tt class="docutils literal"><span class="pre">nimrtl.dll</span></tt>. This means that every generated Nim DLL depends on <tt class="docutils literal"><span class="pre">nimrtl.dll</span></tt>. To generate the &quot;nimrtl.dll&quot; file, use the command:</p>
    450. 

  450. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">-d:release</span> <span class="Identifier">lib/nimrtl.nim</span></pre></p>
    451. 

  451. <p>To link against <tt class="docutils literal"><span class="pre">nimrtl.dll</span></tt> use the command:</p>
    452. 

  452. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">-d:useNimRtl</span> <span class="Identifier">myprog.nim</span></pre></p>
    453. 

  453. 

  454. <h1><a class="toc-backref" id="additional-compilation-switches" href="#additional-compilation-switches">Additional compilation switches</a></h1><p>The standard library supports a growing number of <tt class="docutils literal"><span class="pre"><span class="Identifier">useX</span></span></tt> conditional defines affecting how some features are implemented. This section tries to give a complete list.</p>
    455. 

  455. <table border="1" class="docutils"><tr><th>Define</th><th>Effect</th></tr>
    456. 

  456. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">release</span></span></tt></td><td>Turns on the optimizer. More aggressive optimizations are possible, e.g.: <tt class="docutils literal"><span class="pre option">--passC:-ffast-math</span></tt> (but see issue #10305)</td></tr>
    457. 

  457. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">danger</span></span></tt></td><td>Turns off all runtime checks and turns on the optimizer.</td></tr>
    458. 

  458. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">useFork</span></span></tt></td><td>Makes <tt class="docutils literal"><span class="pre"><span class="Identifier">osproc</span></span></tt> use <tt class="docutils literal"><span class="pre"><span class="Identifier">fork</span></span></tt> instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">posix_spawn</span></span></tt>.</td></tr>
    459. 

  459. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">useNimRtl</span></span></tt></td><td>Compile and link against <tt class="docutils literal"><span class="pre">nimrtl.dll</span></tt>.</td></tr>
    460. 

  460. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">useMalloc</span></span></tt></td><td>Makes Nim use C's <span id="malloc_1">malloc</span> instead of Nim's own memory manager, albeit prefixing each allocation with its size to support clearing memory on reallocation. This only works with <tt class="docutils literal"><span class="pre option">--mm:none</span></tt>, <tt class="docutils literal"><span class="pre option">--mm:arc</span></tt> and <tt class="docutils literal"><span class="pre option">--mm:orc</span></tt>.</td></tr>
    461. 

  461. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">useRealtimeGC</span></span></tt></td><td>Enables support of Nim's GC for <em>soft</em> realtime systems. See the documentation of the <a class="reference external" href="refc.html">refc</a> for further information.</td></tr>
    462. 

  462. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">logGC</span></span></tt></td><td>Enable GC logging to stdout.</td></tr>
    463. 

  463. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">nodejs</span></span></tt></td><td>The JS target is actually <tt class="docutils literal"><span class="pre">node.js</span></tt>.</td></tr>
    464. 

  464. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">ssl</span></span></tt></td><td>Enables OpenSSL support for the sockets module.</td></tr>
    465. 

  465. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">memProfiler</span></span></tt></td><td>Enables memory profiling for the native GC.</td></tr>
    466. 

  466. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">uClibc</span></span></tt></td><td>Use uClibc instead of libc. (Relevant for Unix-like OSes)</td></tr>
    467. 

  467. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">checkAbi</span></span></tt></td><td>When using types from C headers, add checks that compare what's in the Nim file with what's in the C header. This may become enabled by default in the future.</td></tr>
    468. 

  468. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">tempDir</span></span></tt></td><td>This symbol takes a string as its value, like <tt class="docutils literal"><span class="pre option">--define:tempDir:/some/temp/path</span></tt> to override the temporary directory returned by <tt class="docutils literal"><span class="pre"><span class="Identifier">os</span><span class="Operator">.</span><span class="Identifier">getTempDir</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt>. The value <strong>should</strong> end with a directory separator character. (Relevant for the Android platform)</td></tr>
    469. 

  469. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">useShPath</span></span></tt></td><td>This symbol takes a string as its value, like <tt class="docutils literal"><span class="pre option">--define:useShPath:/opt/sh/bin/sh</span></tt> to override the path for the <tt class="docutils literal"><span class="pre"><span class="program">sh</span></span></tt> binary, in cases where it is not located in the default location <tt class="docutils literal"><span class="pre">/bin/sh</span></tt>.</td></tr>
    470. 

  470. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">noSignalHandler</span></span></tt></td><td>Disable the crash handler from <tt class="docutils literal"><span class="pre">system.nim</span></tt>.</td></tr>
    471. 

  471. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">globalSymbols</span></span></tt></td><td>Load all <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">dynlib</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> libraries with the <tt class="docutils literal"><span class="pre"><span class="Identifier">RTLD_GLOBAL</span></span></tt> flag on Posix systems to resolve symbols in subsequently loaded libraries.</td></tr>
    472. 

  472. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">lto</span></span></tt></td><td>Enable link-time optimization in the backend compiler and linker.</td></tr>
    473. 

  473. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">lto_incremental</span></span></tt></td><td>Enable link-time optimization and additionally enable incremental linking for compilers that support it. Currently only clang and vcc.</td></tr>
    474. 

  474. <tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">strip</span></span></tt></td><td>Strip debug symbols added by the backend compiler from the executable.</td></tr>
    475. 

  475. </table>
    476. 

  476. <h1><a class="toc-backref" id="additional-features" href="#additional-features">Additional Features</a></h1><p>This section describes Nim's additional features that are not listed in the Nim manual. Some of the features here only make sense for the C code generator and are subject to change.</p>
    477. 

  477. 

  478. <h2><a class="toc-backref" id="additional-features-linedir-option" href="#additional-features-linedir-option">LineDir option</a></h2><p>The <tt class="docutils literal"><span class="pre option">--lineDir</span></tt> option can be turned on or off. If turned on the generated C code contains <tt class="docutils literal"><span class="pre"><span class="Preprocessor">#line</span></span></tt> directives. This may be helpful for debugging with GDB.</p>
    479. 

  479. 

  480. <h2><a class="toc-backref" id="additional-features-stacktrace-option" href="#additional-features-stacktrace-option">StackTrace option</a></h2><p>If the <tt class="docutils literal"><span class="pre option">--stackTrace</span></tt> option is turned on, the generated C contains code to ensure that proper stack traces are given if the program crashes or some uncaught exception is raised.</p>
    481. 

  481. 

  482. <h2><a class="toc-backref" id="additional-features-linetrace-option" href="#additional-features-linetrace-option">LineTrace option</a></h2><p>The <tt class="docutils literal"><span class="pre option">--lineTrace</span></tt> option implies the <tt class="docutils literal"><span class="pre option">stackTrace</span></tt> option. If turned on, the generated C contains code to ensure that proper stack traces with line number information are given if the program crashes or an uncaught exception is raised.</p>
    483. 

  483. 

  484. <h1><a class="toc-backref" id="dynliboverride" href="#dynliboverride">DynlibOverride</a></h1><p>By default Nim's <tt class="docutils literal"><span class="pre"><span class="Identifier">dynlib</span></span></tt> pragma causes the compiler to generate <tt class="docutils literal"><span class="pre"><span class="Identifier">GetProcAddress</span></span></tt> (or their Unix counterparts) calls to bind to a DLL. With the <tt class="docutils literal"><span class="pre option">dynlibOverride</span></tt> command line switch this can be prevented and then via <tt class="docutils literal"><span class="pre option">--passL</span></tt> the static library can be linked against. For instance, to link statically against Lua this command might work on Linux:</p>
    485. 

  485. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">--dynlibOverride:lua</span> <span class="Identifier">--passL:liblua.lib</span> <span class="Identifier">program.nim</span></pre></p>
    486. 

  486. 

  487. <h1><a class="toc-backref" id="backend-language-options" href="#backend-language-options">Backend language options</a></h1><p>The typical compiler usage involves using the <tt class="docutils literal"><span class="pre option">compile</span></tt> or <tt class="docutils literal"><span class="pre option">c</span></tt> command to transform a <tt class="docutils literal"><span class="pre">.nim</span></tt> file into one or more <tt class="docutils literal"><span class="pre">.c</span></tt> files which are then compiled with the platform's C compiler into a static binary. However, there are other commands to compile to C++, Objective-C, or JavaScript. More details can be read in the <a class="reference external" href="backends.html">Nim Backend Integration document</a>.</p>
    488. 

  488. 

  489. <h1><a class="toc-backref" id="nim-documentation-tools" href="#nim-documentation-tools">Nim documentation tools</a></h1><p>Nim provides the <span id="doc_1">doc</span> command to generate HTML documentation from <tt class="docutils literal"><span class="pre">.nim</span></tt> source files. Only exported symbols will appear in the output. For more details see <a class="reference external" href="docgen.html">the docgen documentation</a>.</p>
    490. 

  490. 

  491. <h1><a class="toc-backref" id="nim-idetools-integration" href="#nim-idetools-integration">Nim idetools integration</a></h1><p>Nim provides language integration with external IDEs through the idetools command. See the documentation of <a class="reference external" href="idetools.html">idetools</a> for further information.</p>
    492. 

  492. 

  493. <h1><a class="toc-backref" id="nim-for-embedded-systems" href="#nim-for-embedded-systems">Nim for embedded systems</a></h1><p>While the default Nim configuration is targeted for optimal performance on modern PC hardware and operating systems with ample memory, it is very well possible to run Nim code and a good part of the Nim standard libraries on small embedded microprocessors with only a few kilobytes of memory.</p>
    494. 

  494. <p>A good start is to use the <tt class="docutils literal"><span class="pre"><span class="Identifier">any</span></span></tt> operating target together with the <tt class="docutils literal"><span class="pre"><span class="Identifier">malloc</span></span></tt> memory allocator and the <tt class="docutils literal"><span class="pre"><span class="Identifier">arc</span></span></tt> garbage collector. For example:</p>
    495. 

  495. <p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">--os:any</span> <span class="option">--mm:arc</span> <span class="option">-d:useMalloc</span> <span class="Identifier">[...]</span> <span class="Identifier">x.nim</span></pre></p>
    496. 

  496. <ul class="simple"><li><tt class="docutils literal"><span class="pre option">--mm:arc</span></tt> will enable the reference counting memory management instead of the default garbage collector. This enables Nim to use heap memory which is required for strings and seqs, for example.</li>
    497. 

  497. <li>The <tt class="docutils literal"><span class="pre option">--os:any</span></tt> target makes sure Nim does not depend on any specific operating system primitives. Your platform should support only some basic ANSI C library <tt class="docutils literal"><span class="pre"><span class="Identifier">stdlib</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">stdio</span></span></tt> functions which should be available on almost any platform.</li>
    498. 

  498. <li>The <tt class="docutils literal"><span class="pre option">-d:useMalloc</span></tt> option configures Nim to use only the standard C memory manage primitives <tt class="docutils literal"><span class="pre"><span class="Identifier">malloc</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">free</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">realloc</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt>.</li>
    499. 

  499. </ul>
    500. 

  500. <p>If your platform does not provide these functions it should be trivial to provide an implementation for them and link these to your program.</p>
    501. 

  501. <p>For targets with very restricted memory, it might be beneficial to pass some additional flags to both the Nim compiler and the C compiler and/or linker to optimize the build for size. For example, the following flags can be used when targeting a gcc compiler:</p>
    502. 

  502. <p><tt class="docutils literal"><span class="pre option">--opt:size -d:lto -d:strip</span></tt></p>
    503. 

  503. <p>The <tt class="docutils literal"><span class="pre option">--opt:size</span></tt> flag instructs Nim to optimize code generation for small size (with the help of the C compiler), the <tt class="docutils literal"><span class="pre option">-d:lto</span></tt> flags enable link-time optimization in the compiler and linker, the <tt class="docutils literal"><span class="pre option">-d:strip</span></tt> strips debug symbols.</p>
    504. 

  504. <p>Check the <a class="reference internal" href="#crossminuscompilation">Cross-compilation</a> section for instructions on how to compile the program for your target.</p>
    505. 

  505. 

  506. <h2><a class="toc-backref" id="nim-for-embedded-systems-nimallocpagesviamalloc" href="#nim-for-embedded-systems-nimallocpagesviamalloc">nimAllocPagesViaMalloc</a></h2><p>Nim's default allocator is based on TLSF, this algorithm was designed for embedded devices. This allocator gets blocks/pages of memory via a currently undocumented <tt class="docutils literal"><span class="pre"><span class="Identifier">osalloc</span></span></tt> API which usually uses POSIX's <tt class="docutils literal"><span class="pre"><span class="Identifier">mmap</span></span></tt> call. On many environments <tt class="docutils literal"><span class="pre"><span class="Identifier">mmap</span></span></tt> is not available but C's <tt class="docutils literal"><span class="pre"><span class="Identifier">malloc</span></span></tt> is. You can use the <tt class="docutils literal"><span class="pre"><span class="Identifier">nimAllocPagesViaMalloc</span></span></tt> define to use <tt class="docutils literal"><span class="pre"><span class="Identifier">malloc</span></span></tt> instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">mmap</span></span></tt>. <tt class="docutils literal"><span class="pre"><span class="Identifier">nimAllocPagesViaMalloc</span></span></tt> is currently only supported with <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">mm</span><span class="Punctuation">:</span><span class="Identifier">arc</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">mm</span><span class="Punctuation">:</span><span class="Identifier">orc</span></span></tt>. (Since version 1.6)</p>
    507. 

  507. 

  508. <h1><a class="toc-backref" id="nimpage256-slash-nimpage512-slash-nimpage1k" href="#nimpage256-slash-nimpage512-slash-nimpage1k">nimPage256 / nimPage512 / nimPage1k</a></h1><p>Adjust the page size for Nim's GC allocator. This enables using <tt class="docutils literal"><span class="pre"><span class="Identifier">nimAllocPagesViaMalloc</span></span></tt> on devices with less RAM. The default page size requires too much RAM to work.</p>
    509. 

  509. <p>Recommended settings:</p>
    510. 

  510. <ul class="simple"><li>&lt; 32 kB of RAM use <tt class="docutils literal"><span class="pre"><span class="Identifier">nimPage256</span></span></tt></li>
    511. 

  511. <li>&lt; 512 kB of RAM use <tt class="docutils literal"><span class="pre"><span class="Identifier">nimPage512</span></span></tt></li>
    512. 

  512. <li>&lt; 2 MB of RAM use <tt class="docutils literal"><span class="pre"><span class="Identifier">nimPage1k</span></span></tt></li>
    513. 

  513. </ul>
    514. 

  514. <p>Initial testing hasn't shown much difference between 512B or 1kB page sizes in terms of performance or latency. Using <tt class="docutils literal"><span class="pre"><span class="Identifier">nimPages256</span></span></tt> will limit the total amount of allocatable RAM.</p>
    515. 

  515. 

  516. <h1><a class="toc-backref" id="nimmemaligntiny" href="#nimmemaligntiny">nimMemAlignTiny</a></h1><p>Sets <tt class="docutils literal"><span class="pre"><span class="Identifier">MemAlign</span></span></tt> to <tt class="docutils literal"><span class="pre"><span class="DecNumber">4</span></span></tt> bytes which reduces the memory alignment to better match some embedded devices.</p>
    517. 

  517. 

  518. <h1><a class="toc-backref" id="thread-stack-size" href="#thread-stack-size">Thread stack size</a></h1><p>Nim's thread API provides a simple wrapper around more advanced RTOS task features. Customizing the stack size and stack guard size can be done by setting <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">d</span><span class="Punctuation">:</span><span class="Identifier">nimThreadStackSize</span><span class="Operator">=</span><span class="DecNumber">16384</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">d</span><span class="Punctuation">:</span><span class="Identifier">nimThreadStackGuard</span><span class="Operator">=</span><span class="DecNumber">32</span></span></tt>.</p>
    519. 

  519. <p>Currently only Zephyr, NuttX and FreeRTOS support these configurations.</p>
    520. 

  520. 

  521. <h1><a class="toc-backref" id="nim-for-realtime-systems" href="#nim-for-realtime-systems">Nim for realtime systems</a></h1><p>See the <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">mm</span><span class="Punctuation">:</span><span class="Identifier">arc</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">mm</span><span class="Punctuation">:</span><span class="Identifier">orc</span></span></tt> memory management settings in <a class="reference external" href="mm.html">MM</a> for further information.</p>
    522. 

  522. 

  523. <h1><a class="toc-backref" id="signal-handling-in-nim" href="#signal-handling-in-nim">Signal handling in Nim</a></h1><p>The Nim programming language has no concept of Posix's signal handling mechanisms. However, the standard library offers some rudimentary support for signal handling, in particular, segmentation faults are turned into fatal errors that produce a stack trace. This can be disabled with the <tt class="docutils literal"><span class="pre option">-d:noSignalHandler</span></tt> switch.</p>
    524. 

  524. 

  525. <h1><a class="toc-backref" id="optimizing-for-nim" href="#optimizing-for-nim">Optimizing for Nim</a></h1><p>Nim has no separate optimizer, but the C code that is produced is very efficient. Most C compilers have excellent optimizers, so usually it is not needed to optimize one's code. Nim has been designed to encourage efficient code: The most readable code in Nim is often the most efficient too.</p>
    526. 

  526. <p>However, sometimes one has to optimize. Do it in the following order:</p>
    527. 

  527. <ol class="simple"><li>switch off the embedded debugger (it is <strong>slow</strong>!)</li>
    528. 

  528. <li>turn on the optimizer and turn off runtime checks</li>
    529. 

  529. <li>profile your code to find where the bottlenecks are</li>
    530. 

  530. <li>try to find a better algorithm</li>
    531. 

  531. <li>do low-level optimizations</li>
    532. 

  532. </ol>
    533. 

  533. <p>This section can only help you with the last item.</p>
    534. 

  534. 

  535. <h2><a class="toc-backref" id="optimizing-for-nim-optimizing-string-handling" href="#optimizing-for-nim-optimizing-string-handling">Optimizing string handling</a></h2><p>String assignments are sometimes expensive in Nim: They are required to copy the whole string. However, the compiler is often smart enough to not copy strings. Due to the argument passing semantics, strings are never copied when passed to subroutines. The compiler does not copy strings that are a result of a procedure call, because the callee returns a new string anyway. Thus it is efficient to do:</p>
    536. 

  536. <p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">s</span> <span class="Operator">=</span> <span class="Identifier">procA</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># assignment will not copy the string; procA allocates a new</span>
    537. 

  537.                 <span class="Comment"># string already</span></pre></p>
    538. 

  538. <p>However, it is not efficient to do:</p>
    539. 

  539. <p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">s</span> <span class="Operator">=</span> <span class="Identifier">varA</span>    <span class="Comment"># assignment has to copy the whole string into a new buffer!</span></pre></p>
    540. 

  540. <p>For <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> symbols a copy is not always necessary:</p>
    541. 

  541. <p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">s</span> <span class="Operator">=</span> <span class="Identifier">varA</span>    <span class="Comment"># may only copy a pointer if it safe to do so</span></pre></p>
    542. 

  542. <p>The compiler optimizes string case statements: A hashing scheme is used for them if several different string constants are used. So code like this is reasonably efficient:</p>
    543. 

  543. <p><pre class="listing"><span class="Keyword">case</span> <span class="Identifier">normalize</span><span class="Punctuation">(</span><span class="Identifier">k</span><span class="Operator">.</span><span class="Identifier">key</span><span class="Punctuation">)</span>
    544. 

  544. <span class="Keyword">of</span> <span class="StringLit">&quot;name&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">name</span> <span class="Operator">=</span> <span class="Identifier">v</span>
    545. 

  545. <span class="Keyword">of</span> <span class="StringLit">&quot;displayname&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">displayName</span> <span class="Operator">=</span> <span class="Identifier">v</span>
    546. 

  546. <span class="Keyword">of</span> <span class="StringLit">&quot;version&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">version</span> <span class="Operator">=</span> <span class="Identifier">v</span>
    547. 

  547. <span class="Keyword">of</span> <span class="StringLit">&quot;os&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">oses</span> <span class="Operator">=</span> <span class="Identifier">split</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">,</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Punctuation">;</span><span class="Punctuation">'</span><span class="Punctuation">}</span><span class="Punctuation">)</span>
    548. 

  548. <span class="Keyword">of</span> <span class="StringLit">&quot;cpu&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">cpus</span> <span class="Operator">=</span> <span class="Identifier">split</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">,</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Punctuation">;</span><span class="Punctuation">'</span><span class="Punctuation">}</span><span class="Punctuation">)</span>
    549. 

  549. <span class="Keyword">of</span> <span class="StringLit">&quot;authors&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">authors</span> <span class="Operator">=</span> <span class="Identifier">split</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">,</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Punctuation">;</span><span class="Punctuation">'</span><span class="Punctuation">}</span><span class="Punctuation">)</span>
    550. 

  550. <span class="Keyword">of</span> <span class="StringLit">&quot;description&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">description</span> <span class="Operator">=</span> <span class="Identifier">v</span>
    551. 

  551. <span class="Keyword">of</span> <span class="StringLit">&quot;app&quot;</span><span class="Punctuation">:</span>
    552. 

  552.   <span class="Keyword">case</span> <span class="Identifier">normalize</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">)</span>
    553. 

  553.   <span class="Keyword">of</span> <span class="StringLit">&quot;console&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">app</span> <span class="Operator">=</span> <span class="Identifier">appConsole</span>
    554. 

  554.   <span class="Keyword">of</span> <span class="StringLit">&quot;gui&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">app</span> <span class="Operator">=</span> <span class="Identifier">appGUI</span>
    555. 

  555.   <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">quit</span><span class="Punctuation">(</span><span class="Identifier">errorStr</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">,</span> <span class="StringLit">&quot;expected: console or gui&quot;</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    556. 

  556. <span class="Keyword">of</span> <span class="StringLit">&quot;license&quot;</span><span class="Punctuation">:</span> <span class="Identifier">c</span><span class="Operator">.</span><span class="Identifier">license</span> <span class="Operator">=</span> <span class="Identifier">UnixToNativePath</span><span class="Punctuation">(</span><span class="Identifier">k</span><span class="Operator">.</span><span class="Identifier">value</span><span class="Punctuation">)</span>
    557. 

  557. <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">quit</span><span class="Punctuation">(</span><span class="Identifier">errorStr</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">,</span> <span class="StringLit">&quot;unknown variable: &quot;</span> <span class="Operator">&amp;</span> <span class="Identifier">k</span><span class="Operator">.</span><span class="Identifier">key</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre></p>
    558. 

  558. </p>
    559. 

  559.     
    560. 

  560.   </div>
    561. 

  561. </div>
    562. 

  562. 

  563.       <div class="twelve-columns footer">
    564. 

  564.         <span class="nim-sprite"></span>
    565. 

  565.         <br>
    566. 

  566.         <small style="color: var(--hint);">Made with Nim. Generated: 2025-01-09 11:59:35 UTC</small>
    567. 

  567.       </div>
    568. 

  568.     </div>
    569. 

  569.   </div>
    570. 

  570.       <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    571. 

  571.     
    572. 

  572. </body>
    573. 

  573. </html>
    574. 

  574.