1NIM(1)                           User Manuals                           NIM(1)
2
3
4

NAME

6       nim - Nim compiler
7

SYNOPSIS

9       nim command [options] [projectfile] [arguments]
10

COMMANDS

12       Basic commands
13
14       compile, c
15           compile project with default code generator (C)
16
17       doc
18           generate the documentation for inputfile
19
20       doc2
21           generate the documentation for the whole project
22

OPTIONS

24       -p, --path:PATH
25           add path to search paths
26
27       -d, --define:SYMBOL(:VAL)
28           define  a conditional symbol (optionally: define the value for that
29       symbol)
30
31       -u, --undef:SYMBOL
32           undefine a conditional symbol
33
34       -f, --forceBuild
35           force rebuilding of all modules
36
37       --stackTrace:on|off
38           turn stack tracing on|off
39
40       --lineTrace:on|off
41           turn line tracing on|off
42
43       --threads:on|off
44           turn support for multi-threading on|off
45
46       -x, --checks:on|off
47           turn all runtime checks on|off
48
49       --objChecks:on|off
50           turn obj conversion checks on|off
51
52       --fieldChecks:on|off
53           turn case variant field checks on|off
54
55       --rangeChecks:on|off
56           turn range checks on|off
57
58       --boundChecks:on|off
59           turn bound checks on|off
60
61       --overflowChecks:on|off
62           turn int over-/underflow checks on|off
63
64       -a, --assertions:on|off
65           turn assertions on|off
66
67       --floatChecks:on|off
68           turn all floating point (NaN/Inf) checks on|off
69
70       --nanChecks:on|off
71           turn NaN checks on|off
72
73       --infChecks:on|off
74           turn Inf checks on|off
75
76       --deadCodeElim:on|off
77           whole program dead code elimination on|off
78
79       --opt:none|speed|size
80           optimize not at all or for speed|size. Note: use -d:release  for  a
81       release build!
82
83       --debugger:native|endb*
84           use native debugger (gdb) | ENDB (experimental)
85
86       --app:console|gui|lib|staticlib
87           generate a console app, GUI app, DLL, or static library
88
89       -r, --run
90           run the compiled program with given arguments
91
92       --advanced
93           show advanced command line switches
94
95       -h, --help
96           show this help
97

ADVANCED COMMANDS

99       compileToC, cc
100           compile project with C code generator
101
102       compileToCpp, cpp
103           compile project to C++ code
104
105       compileToOC, objc
106           compile project to Objective C code
107
108       js
109           compile project to Javascript
110
111       e
112           run a Nimscript file
113
114       rst2html
115           convert a reStructuredText file to HTML
116
117       rst2tex
118           convert a reStructuredText file to TeX
119
120       jsondoc
121           extract the documentation to a json file
122
123       jsondoc2
124           extract documentation to a json file (uses doc2)
125
126       buildIndex
127           build an index for the whole documentation
128
129       run
130           run the project (with Tiny C backend; buggy!)
131
132       genDepend
133           generate a DOT file containing the module dependency graph
134
135       dump
136           dump all defined conditionals and search paths
137
138       check
139           checks the project for syntax and semantic
140

ADVANCED OPTIONS

142       -o:FILE, --out:FILE
143           set the output filename
144
145       --stdout
146           output to stdout
147
148       --colors:on|off
149           turn compiler messages coloring on|off
150
151       --listFullPaths
152           list full paths in messages
153
154       -w:on|off|list, --warnings:on|off|list
155           turn all warnings on|off or list all available
156
157       --warning[X]:on|off
158           turn specific warning X on|off
159
160       --hints:on|off|list
161           turn all hints on|off or list all available
162
163       --hint[X]:on|off
164           turn specific hint X on|off
165
166       --lib:PATH
167           set the system library path
168
169       --import:PATH
170           add an automatically imported module
171
172       --include:PATH
173           add an automatically included module
174
175       --nimcache:PATH
176           set the path used for generated files
177
178       --header:FILE
179           the compiler should produce a .h file (FILE is optional)
180
181       -c, --compileOnly
182           compile only; do not assemble or link
183
184       --noLinking
185           compile but do not link
186
187       --noMain
188           do not generate a main procedure
189
190       --genScript
191           generate  a  compile  script  (in the 'nimcache' subdirectory named
192       'compile_$project$scriptext')
193
194       --os:SYMBOL
195           set the target operating system (cross-compilation)
196
197       --cpu:SYMBOL
198           set the target processor (cross-compilation)
199
200       --debuginfo
201           enables debug information
202
203       -t, --passC:OPTION
204           pass an option to the C compiler
205
206       -l, --passL:OPTION
207           pass an option to the linker
208
209       --cincludes:DIR
210           modify the C compiler header search path
211
212       --clibdir:DIR
213           modify the linker library search path
214
215       --clib:LIBNAME
216           link an additional C library  (you  should  omit  platform-specific
217       extensions)
218
219       --genMapping
220           generate a mapping file containing (Nim, mangled) identifier pairs
221
222       --project
223           document the whole project (doc2)
224
225       --docSeeSrcUrl:url
226           activate   'see   source'   for   doc   and   doc2   commands  (see
227       doc.item.seesrc in config/nimdoc.cfg)
228
229       --lineDir:on|off
230           generation of #line directive on|off
231
232       --embedsrc
233           embeds the original source code as comments in the generated output
234
235       --threadanalysis:on|off
236           turn thread analysis on|off
237
238       --tlsEmulation:on|off
239           turn thread local storage emulation on|off
240
241       --taintMode:on|off
242           turn taint mode on|off
243
244       --implicitStatic:on|off
245           turn implicit compile time evaluation on|off
246
247       --patterns:on|off
248           turn pattern matching on|off
249
250       --memTracker:on|off
251           turn memory tracker on|off
252
253       --excessiveStackTrace:on|off
254           stack traces use full file paths
255
256       --skipCfg
257           do not read the general configuration file
258
259       --skipUserCfg
260           do not read the user's configuration file
261
262       --skipParentCfg
263           do not read the parent dirs' configuration files
264
265       --skipProjCfg
266           do not read the project's configuration file
267
268       --gc:refc|v2|markAndSweep|boehm|go|none|regions
269           select the GC to use; default is refc
270
271       --index:on|off
272           turn index file generation on|off
273
274       --putenv:key=value
275           set an environment variable
276
277       --NimblePath:PATH
278           add a path for Nimble support
279
280       --noNimblePath
281           deactivate the Nimble path
282
283       --noCppExceptions
284           use default exception handling with C++ backend
285
286       --excludePath:PATH
287           exclude a path from the list of search paths
288
289       --dynlibOverride:SYMBOL
290           marks SYMBOL so that dynlib:SYMBOL has no effect and can be  stati‐
291       cally  linked  instead;  symbol matching is fuzzy so that --dynlibOver‐
292       ride:lua matches dynlib: "liblua.so.3"
293
294       --listCmd
295           list the commands used to execute external programs
296
297       --parallelBuild:0|1|...
298           perform a parallel build  value  =  number  of  processors  (0  for
299       auto-detect)
300
301       --verbosity:0|1|2|3
302           set Nim's verbosity level (1 is default)
303
304       --experimental
305           enable experimental language features
306
307       -v, --version
308           show detailed version information
309

LIST OF WARNINGS

311       Each  warning can be activated individually with --warning[NAME]:on|off
312       or in a push pragma.
313
314       ┌──────────────────────┬─────────────────────────────────────────────────────────────────────────┐
315Name          Description                               
316       ├──────────────────────┼─────────────────────────────────────────────────────────────────────────┤
317       │CannotOpenFile        │ Some file not essential for the compiler's working could not be opened. │
318       ├──────────────────────┼─────────────────────────────────────────────────────────────────────────┤
319       │OctalEscape           │ The code contains an unsupported octal sequence.                        │
320       ├──────────────────────┼─────────────────────────────────────────────────────────────────────────┤
321       │Deprecated            │ The code uses a deprecated symbol.                                      │
322       ├──────────────────────┼─────────────────────────────────────────────────────────────────────────┤
323       │ConfigDeprecated      │ The project makes use of a deprecated config file.                      │
324       ├──────────────────────┼─────────────────────────────────────────────────────────────────────────┤
325       │SmallLshouldNotBeUsed │ The letter 'l' should not be used as an identifier.                     │
326       ├──────────────────────┼─────────────────────────────────────────────────────────────────────────┤
327       │EachIdentIsTuple      │ The code contains a confusing var declaration.                          │
328       ├──────────────────────┼─────────────────────────────────────────────────────────────────────────┤
329       │ShadowIdent           │ A local variable shadows another local variable of an outer scope.      │
330       ├──────────────────────┼─────────────────────────────────────────────────────────────────────────┤
331       │User                  │ Some user defined warning.                                              │
332       └──────────────────────┴─────────────────────────────────────────────────────────────────────────┘

VERBOSITY LEVELS

334       0:
335           Minimal output level for the compiler.
336
337       1:
338           Displays compilation of all the  compiled  files,  including  those
339       imported  by  other modules or through the compile pragma ⟨https://nim-
340       lang.org/docs/nimc.html#compile-pragma⟩. This is the default level.
341
342       2:
343           Displays compilation statistics, enumerates the  dynamic  libraries
344       that  will  be  loaded by the final binary and dumps to standard output
345       the result of applying  a  filter  to  the  source  code  ⟨https://nim-
346       lang.org/docs/filters.html⟩ if any filter was used during compilation.
347
348       3:
349           In  addition  to  the previous levels dumps a debug stack trace for
350       compiler developers.
351

COMPILE TIME SYMBOLS

353       Through the -d:x or --define:x switch you can define compile time  sym‐
354       bols  for  conditional compilation. The defined switches can be checked
355       in source code with the when statement and defined  proc.  The  typical
356       use  of  this  switch  is to enable builds in release mode (-d:release)
357       where certain safety checks are omitted for better performance. Another
358       common use is the -d:ssl switch to activate SSL sockets.
359
360       Additionally,  you may pass a value along with the symbol: -d:x=y which
361       may be used in conjunction with the  compile  time  define  pragmas  to
362       override symbols during build time.
363

CONFIGURATION FILES

365       Note: The project file name is the name of the .nim file that is passed
366       as a command line argument to the compiler.
367
368       The nim executable  processes  configuration  files  in  the  following
369       directories (in this order; later files overwrite previous settings):
370
371              1      $nim/config/nim.cfg, /etc/nim.cfg (UNIX) or %NIMROD%/con‐
372                     fig/nim.cfg (Windows). This file can be skipped with  the
373                     --skipCfg command line option.
374
375              2      /home/$user/.config/nim.cfg  (UNIX)  or %APPDATA%/nim.cfg
376                     (Windows). This file can be skipped with the  --skipUser‐
377                     Cfg command line option.
378
379              3      $parentDir/nim.cfg where $parentDir stands for any parent
380                     directory of the project file's path. These files can  be
381                     skipped with the --skipParentCfg command line option.
382
383              4      $projectDir/nim.cfg  where  $projectDir  stands  for  the
384                     project file's path. This file can be  skipped  with  the
385                     --skipProjCfg command line option.
386
387              5      A  project can also have a project specific configuration
388                     file named $project.nim.cfg  that  resides  in  the  same
389                     directory  as $project.nim. This file can be skipped with
390                     the --skipProjCfg command line option.  Command line set‐
391                     tings have priority over configuration file settings.
392
393       The  default  build of a project is a debug build. To compile a release
394       build define the release symbol:
395
396              nim c -d:release myproject.nim
397

SEARCH PATH HANDLING

399       Nim has the concept of a global search path (PATH) that is  queried  to
400       determine  where to find imported modules or include files. If multiple
401       files are found an ambiguity error is produced.
402
403       nim dump shows the contents of the PATH.
404
405       However before the PATH is used the current directory  is  checked  for
406       the  file's  existence.  So if PATH contains  $lib and $lib/bar and the
407       directory structure looks like this:
408
409              $lib/x.nim
410              $lib/bar/x.nim
411              foo/x.nim
412              foo/main.nim
413              other.nim
414
415       And main imports x, foo/x is imported. If other  imports  x  then  both
416       $lib/x.nim  and  $lib/bar/x.nim match and so the compiler should reject
417       it. Currently however this check is not  implemented  and  instead  the
418       first matching file is used.
419

GENERATED C CODE DIRECTORY

421       The generated files that Nim produces all go into a subdirectory called
422       nimcache in your project directory. This makes it easy  to  delete  all
423       generated  files.  Files  generated  in  this directory follow a naming
424       logic which you can read about in the Nim Backend Integration  document
425https://nim-lang.org/docs/backends.html#nimcache-naming-logic⟩.
426
427       However,  the generated C code is not platform independent. C code gen‐
428       erated for Linux does not compile on Windows, for instance. The comment
429       on  top  of  the C file lists the OS, CPU and CC the file has been com‐
430       piled for.
431

COMPILATION CACHE

433       Warning: The compilation cache is still highly experimental!
434
435       The nimcache directory may also contain so called rod or symbol  files.
436       These  files  are pre-compiled modules that are used by the compiler to
437       perform incremental compilation. This means that only modules that have
438       changed  since  the  last compilation (or the modules depending on them
439       etc.) are re-compiled. However, per default no symbol files are  gener‐
440       ated; use the --symbolFiles:on command line switch to activate them.
441
442       Unfortunately  due  to  technical reasons the --symbolFiles:on needs to
443       aggregate some generated C code. This means  that  the  resulting  exe‐
444       cutable  might  contain  some  cruft even when dead code elimination is
445       turned on. So the final release build should  be  done  with  --symbol‐
446       Files:off.
447
448       Due  to  the  aggregation  of  C  code it is also recommended that each
449       project resides in its own directory so  that  the  generated  nimcache
450       directory is not shared between different projects.
451

COMPILER SELECTION

453       To change the compiler from the default compiler (at the command line):
454
455              nim c --cc:llvm_gcc --compile_only myfile.nim
456
457       This uses the configuration defined in config\nim.cfg for llvm_gcc.
458
459       If  nimcache  already  contains compiled code from a different compiler
460       for the same project, add the -f flag to force all files to  be  recom‐
461       piled.
462
463       The  default compiler is defined at the top of config\nim.cfg. Changing
464       this setting affects the compiler used by koch to (re)build Nim.
465

CROSS COMPILATION

467       To cross compile, use for example:
468
469              nim c --cpu:i386 --os:linux --compileOnly --genScript myproject.nim
470
471       Then move the C code and the  compile  script  compile_myproject.sh  to
472       your Linux i386 machine and run the script.
473
474       Another way is to make Nim invoke a cross compiler toolchain:
475
476              nim c --cpu:arm --os:linux myproject.nim
477
478       For  cross  compilation,  the  compiler invokes a C compiler named like
479       $cpu.$os.$cc (for example arm.linux.gcc) and the  configuration  system
480       is  used  to provide meaningful defaults. For example for ARM your con‐
481       figuration file should contain something like:
482
483              arm.linux.gcc.path = "/usr/bin"
484              arm.linux.gcc.exe = "arm-linux-gcc"
485              arm.linux.gcc.linkerexe = "arm-linux-gcc"
486
487       DLL GENERATION
488
489       Nim supports the generation of DLLs. However, there must  be  only  one
490       instance  of  the  GC  per process/address space. This instance is con‐
491       tained in nimrtl.dll. This means that every generated Nim  DLL  depends
492       on nimrtl.dll. To generate the "nimrtl.dll" file, use the command:
493
494              nim c -d:release lib/nimrtl.nim
495
496       To link against nimrtl.dll use the command:
497
498              nim c -d:useNimRtl myprog.nim
499
500       Note:  Currently  the  creation  of  nimrtl.dll with thread support has
501       never been tested and is unlikely to work!
502

ADDITIONAL COMPILATION SWITCHES

504       The standard library supports a  growing  number  of  useX  conditional
505       defines affecting how some features are implemented. This section tries
506       to give a complete list.
507
508       -d:release
509           Turns off runtime checks and turns on the optimizer.
510
511       -d:useWinAnsi
512           Modules like os and osproc use the ANSI  versions  of  the  Windows
513       API. The default build uses the Unicode version.
514
515       -d:useFork
516           Makes osproc use fork instead of posix_spawn.
517
518       -d:useNimRtl
519           Compile and link against nimrtl.dll.
520
521       -d:useMalloc
522           Makes  Nim  use  C's  malloc  instead  of Nim's own memory manager,
523       ableit prefixing each allocation with its size to support clearing mem‐
524       ory on reallocation. This only works with gc:none.
525
526       -d:useRealtimeGC
527           Enables support of Nim's GC for soft realtime systems. See the doc‐
528       umentation of the gc  ⟨https://nim-lang.org/docs/gc.html⟩  for  further
529       information.
530
531       -d:nodejs
532           The JS target is actually node.js.
533
534       -d:ssl
535           Enables OpenSSL support for the sockets module.
536
537       -d:memProfiler
538           Enables memory profiling for the native GC.
539
540       -d:uClibc
541           Use uClibc instead of libc. (Relevant for Unix-like OSes)
542
543       -d:checkAbi
544           When  using types from C headers, add checks that compare what's in
545       the Nim file with what's in the C header (requires a  C  compiler  with
546       Staticassert support, like any C11 compiler)
547
548       -d:tempDir:PATH
549           This  symbol  takes  a  string  as  its  value,  like --define:tem‐
550       pDir:/some/temp/path to override the temporary  directory  returned  by
551       os.getTempDir().  The value should end with a directory separator char‐
552       acter. (Relevant for the Android platform)
553
554       -d:useShPath:PATH
555           This symbol takes a  string  as  its  value,  like  --define:useSh‐
556       Path:/opt/sh/bin/sh  to  override  the path for the sh binary, in cases
557       where it is not located in the default location /bin/sh.
558

ADDITIONAL FEATURES

560       This section describes Nim's additional features that are not listed in
561       the  Nim  manual.  Some  of the features here only make sense for the C
562       code generator and are subject to change.
563
564       LineDir option
565           The lineDir option can be turned on or off. If turned on the gener‐
566       ated  C  code contains #line directives. This may be helpful for debug‐
567       ging with GDB.
568
569       StackTrace option
570           If the stackTrace option is turned on,  the  generated  C  contains
571       code  to  ensure  that  proper  stack  traces  are given if the program
572       crashes or an uncaught exception is raised.
573
574       LineTrace option
575           The lineTrace option implies the stackTrace option. If  turned  on,
576       the  generated  C contains code to ensure that proper stack traces with
577       line number information are given if the program crashes or an uncaught
578       exception is raised.
579
580       Debugger option
581           The  debugger option enables or disables the Embedded Nim Debugger.
582       See the documentation of endb ⟨https://nim-lang.org/docs/endb.html⟩ for
583       further information.
584
585       Breakpoint pragma
586           The breakpoint pragma was specially added for the sake of debugging
587       with   ENDB.   See   the   documentation    of    endb    ⟨https://nim-
588       lang.org/docs/endb.html⟩ for further information.
589

DynlibOverride

591       By  default Nim's dynlib pragma causes the compiler to generate GetPro‐
592       cAddress (or their Unix counterparts) calls to bind to a DLL. With  the
593       dynlibOverride  command  line switch this can be prevented and then via
594       --passL the static library can be linked against. For instance, to link
595       statically against Lua this command might work on Linux:
596
597              nim c --dynlibOverride:lua --passL:liblua.lib program.nim
598

BACKEND LANGUAGE OPTIONS

600       The  typical  compiler usage involves using the compile or c command to
601       transform a .nim file into one or more .c files which are then compiled
602       with  the platform's C compiler into a static binary. However there are
603       other commands to compile  to  C++,  Objective-C  or  Javascript.  More
604       details   can   be   read  in  the  Nim  Backend  Integration  document
605https://nim-lang.org/docs/backends.html⟩.
606

NIM DOCUMENTATION TOOLS

608       Nim provides the doc and doc2 commands to generate  HTML  documentation
609       from  .nim  source files. Only exported symbols will appear in the out‐
610       put. For  more  details  see  the  docgen  documentation  ⟨https://nim-
611       lang.org/docs/docgen.html⟩.
612

NIM IDETOOLS INTEGRATION

614       Nim  provides  language  integration  with  external  IDEs  through the
615       idetools command.  See  the  documentation  of  idetools  ⟨https://nim-
616       lang.org/docs/idetools.html⟩ for further information.
617

NIM FOR EMBEDDED SYSTEMS

619       The  standard library can be avoided to a point where C code generation
620       for 16bit micro controllers is  feasible.  Use  the  standalone  target
621       (--os:standalone)  for  a bare bones standard library that lacks any OS
622       features.
623
624       To make the compiler output code for a 16bit target use  the  --cpu:avr
625       target.
626
627       For example, to generate code for an AVR processor use this command:
628
629              nim c --cpu:avr --os:standalone --deadCodeElim:on --genScript x.nim
630
631       For  the  standalone  target  one  needs  to  provide a file panicover‐
632       ride.nim. See  tests/manyloc/standalone/panicoverride.nim for an  exam‐
633       ple  implementation.  Additionally,  users should specify the amount of
634       heap space to use  with  the  -d:StandaloneHeapSize=SIZE  command  line
635       switch. Note that the total heap size will be SIZE * sizeof(float64).
636

NIM FOR REALTIME SYSTEMS

638       See   the   documentation  of  Nim's  soft  realtime  GC  ⟨https://nim-
639       lang.org/docs/gc.html⟩ for further information.
640

DEBUGGING WITH NIM

642       Nim comes with its own Embedded Nim Debugger. See the documentation  of
643       endb ⟨https://nim-lang.org/docs/endb.html⟩ for further information.
644

OPTIMIZING FOR NIM

646       Nim  has no separate optimizer, but the C code that is produced is very
647       efficient. Most C compilers have excellent optimizers, so usually it is
648       not  needed  to optimize one's code. Nim has been designed to encourage
649       efficient code: The most readable code in Nim is often the  most  effi‐
650       cient too.
651
652       However, sometimes one has to optimize. Do it in the following order:
653
654              1      switch off the embedded debugger (it is slow!)
655
656              2      turn on the optimizer and turn off runtime checks
657
658              3      profile your code to find where the bottlenecks are
659
660              4      try to find a better algorithm
661
662              5      do low-level optimizations
663
664       This section can only help you with the last item.
665
666       Optimizing string handling
667
668       String assignments are sometimes expensive in Nim: They are required to
669       copy the whole string. However, the compiler is often smart  enough  to
670       not  copy  strings.  Due to the argument passing semantics, strings are
671       never copied when passed to subroutines. The  compiler  does  not  copy
672       strings  that  are  a  result from a procedure call, because the callee
673       returns a new string anyway. Thus it is efficient to do:
674
675              var s = procA() # assignment will not copy the string; procA allocates a new
676                              # string already
677
678       However it is not efficient to do:
679
680              var s = varA    # assignment has to copy the whole string into a new buffer!
681
682       For let symbols a copy is not always necessary:
683
684              let s = varA    # may only copy a pointer if it safe to do so
685
686       If you know what you're doing, you can  also  mark  single  string  (or
687       sequence) objects as shallow:
688
689              var s = "abc"
690              shallow(s) # mark 's' as shallow string
691              var x = s  # now might not copy the string!
692
693       Usage of shallow is always safe once you know the string won't be modi‐
694       fied anymore, similar to Ruby's freeze.
695
696       The compiler optimizes string case statements: A hashing scheme is used
697       for  them  if several different string constants are used. So code like
698       this is reasonably efficient:
699
700              case normalize(k.key)
701              of "name": c.name = v
702              of "displayname": c.displayName = v
703              of "version": c.version = v
704              of "os": c.oses = split(v, {';'})
705              of "cpu": c.cpus = split(v, {';'})
706              of "authors": c.authors = split(v, {';'})
707              of "description": c.description = v
708              of "app":
709                case normalize(v)
710                of "console": c.app = appConsole
711                of "gui": c.app = appGUI
712                else: quit(errorStr(p, "expected: console or gui"))
713              of "license": c.license = UnixToNativePath(k.value)
714              else: quit(errorStr(p, "unknown variable: " & k.key))
715

SEE ALSO

717       Official documentation ⟨https://nim-lang.org/documentation.html⟩,  nim‐
718       grep(1)
719
720
721
722Linux                           SEPTEMBER 2017                          NIM(1)
Impressum