X-Git-Url: http://nitlanguage.org diff --git a/share/man/nitc.md b/share/man/nitc.md index 4d703e9..c241573 100644 --- a/share/man/nitc.md +++ b/share/man/nitc.md @@ -7,6 +7,8 @@ nitc - compiles Nit programs. nitc [*options*] FILE... +nitc [*options*] --run FILE [ARG]... + # DESCRIPTION @@ -45,7 +47,6 @@ See the documentation of these specific modules for details. ## MESSAGES ### `-W`, `--warn` - Show additional warnings (advices). By default, only important warnings are displayed. @@ -68,7 +69,6 @@ A warning is considered an advice when: in order to let people fix them before promoting the advice to an important warning. ### `-w`, `--warning` - Show/hide a specific warning. Each type of warning can be individually displayed or hidden. @@ -144,14 +144,14 @@ The path added with `-I` are searched before those added by the environment vari May be used more than once. ### `-o`, `--output` -Output executable name. +Filename of the generated executable. Indicates the path and name of the produced executable. Note: it is better to use `--dir` if only the directory is important. This way, the platform extension will be correctly set. -### `-o` is not usable if multiple programs are compiled at once. +`-o` is not usable if multiple programs are compiled at once. ### `--dir` Output directory. @@ -165,6 +165,21 @@ Has precedence over the environment variable `NIT_DIR`. ## COMPILATION +### `--run` +Execute the binary after the compilation. + +The binary is generated as expected then it is executed directly. +After the execution, the binary is not removed. + +When `--run` is used, the first argument is the program to compile, the rest of the arguments are the arguments of the program. +Note that you MUST use `--` before the program arguments if one of them is an option starting with a `-`. + +~~~bash +$ nitc --run foo.nit arg # compile foo.nit, then executes `./foo arg` +$ nitc --run foo.nit arg -W # compile foo.nit with warnings, then executes `./foo arg` +$ nitc --run foo.nit -- arg -W # compile foo.nit, then executes `./foo arg -W` +~~~ + ### `--compile-dir` Directory used to generate temporary files. @@ -188,7 +203,7 @@ The final binary will be generated in the same directory. Note that, to be useful, the compilation directory is not destroyed when `--no-cc` is used. -### `-m` +### `-m`, `--mixin` Additional module to mix-in. Additional modules are imported and refine the main module of the program. @@ -316,7 +331,7 @@ This makes the compiled program faster since less indirections are required to g It also produces executables that are a little bit smaller since static memory does not have to store the colors. ### `--substitute-monomorph` -Replace monomorphic trampolines with direct call. +Replace monomorphic trampolines with direct calls. Late-binding is implemented with *trampolines*, that are small functions that just select and jump the to right implementations. 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 @@ -376,9 +391,6 @@ Disable implicit casts on unsafe return with erasure-typing policy (dangerous). These options are used to debug or to bench the compilation results. Usually you do not need them since they make the generated code slower. -### `--hardening` -Generate contracts in the C code against bugs in the compiler. - ### `--no-shortcut-range` Always instantiate a range and its iterator on 'for' loops. @@ -388,7 +400,7 @@ Put primitive attributes in a box instead of an union. ### `--no-shortcut-equal` Always call == in a polymorphic way. -### `--no-tag-primitive` +### `--no-tag-primitives` Use only boxes for primitive types. The separate compiler uses tagged values to encode common primitive types like Int, Bool and Char. @@ -410,10 +422,35 @@ Disable advanced gcc directives for optimization. ### `--trampoline-call` Use an indirection when calling. -Just add the trampolines of `--substitute-monomorph` without doing any aditionnal optimizations. +Just add the trampolines of `--substitute-monomorph` without doing any additional optimizations. + + +### DEBUGGING + +### `--no-stacktrace` +Disable the generation of stack traces. + +With this option, the compiled program will not display stack traces on runtime errors. + +Because stack traces rely on libunwind, this option might be useful in order to generate more portable binaries +since libunwind might be non available on the runtime system (or available with an ABI incompatible version). + +The generated C is API-portable and can be reused, distributed and compiled on any supported system. +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 +and stack trace will be disabled. + +Note that the `--no-stacktrace` option (or this absence) can be toggled manually in the generated Makefile (search `NO_STACKTRACE` in the Makefile). +Moreover, the environment variable `NIT_NO_STACK` (see bellow) can also be used at runtime to disable stack traces. + +### `--trace-memory` +Enable dynamic measure of memory usage. + +Compiled programs will generate a large `memory.log` file that logs all memory allocations. +This logs file can then be analyzed with the tool `memplot` from contrib. + +### `--hardening` +Generate contracts in the C code against bugs in the compiler. -### `--no-tag-primitives` -Use only boxes for primitive types. ## INTERNAL OPTIONS @@ -435,19 +472,6 @@ Do not check, and produce errors, on visibility issues. ### `--no-main` Do not generate main entry point. -### `--no-stacktrace` -The compiled program will not display stack traces on runtime errors. - -Because stack traces rely on libunwind, this option might be useful in order to generate more portable binaries -since libunwind might be non available on the runtime system (or available with an ABI incompatible version). - -The generated C is API-portable and can be reused, distributed and compiled on any supported system. -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 -and stack trace will be disabled. - -Note that the `--no-stacktrace` option (or this absence) can be toggled manually in the generated Makefile (search `NO_STACKTRACE` in the Makefile). -Moreover, the environment variable `NIT_NO_STACK` (see bellow) can also be used at runtime to disable stack traces. - ### `--max-c-lines` Maximum number of lines in generated C files. Use 0 for unlimited.