3 nitc - compiles Nit programs.
8 nitc [*options*] FILE...
10 nitc [*options*] --run FILE [ARG]...
15 nitc is the current official Nit compiler.
16 It takes the main module of a Nit program as argument and produces an executable file.
18 By default, the generated executables are produced in the current directory.
19 (see `--dir` for details.)
21 Internally, nitc rely on the presence of a C compiler. Usually gcc (but nitc was successfully tested with clang).
22 A compilation directory is therefore created and (re-)used.
23 By default, the compilation directory is named `nit_compile` and is removed after the compilation.
24 (see `--compile-dir` for details.)
26 Currently, because Nit is still in heavy development, the compilation directory is not cleaned after the compilation.
28 By default, the compilation process tries to have a good trade-off between the compilation time and the performance of produced executables.
29 To produce more optimized executables, the current best option is `--semi-global`.
31 To improve the compilation time and simplify the compilation of multiple programs, more than one file can be given.
32 Each one will be compiled into a distinct executable.
34 $ nitc prog1.nit prog2.nit
36 To combine files into a single program, use the `-m` option.
38 $ nitc prog1.nit -m other_module.nit
40 nitc can produces executables for various platforms when specific modules are used.
41 Currently, android and emscripten are supported.
42 See the documentation of these specific modules for details.
50 Show additional warnings (advices).
52 By default, only important warnings are displayed.
53 May be overridden by `-w`.
55 Important warnings are displayed by default. A warning is considered important when:
57 * There is a simple correction.
58 * There is no reason to let the code this way.
59 * There is always a real issue (no false positive).
61 Other warnings, called advices, are not displayed by default to avoid filling the terminal with
63 A warning is considered an advice when:
65 * The correction could be complex. e.g. require a refactorisation or an API change.
66 * The correction cannot be done. e.g. Code that use a deprecated API for some compatibility reason.
67 * There is not a real issue (false positive). Note that this should be unlikely.
68 * Transitional: While a real important warning, it fires a lot in current code, so a transition is needed
69 in order to let people fix them before promoting the advice to an important warning.
72 Show/hide a specific warning.
74 Each type of warning can be individually displayed or hidden.
75 The `-w` option takes the name of a warning (displayed at the end of the warning message, between parentheses) to activate it;
76 and "no-{name}" to disable it.
77 It has precedence over -q and -W.
78 Multiple `-w` can be given.
80 To show only `missing-doc` warnings in standard"
82 $ nitc -q -w missing-doc standard
84 To show all warnings and advices, except `missing-doc`:
86 $ nitc -W -w no-missing-doc standard
88 To show important warnings except `useless-type-test`, but not advice except `missing-doc`:
90 $ nitc -w missing-doc -w no-useless-type-test standard
94 May be overridden by `-w`
96 ### `--stop-on-first-error`
97 Just display the first encountered error then stop.
99 By default, nitc tries to detect and display more than one error before aborting the compilation.
102 Do not use color to display errors and warnings.
104 Also, do not echo the line.
105 This options is mainly used by scripts and tools that need parsable error messages.
107 ### `-v`, `--verbose`
108 Additional messages from the tool.
109 Multiple `-v` can be given to improve the verbosity.
111 With one `-v`, there is constant number of lines.
112 With two `-v`, the number of lines is proportional to the number of modules.
113 With three `-v`, the number of lines is proportional to the number of definition of classes.
114 With four `-v`, the number of lines is proportional to the number of definition of properties.
117 Generate various log files.
119 The tool will generate some files in the logging directory (see `--log-dir`).
120 These files are intended to the advanced user and the developers of the tools.
123 Directory where to generate log files.
125 By default the directory is called `logs` in the working directory.
128 ### `-h`, `-?`, `--help`
129 Show Help (the list of options).
132 Show version and exit.
138 Add an additional include path.
140 This option is used to indicate an additional path of a directory containing Nit libraries.
142 The path added with `-I` are searched before those added by the environment variable `NIT_PATH`.
144 May be used more than once.
147 Filename of the generated executable.
149 Indicates the path and name of the produced executable.
151 Note: it is better to use `--dir` if only the directory is important.
152 This way, the platform extension will be correctly set.
154 `-o` is not usable if multiple programs are compiled at once.
159 Produce the executables in the given directory instead of the current directory.
162 Base directory of the Nit installation.
164 Has precedence over the environment variable `NIT_DIR`.
169 Execute the binary after the compilation.
171 The binary is generated as expected then it is executed directly.
172 After the execution, the binary is not removed.
174 When `--run` is used, the first argument is the program to compile, the rest of the arguments are the arguments of the program.
175 Note that you MUST use `--` before the program arguments if one of them is an option starting with a `-`.
178 $ nitc --run foo.nit arg # compile foo.nit, then executes `./foo arg`
179 $ nitc --run foo.nit arg -W # compile foo.nit with warnings, then executes `./foo arg`
180 $ nitc --run foo.nit -- arg -W # compile foo.nit, then executes `./foo arg -W`
184 Directory used to generate temporary files.
186 By default, it is named `nit_compile` and created in the current directory and destroyed after the compilation.
188 If the option `--compile_dir` or `--no-cc` is used, then the directory is not destroyed and let as is.
191 Do not invoke the C compiler.
193 Files in the compilation directory are generated but the C compiler is not invoked.
195 This option is mainly used to produce C files distributable then compilable on system that do not have a Nit compiler (e.g. embedded system).
196 In this case, it is suggested to also use the options `--dir`, `--compile-dir` and `--semi-global`.
198 $ nitc examples/hello_world.nit --no-cc --dir hello --compile-dir hello --semi-global
200 Will produce a `hello` directory that contains the required C files to finish the compilation.
201 Only the C files required for the program are generated.
202 The final binary will be generated in the same directory.
204 Note that, to be useful, the compilation directory is not destroyed when `--no-cc` is used.
207 Additional module to mix-in.
209 Additional modules are imported and refine the main module of the program.
210 This has basically the same effect than implementing a specific module that imports the main module of the program then each one of the mix-in modules.
211 May be used more than once.
213 This is option is used to weave additional behaviors to existing programs.
214 Modules designated to bring features to programs by refining basic or specialized services, without any intervention of the main program, are good candidates to be used with the `-m` option.
217 An other usage of the `-m` option is to compile program to a specific platform. E.g. `emscripten` or `android`.
219 A last usage is to develop programs as product lines with a main basic module (vanilla) and specific distinct features as flavor modules, then to combine them at compile-time.
221 $ nitc prog_vanilla.nit -m feature_chocolate.nit -m feature_cherry.nit
224 Define a specific property.
226 The `-D` option allows to refine a top-level method at compile-time.
227 This has basically the same effect than implementing a specific module that imports the main module of the program and refines the designated methods.
229 The designated method must be top-level function with no parameters that returns a Bool, an Int or a String.
231 The argument of the `-D` option is "{name}={value}".
232 For Bool, the argument can also be just "{name}", in this case, the value is considered to be `true`.
234 $ nitc foo.nit -D prefix=/opt/foo -D port=8080 -D with_ssl
237 Compile in release mode and finalize application.
239 Currently, this only affect the android platform.
242 Compile in debug mode.
244 Currently removes gcc optimizations.
245 Also preserves the source-files directory for C-debuggers.
247 For more debugging-related options, see also `--hardening` and `NIT_GC_OPTION`
250 Compile with lttng's instrumentation.
252 Currently add a lttng trace provider and add tracepoint into object instances.
256 ### `nitc` includes distinct compilation modes.
259 Use separate compilation (default mode).
261 In separate compilation, modules are compiled independently of their programs.
262 This makes the recompilation of programs faster since only the modified files need to be recompiled.
265 Use global compilation.
267 The produced executables may become huge and the compilation time is prohibitive.
268 But sometime, they are faster.
270 In practice, `--semi-global` produces nearly as fast but smaller executables.
275 Like `--separate` but use an erasure dynamic typing policy for generics and virtual types.
276 Usually you do not need this, even if you understand the previous sentence.
279 ## SEMI-GLOBAL OPTIMIZATIONS
281 In `--separate` and in `--erasure` modes, some optimization can be gained by relaxing the constraint about
282 the independence on programs.
284 Therefore, with these options, the produced executables may be faster and smaller but the recompilation time
288 Enable all semi-global optimizations.
291 Activate RTA (Rapid Type Analysis).
293 This option only make sense in `--erasure` to enable some semi-global optimizations.
295 RTA is implicitly enabled in `--separate` and `--global`.
297 ### `--inline-coloring-numbers`
298 Inline colors and ids (semi-global).
300 ### `--inline-some-methods`
301 Allow the separate compiler to inline some methods (semi-global).
304 ### `--direct-call-monomorph`
305 Allow the separate compiler to direct call monomorphic sites (semi-global).
308 ### `--direct-call-monomorph0`
309 Allow the separate compiler to direct call monomorphic sites (semi-global).
312 The difference with the non-zero option is internal:
313 with this option, the monomorphism is looked-at on the mmethod level and not at the callsite level.
315 ### `--skip-dead-methods`
316 Do not compile dead methods (semi-global).
319 ## LINK-BOOST OPTIMIZATIONS
321 In `--separate` and in `--erasure` modes, some optimization can be gained by hijacking the linker process.
323 Warning: these optimisations are not portable since they use extra features of the GNU linker `ld`.
324 However, there is very few reasons to not use them if GNU `ld` is available.
327 Enable all link-boost optimizations.
329 ### `--colors-are-symbols`
330 Store colors as symbols instead of static data.
332 By default, the various identifiers used to implement OO-mechanisms are stored as genuine constant static variables.
334 This option uses linker symbols to encode these identifiers.
335 This makes the compiled program faster since less indirections are required to get the values.
336 It also produces executables that are a little bit smaller since static memory does not have to store the colors.
338 ### `--substitute-monomorph`
339 Replace monomorphic trampolines with direct calls.
341 Late-binding is implemented with *trampolines*, that are small functions that just select and jump the to right implementations.
342 If, at link-time, is it known that the target will always by the same implementation then all calls to the trampoline are replaced by
343 direct calls to this single implementation.
345 Note that using trampolines as indirection slows down the executable.
346 However, it is expected that the gain of monomorphic direct-calls overcompensates the additional indirections in polymorphic trampoline-calls.
348 Note: automatically enable option `--trampoline-call`.
350 ## POTENTIAL OPTIMIZATIONS
352 These optimisation are not enabled by default as they are counter-effective in most cases.
355 Guard VFT calls with a direct call.
358 Build a poset of types to create more condensed tables.
360 The drawback is that more time and memory are used by the compilation process.
363 ## DANGEROUS OPTIMIZATIONS
365 The following optimizations disable runtime checks.
366 It means that correct (non-buggy) programs may be slightly faster.
367 It also means that incorrect (buggy) programs may have unspecified behaviors
368 (e.g. formatting your hard drive or killing your cat).
370 In fact, these options are mainly used to bench the compilation results.
373 Disable all tests (dangerous).
375 ### `--no-check-covariance`
376 Disable type tests of covariant parameters (dangerous).
378 ### `--no-check-attr-isset`
379 Disable isset tests before each attribute access (dangerous).
381 ### `--no-check-assert`
382 Disable the evaluation of explicit `assert` and `as` (dangerous).
384 ### `--no-check-autocast`
385 Disable implicit casts on unsafe expression usage (dangerous).
387 ### `--no-check-null`
388 Disable tests of null receiver (dangerous).
390 ### `--no-check-erasure-cast`
391 Disable implicit casts on unsafe return with erasure-typing policy (dangerous).
396 These options are used to debug or to bench the compilation results.
397 Usually you do not need them since they make the generated code slower.
399 ### `--no-shortcut-range`
400 Always instantiate a range and its iterator on 'for' loops.
402 ### `--no-union-attribute`
403 Put primitive attributes in a box instead of an union.
405 ### `--no-shortcut-equal`
406 Always call == in a polymorphic way.
408 ### `--no-tag-primitives`
409 Use only boxes for primitive types.
411 The separate compiler uses tagged values to encode common primitive types like Int, Bool and Char.
412 This option disables tags and forces such primitive values to be boxed.
413 The drawback is that each boxing costs a memory allocation thus increases the amount of work for the garbage collector.
415 However, in some cases, it is possible that this option improves performance since the absence of tags simplify the implementation
416 of OO mechanisms like method calls or equality tests.
418 ### `--no-inline-intern`
419 Do not inline call to intern methods.
421 ### `--colo-dead-methods`
422 Force colorization of dead methods.
424 ### `--no-gcc-directive`
425 Disable advanced gcc directives for optimization.
427 ### `--trampoline-call`
428 Use an indirection when calling.
430 Just add the trampolines of `--substitute-monomorph` without doing any additional optimizations.
435 ### `--no-stacktrace`
436 Disable the generation of stack traces.
438 With this option, the compiled program will not display stack traces on runtime errors.
440 Because stack traces rely on libunwind, this option might be useful in order to generate more portable binaries
441 since libunwind might be non available on the runtime system (or available with an ABI incompatible version).
443 The generated C is API-portable and can be reused, distributed and compiled on any supported system.
444 If the option `--no-stacktrace` is not used but the development files of the library `libunwind` are not available, then a warning will be displayed
445 and stack trace will be disabled.
447 Note that the `--no-stacktrace` option (or this absence) can be toggled manually in the generated Makefile (search `NO_STACKTRACE` in the Makefile).
448 Moreover, the environment variable `NIT_NO_STACK` (see bellow) can also be used at runtime to disable stack traces.
451 Enable dynamic measure of memory usage.
453 Compiled programs will generate a large `memory.log` file that logs all memory allocations.
454 This logs file can then be analyzed with the tool `memplot` from contrib.
457 Generate contracts in the C code against bugs in the compiler.
462 These options can be used to control the fine behavior of the tool.
463 They are useless for a normal user.
465 ### `--disable-phase`
466 Disable a specific phase; use `list` to get the list.
469 Only proceed to parse files.
471 ### `--only-metamodel`
472 Stop after meta-model processing.
474 ### `--ignore-visibility`
475 Do not check, and produce errors, on visibility issues.
478 Do not generate main entry point.
481 Maximum number of lines in generated C files. Use 0 for unlimited.
483 ### `--group-c-files`
484 Group all generated code in the same series of files.
487 Additional options to the `make` command.
489 $ nitc foo.nit --make-flags 'CC=clang' --make-flags 'CFLAGS="-O0 -g"'
491 ### `--typing-test-metrics`
492 Enable static and dynamic count of all type tests.
494 ### `--invocation-metrics`
495 Enable static and dynamic count of all method invocations.
497 ### `--isset-checks-metrics`
498 Enable static and dynamic count of isset checks before attributes access.
500 ### `--tables-metrics`
501 Enable static size measuring of tables used for vft, typing and resolution.
503 ### `--set-dummy-tool`
504 Set toolname and version to DUMMY. Useful for testing.
506 ### `--bash-completion`
507 Generate bash_completion file for this program.
510 Generate a stub manpage in pandoc markdown format.
513 Continue after errors, whatever the consequences.
515 The tool does not stop after some errors but continue until it produces incorrect result, crashes, erases the hard drive, or just continue forever in an infinite loop.
516 This option is used to test the robustness of the tools by allowing phases to progress on incorrect data.
519 Force lazy semantic analysis of the source-code.
521 Analysis of methods is thus done only when required.
522 This option breaks the behavior of most of the tools since errors in methods are undetected until the method is required in some processing.
524 # ENVIRONMENT VARIABLES
527 Base directory of the Nit installation.
529 When the `NIT_DIR` environment variable is set then it specifies the path of the Nit install directory.
531 This directory is used to locate binaries, shared files and the common libraries.
533 When unset, the directory is guessed according to some heuristic.
535 The `--nit-dir` option also set the base directory of the Nit installation but has precedence.
538 Additional include paths.
540 The `NIT_PATH` environment variable contains paths of directories containing Nit libraries.
541 Each path is separated with a column (`:`).
543 The `-I` option also add additional paths.
546 Runtime control of the garbage collector.
548 The behavior of the GC of the executables produced by nitc can be tuned with this environment variable.
550 The environment variable is used when programs are executed, not when they are compiled.
551 Thus, you do not need to recompile programs in order to tweak their GC options.
553 Available values are:
555 * boehm: use the Boehm-Demers-Weiser's conservative garbage collector (default).
556 * malloc: disable the GC and just use `malloc` without doing any `free`.
557 * large: disable the GC and just allocate a large memory area to use for all instantiation.
558 * help: show the list of available options.
561 Runtime control of stack traces.
563 By default, stack traces are printed when a runtime errors occurs during the execution of a compiled program.
564 When setting this environment variable to a non empty value, such stack traces are disabled.
566 The environment variable is used when programs are executed, not when they are compiled.
567 Thus, you do not need to recompile programs in order to disable generated stack traces.
569 Note that stack traces require that, during the compilation, development files of the library `libunwind` are available.
570 If they are not available, then programs are compiled without any stack trace support.
572 To completely disable stack traces, see the option `--no-stacktrace`.
576 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>
nitlanguage / nit.git / blob