share/man/nitc.md

   1 % NITG(1)
   2
   3 # NAME
   4
   5 nitc - compiles Nit programs.
   6
   7
   8 # SYNOPSIS
   9
  10 nitc [*options*] FILE...
  11
  12
  13 # DESCRIPTION
  14
  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.
  17
  18 By default, the generated executables are produced in the current directory.
  19 (see `--dir` for details.)
  20
  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`.
  24 (see `--compile-dir` for details.)
  25
  26 Currently, because Nit is still in heavy development, the compilation directory is not cleaned after the compilation.
  27
  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`.
  30
  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.
  33
  34     $ nitc prog1.nit prog2.nit
  35
  36 To combine files into a single program, use the `-m` option.
  37
  38     $ nitc prog1.nit -m other_module.nit
  39
  40 nitc can produces executables for various platforms when specific modules are used.
  41 Currently, android, pnacl and emscripten are supported.
  42 See the documentation of these specific modules for details.
  43
  44
  45 # OPTIONS
  46
  47 ## MESSAGES
  48
  49 `-W`, `--warn`
  50 :   Show additional warnings (advices).
  51
  52     By default, only important warnings are displayed.
  53     May be overridden by `-w`.
  54
  55     Important warnings are displayed by default. A warning is considered important when:
  56
  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).
  60
  61     Other warnings, called advices, are not displayed by default to avoid filling the terminal with
  62     unwanted information.
  63     A warning is considered an advice when:
  64
  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.
  70
  71 `-w`, `--warning`
  72 :   Show/hide a specific warning.
  73
  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.
  79
  80     To show only `missing-doc` warnings in standard"
  81
  82         $ nitc -q -w missing-doc standard
  83
  84     To show all warnings and advices, except `missing-doc`:
  85
  86         $ nitc -W -w no-missing-doc standard
  87
  88     To show important warnings except `useless-type-test`, but not advice except `missing-doc`:
  89
  90         $ nitc -w missing-doc -w no-useless-type-test standard
  91
  92 `-q`, `--quiet`
  93 :   Do not show warnings.
  94     May be overridden by `-w`
  95
  96 `--stop-on-first-error`
  97 :   Just display the first encountered error then stop.
  98
  99     By default, nitc tries to detect and display more than one error before aborting the compilation.
 100
 101 `--no-color`
 102 :   Do not use color to display errors and warnings.
 103
 104     Also, do not echo the line.
 105     This options is mainly used by scripts and tools that need parsable error messages.
 106
 107 `-v`, `--verbose`
 108 :   Additional messages from the tool.
 109     Multiple `-v` can be given to improve the verbosity.
 110
 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.
 115
 116 `--log`
 117 :   Generate various log files.
 118
 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.
 121
 122 `--log-dir`
 123 :   Directory where to generate log files.
 124
 125     By default the directory is called `logs` in the working directory.
 126
 127
 128 `-h`, `-?`, `--help`
 129 :   Show Help (the list of options).
 130
 131 `--version`
 132 :   Show version and exit.
 133
 134
 135 ## PATHS
 136
 137 `-I`, `--path`
 138 :   Add an additional include path.
 139
 140     This option is used to indicate an additional path of a directory containing Nit libraries.
 141
 142     The path added with `-I` are searched before those added by the environment variable `NIT_PATH`.
 143
 144     May be used more than once.
 145
 146 `-o`, `--output`
 147 :   Output executable name.
 148
 149     Indicates the path and name of the produced executable.
 150
 151     Note: it is better to use `--dir` if only the directory is important.
 152     This way, the platform extension will be correctly set.
 153
 154     `-o` is not usable if multiple programs are compiled at once.
 155
 156 `--dir`
 157 :   Output directory.
 158
 159     Produce the executables in the given directory instead of the current directory.
 160
 161 `--nit-dir`
 162 :   Base directory of the Nit installation.
 163
 164     Has precedence over the environment variable `NIT_DIR`.
 165
 166 ## COMPILATION
 167
 168 `--compile-dir`
 169 :   Directory used to generate temporary files.
 170
 171     By default, it is named `.nit_compile`.
 172
 173 `--no-cc`
 174 :   Do not invoke the C compiler.
 175
 176     Files in the compilation directory are generated but the C compiler is not invoked.
 177
 178     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).
 179     In this case, it is suggested to also use the options `--dir`, `--compile-dir` and `--semi-global`.
 180
 181         $ nitc examples/hello_world.nit --no-cc --dir hello --compile-dir hello --semi-global
 182
 183     Will produce a `hello` directory that contains the required C files to finish the compilation.
 184     Only the C files required for the program are generated.
 185     The final binary will be generated in the same directory.
 186
 187 `-m`
 188 :   Additional module to mix-in.
 189
 190     Additional modules are imported and refine the main module of the program.
 191     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.
 192     May be used more than once.
 193
 194     This is option is used to weave additional behaviors to existing programs.
 195     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.
 196     E.g. `hash_debug`.
 197
 198     An other usage of the `-m` option is to compile program to a specific platform. E.g. `emscripten`  or `android`.
 199
 200     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.
 201
 202         $ nitc prog_vanilla.nit -m feature_chocolate.nit -m feature_cherry.nit
 203
 204 `-D`, `--define`
 205 :   Define a specific property.
 206
 207     The `-D` option allows to refine a top-level method at compile-time.
 208     This has basically the same effect than implementing a specific module that imports the main module of the program and refines the designated methods.
 209
 210     The designated method must be top-level function with no parameters that returns a Bool, an Int or a String.
 211
 212     The argument of the `-D` option is "{name}={value}".
 213     For Bool, the argument can also be just "{name}", in this case, the value is considered to be `true`.
 214
 215         $ nitc foo.nit -D prefix=/opt/foo -D port=8080 -D with_ssl
 216
 217 `--release`
 218 :   Compile in release mode and finalize application.
 219
 220     Currently, this only affect the android platform.
 221
 222 ## COMPILATION MODES
 223
 224 `nitc` includes distinct compilation modes.
 225
 226 `--separate`
 227 :   Use separate compilation (default mode).
 228
 229     In separate compilation, modules are compiled independently of their programs.
 230     This makes the recompilation of programs faster since only the modified files need to be recompiled.
 231
 232 `--global`
 233 :   Use global compilation.
 234
 235     The produced executables may become huge and the compilation time is prohibitive.
 236     But sometime, they are faster.
 237
 238     In practice, `--semi-global` produces nearly as fast but smaller executables.
 239
 240 `--erasure`
 241 :   Erase generic types.
 242
 243     Like `--separate` but use an erasure dynamic typing policy for generics and virtual types.
 244     Usually you do not need this, even if you understand the previous sentence.
 245
 246
 247 ## SEMI-GLOBAL OPTIMIZATIONS
 248
 249 In `--separate` and in `--erasure` modes, some optimization can be gained by relaxing the constraint about
 250 the independence on programs.
 251
 252 Therefore, with these options, the produced executables may be faster and smaller but the recompilation time
 253 will increase.
 254
 255 `--semi-global`
 256 :   Enable all semi-global optimizations.
 257
 258 `--rta`
 259 :   Activate RTA (Rapid Type Analysis).
 260
 261     This option only make sense in `--erasure` to enable some semi-global optimizations.
 262
 263     RTA is implicitly enabled in `--separate` and `--global`.
 264
 265 `--inline-coloring-numbers`
 266 :   Inline colors and ids (semi-global).
 267
 268 `--inline-some-methods`
 269 :   Allow the separate compiler to inline some methods (semi-global).
 270     Need `--rta`.
 271
 272 `--direct-call-monomorph`
 273 :   Allow the separate compiler to direct call monomorphic sites (semi-global).
 274     Need `--rta`.
 275
 276 `--skip-dead-methods`
 277 :   Do not compile dead methods (semi-global).
 278     Need `--rta`.
 279
 280 ## LINK-BOOST OPTIMIZATIONS
 281
 282 In `--separate` and in `--erasure` modes, some optimization can be gained by hijacking the linker process.
 283
 284 Warning: these optimisations are not portable since they use extra features of the GNU linker `ld`.
 285 However, there is very few reasons to not use them if GNU `ld` is available.
 286
 287 `--link-boost`
 288 :   Enable all link-boost optimizations.
 289
 290 `--colors-are-symbols`
 291 :   Store colors as symbols instead of static data.
 292
 293     By default, the various identifiers used to implement OO-mechanisms are stored as genuine constant static variables.
 294
 295     This option uses linker symbols to encode these identifiers.
 296     This makes the compiled program faster since less indirections are required to get the values.
 297     It also produces executables that are a little bit smaller since static memory does not have to store the colors.
 298
 299 `--substitute-monomorph`
 300 :   Replace monomorphic trampolines with direct call.
 301
 302     Late-binding is implemented with *trampolines*, that are small functions that just select and jump the to right implementations.
 303     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
 304     direct calls to this single implementation.
 305
 306     Note that using trampolines as indirection slows down the executable.
 307     However, it is expected that the gain of monomorphic direct-calls overcompensates the additional indirections in polymorphic trampoline-calls.
 308
 309     Note: automatically enable option `--trampoline-call`.
 310
 311 ## DANGEROUS OPTIMIZATIONS
 312
 313 The following optimizations disable runtime checks.
 314 It means that correct (non-buggy) programs may be slightly faster.
 315 It also means that incorrect (buggy) programs may have unspecified behaviors
 316 (e.g. formatting your hard drive or killing your cat).
 317
 318 In fact, these options are mainly used to bench the compilation results.
 319
 320 `--no-check-all`
 321 :   Disable all tests (dangerous).
 322
 323 `--no-check-covariance`
 324 :   Disable type tests of covariant parameters (dangerous).
 325
 326 `--no-check-attr-isset`
 327 :   Disable isset tests before each attribute access (dangerous).
 328
 329 `--no-check-assert`
 330 :   Disable the evaluation of explicit `assert` and `as` (dangerous).
 331
 332 `--no-check-autocast`
 333 :   Disable implicit casts on unsafe expression usage (dangerous).
 334
 335 `--no-check-null`
 336 :   Disable tests of null receiver (dangerous).
 337
 338 `--no-check-erasure-cast`
 339 :   Disable implicit casts on unsafe return with erasure-typing policy (dangerous).
 340
 341
 342 ## UNOPTIMIZATIONS
 343
 344 These options are used to debug or to bench the compilation results.
 345 Usually you do not need them since they make the generated code slower.
 346
 347 `--hardening`
 348 :   Generate contracts in the C code against bugs in the compiler.
 349
 350 `--no-shortcut-range`
 351 :   Always instantiate a range and its iterator on 'for' loops.
 352
 353 `--no-union-attribute`
 354 :   Put primitive attributes in a box instead of an union.
 355
 356 `--no-shortcut-equal`
 357 :   Always call == in a polymorphic way.
 358
 359 `--no-tag-primitive`
 360 :   Use only boxes for primitive types.
 361
 362 The separate compiler uses tagged values to encode common primitive types like Int, Bool and Char.
 363 This option disables tags and forces such primitive values to be boxed.
 364 The drawback is that each boxing costs a memory allocation thus increases the amount of work for the garbage collector.
 365
 366 However, in some cases, it is possible that this option improves performance since the absence of tags simplify the implementation
 367 of OO mechanisms like method calls or equality tests.
 368
 369 `--no-inline-intern`
 370 :   Do not inline call to intern methods.
 371
 372 `--colo-dead-methods`
 373 :   Force colorization of dead methods.
 374
 375 `--no-gcc-directive`
 376 :   Disable advanced gcc directives for optimization.
 377
 378 `--trampoline-call`
 379 :   Use an indirection when calling.
 380
 381     Just add the trampolines of `--substitute-monomorph` without doing any aditionnal optimizations.
 382
 383 ## INTERNAL OPTIONS
 384
 385 These options can be used to control the fine behavior of the tool.
 386 They are useless for a normal user.
 387
 388 `--disable-phase`
 389 :   Disable a specific phase; use `list` to get the list.
 390
 391 `--only-parse`
 392 :   Only proceed to parse files.
 393
 394 `--only-metamodel`
 395 :   Stop after meta-model processing.
 396
 397 `--ignore-visibility`
 398 :   Do not check, and produce errors, on visibility issues.
 399
 400 `--no-main`
 401 :   Do not generate main entry point.
 402
 403 `--no-stacktrace`
 404 :   The compiled program will not display stack traces on runtime errors.
 405
 406     Because stack traces rely on libunwind, this option might be useful in order to generate more portable binaries
 407     since libunwind might be non available on the runtime system (or available with an ABI incompatible version).
 408
 409     The generated C is API-portable and can be reused, distributed and compiled on any supported system.
 410     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
 411     and stack trace will be disabled.
 412
 413     Note that the `--no-stacktrace` option (or this absence) can be toggled manually in the generated Makefile (search `NO_STACKTRACE` in the Makefile).
 414     Moreover, the environment variable `NIT_NO_STACK` (see bellow) can also be used at runtime to disable stack traces.
 415
 416 `--max-c-lines`
 417 :   Maximum number of lines in generated C files. Use 0 for unlimited.
 418
 419 `--group-c-files`
 420 :   Group all generated code in the same series of files.
 421
 422 `--make-flags`
 423 :   Additional options to the `make` command.
 424
 425           $ nitc foo.nit --make-flags 'CC=clang' --make-flags 'CFLAGS="-O0 -g"'
 426
 427 `--typing-test-metrics`
 428 :   Enable static and dynamic count of all type tests.
 429
 430 `--invocation-metrics`
 431 :   Enable static and dynamic count of all method invocations.
 432
 433 `--isset-checks-metrics`
 434 :   Enable static and dynamic count of isset checks before attributes access.
 435
 436 `--tables-metrics`
 437 :   Enable static size measuring of tables used for vft, typing and resolution.
 438
 439 `--set-dummy-tool`
 440 :   Set toolname and version to DUMMY. Useful for testing.
 441
 442 `--bash-completion`
 443 :   Generate bash_completion file for this program.
 444
 445 `--stub-man`
 446 :   Generate a stub manpage in pandoc markdown format.
 447
 448 `--keep-going`
 449 :   Continue after errors, whatever the consequences.
 450
 451 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.
 452 This option is used to test the robustness of the tools by allowing phases to progress on incorrect data.
 453
 454 # ENVIRONMENT VARIABLES
 455
 456 `NIT_DIR`
 457 :   Base directory of the Nit installation.
 458
 459     When the `NIT_DIR` environment variable is set then it specifies the path of the Nit install directory.
 460
 461     This directory is used to locate binaries, shared files and the common libraries.
 462
 463     When unset, the directory is guessed according to some heuristic.
 464
 465     The `--nit-dir` option also set the base directory of the Nit installation but has precedence.
 466
 467 `NIT_PATH`
 468 :   Additional include paths.
 469
 470     The `NIT_PATH` environment variable contains paths of directories containing Nit libraries.
 471     Each path is separated with a column (`:`).
 472
 473     The `-I` option also add additional paths.
 474
 475 `NIT_GC_OPTION`
 476 :   Runtime control of the garbage collector.
 477
 478     The behavior of the GC of the executables produced by nitc can be tuned with this environment variable.
 479
 480     The environment variable is used when programs are executed, not when they are compiled.
 481     Thus, you do not need to recompile programs in order to tweak their GC options.
 482
 483     Available values are:
 484
 485     * boehm: use the Boehm-Demers-Weiser's conservative garbage collector (default).
 486     * malloc: disable the GC and just use `malloc` without doing any `free`.
 487     * large: disable the GC and just allocate a large memory area to use for all instantiation.
 488     * help: show the list of available options.
 489
 490 `NIT_NO_STACK`
 491 :   Runtime control of stack traces.
 492
 493     By default, stack traces are printed when a runtime errors occurs during the execution of a compiled program.
 494     When setting this environment variable to a non empty value, such stack traces are disabled.
 495
 496     The environment variable is used when programs are executed, not when they are compiled.
 497     Thus, you do not need to recompile programs in order to disable generated stack traces.
 498
 499     Note that stack traces require that, during the compilation, development files of the library `libunwind` are available.
 500     If they are not available, then programs are compiled without any stack trace support.
 501
 502     To completely disable stack traces, see the option `--no-stacktrace`.
 503
 504 # SEE ALSO
 505
 506 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>