1NIM(1) User Manuals NIM(1)
2
6 nim - Nim compiler
7
9 nim command [options] [projectfile] [arguments]
10
12 Basic commands
13 compile, c
15 compile project with default code generator (C)
16 doc
18 generate the documentation for inputfile
19 doc2
21 generate the documentation for the whole project
22
24 -p, --path:PATH
25 add path to search paths
26 -d, --define:SYMBOL(:VAL)
28 define a conditional symbol (optionally: define the value for that
29 symbol)
30 -u, --undef:SYMBOL
32 undefine a conditional symbol
33 -f, --forceBuild
35 force rebuilding of all modules
36 --stackTrace:on|off
38 turn stack tracing on|off
39 --lineTrace:on|off
41 turn line tracing on|off
42 --threads:on|off
44 turn support for multi-threading on|off
45 -x, --checks:on|off
47 turn all runtime checks on|off
48 --objChecks:on|off
50 turn obj conversion checks on|off
51 --fieldChecks:on|off
53 turn case variant field checks on|off
54 --rangeChecks:on|off
56 turn range checks on|off
57 --boundChecks:on|off
59 turn bound checks on|off
60 --overflowChecks:on|off
62 turn int over-/underflow checks on|off
63 -a, --assertions:on|off
65 turn assertions on|off
66 --floatChecks:on|off
68 turn all floating point (NaN/Inf) checks on|off
69 --nanChecks:on|off
71 turn NaN checks on|off
72 --infChecks:on|off
74 turn Inf checks on|off
75 --deadCodeElim:on|off
77 whole program dead code elimination on|off
78 --opt:none|speed|size
80 optimize not at all or for speed|size. Note: use -d:release for a
81 release build!
82 --debugger:native|endb*
84 use native debugger (gdb) | ENDB (experimental)
85 --app:console|gui|lib|staticlib
87 generate a console app, GUI app, DLL, or static library
88 -r, --run
90 run the compiled program with given arguments
91 --advanced
93 show advanced command line switches
94 -h, --help
96 show this help
97
99 compileToC, cc
100 compile project with C code generator
101 compileToCpp, cpp
103 compile project to C++ code
104 compileToOC, objc
106 compile project to Objective C code
107 js
109 compile project to Javascript
110 e
112 run a Nimscript file
113 rst2html
115 convert a reStructuredText file to HTML
116 rst2tex
118 convert a reStructuredText file to TeX
119 jsondoc
121 extract the documentation to a json file
122 jsondoc2
124 extract documentation to a json file (uses doc2)
125 buildIndex
127 build an index for the whole documentation
128 run
130 run the project (with Tiny C backend; buggy!)
131 genDepend
133 generate a DOT file containing the module dependency graph
134 dump
136 dump all defined conditionals and search paths
137 check
139 checks the project for syntax and semantic
140
142 -o:FILE, --out:FILE
143 set the output filename
144 --stdout
146 output to stdout
147 --colors:on|off
149 turn compiler messages coloring on|off
150 --listFullPaths
152 list full paths in messages
153 -w:on|off|list, --warnings:on|off|list
155 turn all warnings on|off or list all available
156 --warning[X]:on|off
158 turn specific warning X on|off
159 --hints:on|off|list
161 turn all hints on|off or list all available
162 --hint[X]:on|off
164 turn specific hint X on|off
165 --lib:PATH
167 set the system library path
168 --import:PATH
170 add an automatically imported module
171 --include:PATH
173 add an automatically included module
174 --nimcache:PATH
176 set the path used for generated files
177 --header:FILE
179 the compiler should produce a .h file (FILE is optional)
180 -c, --compileOnly
182 compile only; do not assemble or link
183 --noLinking
185 compile but do not link
186 --noMain
188 do not generate a main procedure
189 --genScript
191 generate a compile script (in the 'nimcache' subdirectory named
192 'compile_$project$scriptext')
193 --os:SYMBOL
195 set the target operating system (cross-compilation)
196 --cpu:SYMBOL
198 set the target processor (cross-compilation)
199 --debuginfo
201 enables debug information
202 -t, --passC:OPTION
204 pass an option to the C compiler
205 -l, --passL:OPTION
207 pass an option to the linker
208 --cincludes:DIR
210 modify the C compiler header search path
211 --clibdir:DIR
213 modify the linker library search path
214 --clib:LIBNAME
216 link an additional C library (you should omit platform-specific
217 extensions)
218 --genMapping
220 generate a mapping file containing (Nim, mangled) identifier pairs
221 --project
223 document the whole project (doc2)
224 --docSeeSrcUrl:url
226 activate 'see source' for doc and doc2 commands (see
227 doc.item.seesrc in config/nimdoc.cfg)
228 --lineDir:on|off
230 generation of #line directive on|off
231 --embedsrc
233 embeds the original source code as comments in the generated output
234 --threadanalysis:on|off
236 turn thread analysis on|off
237 --tlsEmulation:on|off
239 turn thread local storage emulation on|off
240 --taintMode:on|off
242 turn taint mode on|off
243 --implicitStatic:on|off
245 turn implicit compile time evaluation on|off
246 --patterns:on|off
248 turn pattern matching on|off
249 --memTracker:on|off
251 turn memory tracker on|off
252 --excessiveStackTrace:on|off
254 stack traces use full file paths
255 --skipCfg
257 do not read the general configuration file
258 --skipUserCfg
260 do not read the user's configuration file
261 --skipParentCfg
263 do not read the parent dirs' configuration files
264 --skipProjCfg
266 do not read the project's configuration file
267 --gc:refc|v2|markAndSweep|boehm|go|none|regions
269 select the GC to use; default is refc
270 --index:on|off
272 turn index file generation on|off
273 --putenv:key=value
275 set an environment variable
276 --NimblePath:PATH
278 add a path for Nimble support
279 --noNimblePath
281 deactivate the Nimble path
282 --noCppExceptions
284 use default exception handling with C++ backend
285 --excludePath:PATH
287 exclude a path from the list of search paths
288 --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 --listCmd
295 list the commands used to execute external programs
296 --parallelBuild:0|1|...
298 perform a parallel build value = number of processors (0 for
299 auto-detect)
300 --verbosity:0|1|2|3
302 set Nim's verbosity level (1 is default)
303 --experimental
305 enable experimental language features
306 -v, --version
308 show detailed version information
309
311 Each warning can be activated individually with --warning[NAME]:on|off
312 or in a push pragma.
313 ┌──────────────────────┬─────────────────────────────────────────────────────────────────────────┐
315 │ Name │ 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 └──────────────────────┴─────────────────────────────────────────────────────────────────────────┘
334 0:
335 Minimal output level for the compiler.
336 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 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 3:
349 In addition to the previous levels dumps a debug stack trace for
350 compiler developers.
351
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 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
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 The nim executable processes configuration files in the following
369 directories (in this order; later files overwrite previous settings):
370 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 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 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 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 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 The default build of a project is a debug build. To compile a release
394 build define the release symbol:
395 nim c -d:release myproject.nim
397
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 nim dump shows the contents of the PATH.
404 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 $lib/x.nim
410 $lib/bar/x.nim
411 foo/x.nim
412 foo/main.nim
413 other.nim
414 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
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
425 ⟨https://nim-lang.org/docs/backends.html#nimcache-naming-logic⟩.
426 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
433 Warning: The compilation cache is still highly experimental!
434 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 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 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
453 To change the compiler from the default compiler (at the command line):
454 nim c --cc:llvm_gcc --compile_only myfile.nim
456 This uses the configuration defined in config\nim.cfg for llvm_gcc.
458 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 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
467 To cross compile, use for example:
468 nim c --cpu:i386 --os:linux --compileOnly --genScript myproject.nim
470 Then move the C code and the compile script compile_myproject.sh to
472 your Linux i386 machine and run the script.
473 Another way is to make Nim invoke a cross compiler toolchain:
475 nim c --cpu:arm --os:linux myproject.nim
477 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 arm.linux.gcc.path = "/usr/bin"
484 arm.linux.gcc.exe = "arm-linux-gcc"
485 arm.linux.gcc.linkerexe = "arm-linux-gcc"
486 DLL GENERATION
488 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 nim c -d:release lib/nimrtl.nim
495 To link against nimrtl.dll use the command:
497 nim c -d:useNimRtl myprog.nim
499 Note: Currently the creation of nimrtl.dll with thread support has
501 never been tested and is unlikely to work!
502
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 -d:release
509 Turns off runtime checks and turns on the optimizer.
510 -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 -d:useFork
516 Makes osproc use fork instead of posix_spawn.
517 -d:useNimRtl
519 Compile and link against nimrtl.dll.
520 -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 -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 -d:nodejs
532 The JS target is actually node.js.
533 -d:ssl
535 Enables OpenSSL support for the sockets module.
536 -d:memProfiler
538 Enables memory profiling for the native GC.
539 -d:uClibc
541 Use uClibc instead of libc. (Relevant for Unix-like OSes)
542 -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 -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 -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
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 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 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 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 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 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
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 nim c --dynlibOverride:lua --passL:liblua.lib program.nim
598
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
605 ⟨https://nim-lang.org/docs/backends.html⟩.
606
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
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
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 To make the compiler output code for a 16bit target use the --cpu:avr
625 target.
626 For example, to generate code for an AVR processor use this command:
628 nim c --cpu:avr --os:standalone --deadCodeElim:on --genScript x.nim
630 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
638 See the documentation of Nim's soft realtime GC ⟨https://nim-
639 lang.org/docs/gc.html⟩ for further information.
640
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
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 However, sometimes one has to optimize. Do it in the following order:
653 1 switch off the embedded debugger (it is slow!)
655 2 turn on the optimizer and turn off runtime checks
657 3 profile your code to find where the bottlenecks are
659 4 try to find a better algorithm
661 5 do low-level optimizations
663 This section can only help you with the last item.
665 Optimizing string handling
667 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 var s = procA() # assignment will not copy the string; procA allocates a new
676 # string already
677 However it is not efficient to do:
679 var s = varA # assignment has to copy the whole string into a new buffer!
681 For let symbols a copy is not always necessary:
683 let s = varA # may only copy a pointer if it safe to do so
685 If you know what you're doing, you can also mark single string (or
687 sequence) objects as shallow:
688 var s = "abc"
690 shallow(s) # mark 's' as shallow string
691 var x = s # now might not copy the string!
692 Usage of shallow is always safe once you know the string won't be modi‐
694 fied anymore, similar to Ruby's freeze.
695 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 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
717 Official documentation ⟨https://nim-lang.org/documentation.html⟩, nim‐
718 grep(1)
719Linux SEPTEMBER 2017 NIM(1)