advopt.txt 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180
  1. Advanced commands:
  2. //compileToC, cc compile project with C code generator
  3. //compileToCpp, cpp compile project to C++ code
  4. //compileToOC, objc compile project to Objective C code
  5. //js compile project to Javascript
  6. //e run a Nimscript file
  7. //md2html convert a Markdown file to HTML
  8. use `--docCmd:skip` to skip compiling snippets
  9. //rst2html convert a reStructuredText file to HTML
  10. use `--docCmd:skip` to skip compiling snippets
  11. //md2tex convert a Markdown file to LaTeX
  12. //rst2tex convert a reStructuredText file to LaTeX
  13. //doc2tex extract the documentation to a LaTeX file
  14. //jsondoc extract the documentation to a json file
  15. //ctags create a tags file
  16. //buildIndex build an index for the whole documentation
  17. //genDepend generate a DOT file containing the
  18. module dependency graph
  19. //dump dump all defined conditionals and search paths
  20. see also: --dump.format:json (useful with: `| jq`)
  21. //check checks the project for syntax and semantics
  22. (can be combined with --defusages)
  23. Runtime checks (see -x):
  24. --objChecks:on|off turn obj conversion checks on|off
  25. --fieldChecks:on|off turn case variant field checks on|off
  26. --rangeChecks:on|off turn range checks on|off
  27. --boundChecks:on|off turn bound checks on|off
  28. --overflowChecks:on|off turn int over-/underflow checks on|off
  29. --floatChecks:on|off turn all floating point (NaN/Inf) checks on|off
  30. --nanChecks:on|off turn NaN checks on|off
  31. --infChecks:on|off turn Inf checks on|off
  32. Advanced options:
  33. --defusages:FILE,LINE,COL
  34. find the definition and all usages of a symbol
  35. -o:FILE, --out:FILE set the output filename
  36. --outdir:DIR set the path where the output file will be written
  37. --usenimcache will use `outdir=$$nimcache`, whichever it resolves
  38. to after all options have been processed
  39. --stdout:on|off output to stdout
  40. --colors:on|off turn compiler messages coloring on|off
  41. --filenames:abs|canonical|legacyRelProj
  42. customize how filenames are rendered in compiler messages,
  43. defaults to `abs` (absolute)
  44. --processing:dots|filenames|off
  45. show files as they're being processed by nim compiler
  46. --unitsep:on|off use the ASCII unit separator (31) between error
  47. messages, useful for IDE-like tooling
  48. --declaredLocs:on|off show declaration locations in messages
  49. --spellSuggest:num show at most `num >= 0` spelling suggestions on typos.
  50. if `num` is not specified (or `auto`), return
  51. an implementation defined set of suggestions.
  52. --hints:on|off|list. `on|off` enables or disables hints.
  53. `list` reports which hints are selected.
  54. --hint:X:on|off turn specific hint X on|off. `hint:X` means `hint:X:on`,
  55. as with similar flags. `all` is the set of all hints
  56. (only `all:off` is supported).
  57. --hintAsError:X:on|off turn specific hint X into an error on|off
  58. -w:on|off|list, --warnings:on|off|list
  59. `on|off` enables or disables warnings.
  60. `list` reports which warnings are selected.
  61. --warning:X:on|off turn specific warning X on|off. `warning:X` means `warning:X:on`,
  62. as with similar flags. `all` is the set of all warning
  63. (only `all:off` is supported).
  64. --warningAsError:X:on|off
  65. turn specific warning X into an error on|off
  66. --styleCheck:off|hint|error
  67. produce hints or errors for Nim identifiers that
  68. do not adhere to Nim's official style guide
  69. https://nim-lang.org/docs/nep1.html
  70. --styleCheck:usages only enforce consistent spellings of identifiers,
  71. do not enforce the style on declarations
  72. --showAllMismatches:on|off
  73. show all mismatching candidates in overloading
  74. resolution
  75. --lib:PATH set the system library path
  76. --import:PATH add an automatically imported module
  77. see also `patchFile` in nimscript which offers more flexibility.
  78. --include:PATH add an automatically included module
  79. --nimcache:PATH set the path used for generated files
  80. see also https://nim-lang.org/docs/nimc.html#compiler-usage-generated-c-code-directory
  81. -c, --compileOnly:on|off compile Nim files only; do not assemble or link
  82. --noLinking:on|off compile Nim and generated files but do not link
  83. --noMain:on|off do not generate a main procedure
  84. --genScript:on|off generate a compile script (in the 'nimcache'
  85. subdirectory named 'compile_$$project$$scriptext'),
  86. and a '.deps' file containing the dependencies;
  87. implies --compileOnly
  88. --os:SYMBOL set the target operating system (cross-compilation)
  89. --cpu:SYMBOL set the target processor (cross-compilation)
  90. --debuginfo:on|off enables debug information
  91. -t, --passC:OPTION pass an option to the C compiler
  92. -l, --passL:OPTION pass an option to the linker
  93. --cc:SYMBOL specify the C compiler
  94. --cincludes:DIR modify the C compiler header search path
  95. --clibdir:DIR modify the linker library search path
  96. --clib:LIBNAME link an additional C library
  97. (you should omit platform-specific extensions)
  98. --project document the whole project (doc)
  99. --docRoot:path `nim doc --docRoot:/foo --project --outdir:docs /foo/sub/main.nim`
  100. generates: docs/sub/main.html
  101. if path == @pkg, will use nimble file enclosing dir
  102. if path == @path, will use first matching dir in `--path`
  103. if path == @default (the default and most useful), will use
  104. best match among @pkg,@path.
  105. if these are nonexistent, will use project path
  106. -b, --backend:c|cpp|js|objc
  107. sets backend to use with commands like `nim doc` or `nim r`
  108. --docCmd:cmd if `cmd == skip`, skips runnableExamples
  109. else, runs runnableExamples with given options, e.g.:
  110. `--docCmd:"-d:foo --threads:on"`
  111. --docSeeSrcUrl:url activate 'see source' for doc command
  112. (see doc.item.seesrc in config/nimdoc.cfg)
  113. --docInternal also generate documentation for non-exported symbols
  114. --lineDir:on|off generation of #line directive on|off
  115. --embedsrc:on|off embeds the original source code as comments
  116. in the generated output
  117. --tlsEmulation:on|off turn thread local storage emulation on|off
  118. --implicitStatic:on|off turn implicit compile time evaluation on|off
  119. --trmacros:on|off turn term rewriting macros on|off
  120. --multimethods:on|off turn multi-methods on|off
  121. --hotCodeReloading:on|off
  122. turn support for hot code reloading on|off
  123. --excessiveStackTrace:on|off
  124. stack traces use full file paths
  125. --stackTraceMsgs:on|off enable user defined stack frame msgs via `setFrameMsg`
  126. --skipCfg:on|off do not read the nim installation's configuration file
  127. --skipUserCfg:on|off do not read the user's configuration file
  128. --skipParentCfg:on|off do not read the parent dirs' configuration files
  129. --skipProjCfg:on|off do not read the project's configuration file
  130. --mm:orc|arc|refc|markAndSweep|boehm|go|none|regions
  131. select which memory management to use; default is 'orc'
  132. --exceptions:setjmp|cpp|goto|quirky
  133. select the exception handling implementation
  134. --index:on|off|only docgen: turn index file generation on|off (`only` means
  135. not generate output files like HTML)
  136. --noImportdoc:on|off turn loading documentation ``.idx`` files on|off
  137. --putenv:key=value set an environment variable
  138. --NimblePath:PATH add a path for Nimble support
  139. --noNimblePath deactivate the Nimble path
  140. --clearNimblePath empty the list of Nimble package search paths
  141. --cppCompileToNamespace:namespace
  142. use the provided namespace for the generated C++ code,
  143. if no namespace is provided "Nim" will be used
  144. --nimMainPrefix:prefix use `{prefix}NimMain` instead of `NimMain` in the produced
  145. C/C++ code
  146. --expandMacro:MACRO dump every generated AST from MACRO
  147. --expandArc:PROCNAME show how PROCNAME looks like after diverse optimizations
  148. before the final backend phase (mostly ARC/ORC specific)
  149. --excludePath:PATH exclude a path from the list of search paths
  150. --dynlibOverride:SYMBOL marks SYMBOL so that dynlib:SYMBOL
  151. has no effect and can be statically linked instead;
  152. symbol matching is fuzzy so
  153. that --dynlibOverride:lua matches
  154. dynlib: "liblua.so.3"
  155. --dynlibOverrideAll
  156. disables the effects of the dynlib pragma
  157. --listCmd list the compilation commands; can be combined with
  158. `--hint:exec:on` and `--hint:link:on`
  159. --asm produce assembler code
  160. --parallelBuild:0|1|... perform a parallel build
  161. value = number of processors (0 for auto-detect)
  162. --incremental:on|off only recompile the changed modules (experimental!)
  163. --verbosity:0|1|2|3 set Nim's verbosity level (1 is default)
  164. --errorMax:N stop compilation after N errors; 0 means unlimited
  165. --maxLoopIterationsVM:N set max iterations for all VM loops
  166. --experimental:$1
  167. enable experimental language feature
  168. --legacy:$2
  169. enable obsolete/legacy language feature
  170. --benchmarkVM:on|off turn benchmarking of VM code with cpuTime() on|off
  171. --profileVM:on|off turn compile time VM profiler on|off
  172. --panics:on|off turn panics into process terminations (default: off)
  173. --deepcopy:on|off enable 'system.deepCopy' for ``--mm:arc|orc``
  174. --jsbigint64:on|off toggle the use of BigInt for 64-bit integers for
  175. the JavaScript backend (default: on)
  176. --nimBasePattern:nimbase.h
  177. allows to specify a custom pattern for `nimbase.h`