5 nitg --- compiles Nit programs.
10 nitg [*options*] FILE...
15 nitg 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, nitg rely on the presence of a C compiler. Usually gcc (but nitg 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`.
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 To combine files into a single program, use the `-m` option.
36 nitg can produces executables for various platforms when specific modules are used.
37 Currently, android, pnacl and emscripten are supported.
38 See the documentation of these specific modules for details.
46 : Show additional warnings (advices).
48 By default, only important warnings are displayed.
49 May be overridden by `-w`.
51 Important warnings are displayed by default. A warning is considered important when:
53 * There is a simple correction.
54 * There is no reason to let the code this way.
55 * There is always a real issue (no false positive).
57 Other warnings, called advices, are not displayed by default to avoid filling the terminal with
59 A warning is considered an advice when:
61 * The correction could be complex. e.g. require a refactorisation or an API change.
62 * The correction cannot be done. e.g. Code that use a deprecated API for some compatibility reason.
63 * There is not a real issue (false positive). Note that this should be unlikely.
64 * Transitional: While a real important warning, it fires a lot in current code, so a transition is needed
65 in order to let people fix them before promoting the advice to an important warning.
68 : Show/hide a specific warning.
70 Each type of warning can be individually displayed or hidden.
71 The `-w` option takes the name of a warning (displayed at the end of the warning message, between parentheses) to activate it;
72 and "no-{name}" to disable it.
73 It has precedence over -q and -W.
74 Multiple `-w` can be given.
76 To show only `missing-doc` warnings in standard"
78 $ nitg -q -w missing-doc standard
80 To show all warnings and advices, except `missing-doc`:
82 $ nitg -W -w no-missing-doc standard
84 To show important warnings except `useless-type-test`, but not advice except `missing-doc`:
86 $ nitg -w missing-doc -w no-useless-type-test standard
89 : Do not show warnings.
90 May be overridden by `-w`
92 `--stop-on-first-error`
93 : Just display the first encountered error then stop.
95 By default, nitg tries to detect and display more than one error before aborting the compilation.
98 : Do not use color to display errors and warnings.
100 Also, do not echo the line.
101 This options is mainly used by scripts and tools that need parsable error messages.
104 : Additional messages from the tool.
105 Multiple `-v` can be given to improve the verbosity.
107 With one `-v`, there is constant number of lines.
108 With two `-v`, the number of lines is proportional to the number of modules.
109 With three `-v`, the number of lines is proportional to the number of definition of properties.
112 : Generate various log files.
116 : Directory where to generate log files.
121 : Show Help (the list of options).
124 : Show version and exit.
130 : Add an include path.
132 This option is used to indicate an additional path of a directory containing Nit libraries.
134 The path added with `-I` are searched before those added by the environment variable `NIT_PATH`.
136 May be used more than once.
139 : Output executable name.
141 Indicates the path and name of the produced executable.
143 Note: it is better to use `--dir` if only the directory is important.
144 This way, the platform extension will be correctly set.
146 `-o` is not available if multiple programs are compiled at once.
151 Produce the executables in the given directory instead of the current directory.
157 : Directory used to generate temporary files.
159 By default, it is named `.nit_compile`.
162 : Do not invoke the C compiler.
164 Files in the compilation directory are generated but the C compiler is not invoked.
166 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).
167 In this case, it is suggested to also use the options `--dir`, `--compile-dir` and `--semi-global`.
169 $ nitg examples/hello_world.nit --no-cc --dir hello --compile-dir hello --semi-global
171 Will produce a `hello` directory that contains the required C files to finish the compilation.
172 Only the C files required for the program are generated.
173 The final binary will be generated in the same directory.
176 : Additional module to mix-in.
178 Additional modules are imported and refine the main module of the program.
179 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.
180 May be used more than once.
182 This is option is used to weave additional behaviors to existing programs.
183 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.
186 An other usage of the `-m` option is to compile program to a specific platform. E.g. `emscripten` or `android`.
188 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.
190 $ nitg prog_vanilla.nit -m feature_chocolate.nit -m feature_cherry.nit
193 : Define a specific property.
195 The `-D` option allows to refine a top-level method at compile-time.
196 This has basically the same effect than implementing a specific module that imports the main module of the program and refines the designated methods.
198 The designated method must be top-level function with no parameters that returns a Bool, an Int or a String.
200 The argument of the `-D` option is "{name}={value}".
201 For Bool, the argument can also be just "{name}", in this case, the value is considered to be `true`.
203 $ nitg foo.nit -D prefix=/opt/foo -D port=8080 -D with_ssl
206 : Compile in release mode and finalize application.
208 Currently, this only affect the android platform.
212 `nitg` includes distinct compilation modes.
215 : Use separate compilation (default mode).
217 In separate compilation, modules are compiled independently of their programs.
218 This makes the recompilation of programs faster since only the modified files need to be recompiled.
221 : Use global compilation.
223 The produced executables may become huge and the compilation time is prohibitive.
224 But sometime, they are faster.
226 In practice, `--semi-global` produces nearly as fast but smaller executables.
229 : Erase generic types.
231 Like `--separate` but use an erasure dynamic typing policy for generics and virtual types.
232 Usually you do not need this, even if you understand the previous sentence.
235 ## SEMI-GLOBAL OPTIMIZATIONS
237 In `--separate` and in `--erasure` modes, some optimization can be gained by relaxing the constraint about
238 the independence on programs.
240 Therefore, with these options, the produced executables may be faster and smaller but the recompilation time
244 : Enable all semi-global optimizations.
247 : Activate RTA (Rapid Type Analysis).
249 This option only make sense in `--erasure` to enable some semi-global optimizations.
251 RTA is implicitly enabled in `--separate` and `--global`.
253 `--inline-coloring-numbers`
254 : Inline colors and ids (semi-global).
256 `--inline-some-methods`
257 : Allow the separate compiler to inline some methods (semi-global).
260 `--direct-call-monomorph`
261 : Allow the separate compiler to direct call monomorphic sites (semi-global).
264 `--skip-dead-methods`
265 : Do not compile dead methods (semi-global)
269 ## DANGEROUS OPTIMIZATIONS
271 The following optimizations disable runtime checks.
272 It means that correct (non-buggy) programs may be slightly faster.
273 It also means that incorrect (buggy) programs may have unspecified behaviors
274 (e.g. formatting your hard drive or killing your cat).
276 In fact, these options are mainly used to bench the compilation results.
279 : Disable all tests (dangerous).
281 `--no-check-covariance`
282 : Disable type tests of covariant parameters (dangerous).
284 `--no-check-attr-isset`
285 : Disable isset tests before each attribute access (dangerous).
288 : Disable the evaluation of explicit `assert` and `as` (dangerous).
290 `--no-check-autocast`
291 : Disable implicit casts on unsafe expression usage (dangerous).
294 : Disable tests of null receiver (dangerous).
296 `--no-check-erasure-cast`
297 : Disable implicit casts on unsafe return with erasure-typing policy (dangerous).
302 These options are used to debug or to bench the compilation results.
303 Usually you do not need them since they make the generated code slower.
306 : Generate contracts in the C code against bugs in the compiler.
308 `--no-shortcut-range`
309 : Always instantiate a range and its iterator on 'for' loops.
311 `--no-union-attribute`
312 : Put primitive attributes in a box instead of an union.
314 `--no-shortcut-equal`
315 : Always call == in a polymorphic way.
318 : Do not inline call to intern methods.
320 `--colo-dead-methods`
321 : Force colorization of dead methods.
324 : Disable advanced gcc directives for optimization.
329 These options can be used to control the fine behavior of the tool.
330 They are useless for a normal user.
333 : Disable a specific phase; use `list` to get the list.
336 : Only proceed to parse files.
339 : Stop after meta-model processing.
341 `--ignore-visibility`
342 : Do not check, and produce errors, on visibility issues.
345 : Do not generate main entry point.
348 : Control the generation of stack traces.
351 : Maximum number of lines in generated C files. Use 0 for unlimited.
354 : Group all generated code in the same series of files.
357 : Additional options to the `make` command.
359 $ nitg foo.nit --make-flags 'CC=clang' --make-flags 'CFLAGS="-O0 -g"'
361 `--typing-test-metrics`
362 : Enable static and dynamic count of all type tests.
364 `--invocation-metrics`
365 : Enable static and dynamic count of all method invocations.
367 `--isset-checks-metrics`
368 : Enable static and dynamic count of isset checks before attributes access.
371 : Enable static size measuring of tables used for vft, typing and resolution.
374 : Set toolname and version to DUMMY. Useful for testing.
377 : Generate bash_completion file for this program.
380 : Generate a stub manpage in pandoc markdown format.
383 # ENVIRONMENT VARIABLES
386 : Nit install directory.
388 When the `NIT_DIR` environment variable is set then it specifies the path of the Nit install directory.
390 This directory is used to locate binaries, shared files and the common libraries.
392 When unset, the directory is guessed according to some heuristic.
395 : Additional include paths.
397 The `NIT_PATH` environment variable contains paths of directories containing Nit libraries.
398 Each path is separated with a column (`:`).
400 The `-I` option also add additional paths.
403 : Runtime control of the garbage collector.
405 The behavior of the GC of the executables produced by nitg can be tuned with this environment variable.
407 The environment variable is used when programs are executed, not when they are compiled.
408 Thus, you do not need to recompile programs in order to tweak their GC options.
410 Available values are:
412 * boehm: use the Boehm-Demers-Weiser's conservative garbage collector (default).
413 * malloc: disable the GC and just use `malloc` without doing any `free`.
414 * large: disable the GC and just allocate a large memory area to use for all instantiation.
415 * help: show the list of available options.
419 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>
nitlanguage / nit.git / blob