X-Git-Url: http://nitlanguage.org diff --git a/share/man/nitc.md b/share/man/nitc.md index 2927a24..eff6232 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 @@ -36,7 +38,7 @@ To combine files into a single program, use the `-m` option. $ nitc prog1.nit -m other_module.nit nitc can produces executables for various platforms when specific modules are used. -Currently, android, pnacl and emscripten are supported. +Currently, android and emscripten are supported. See the documentation of these specific modules for details. @@ -163,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. @@ -229,6 +246,29 @@ Also preserves the source-files directory for C-debuggers. For more debugging-related options, see also `--hardening` and `NIT_GC_OPTION` +### `--trace` +Compile with lttng's instrumentation. + +Currently add a lttng trace provider and add tracepoint into object instances and destructions. + +The lttng nit/misc/Nit_Compiler.lttng file is a template that you can use instead of configure channels by yourself. You have to configure the path of the destination tracefile. "your path" + +To create a channel with template : + lttng-sessiond --daemonize + lttng load -i=~/nit/misc/Nit_Compiler.lttng Nit_Compiler +To create a channel without template : + lttng create session_name + lttng enable-event --userspace Nit_Compiler:Object_Instance + lttng enable-event --userspace Nit_Compiler:Object_Destroy +To record some traces : + lttng start + --> run your program + lttng stop +To read some traces : + babeltrace ~/session_name +To destroy your current tracing session : + lttng destroy + ## COMPILATION MODES ### `nitc` includes distinct compilation modes. @@ -374,9 +414,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. @@ -386,7 +423,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. @@ -408,10 +445,35 @@ Disable advanced gcc directives for optimization. ### `--trampoline-call` Use an indirection when calling. -Just add the trampolines of `--substitute-monomorph` without doing any additionnal 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 @@ -433,21 +495,6 @@ Do not check, and produce errors, on visibility issues. ### `--no-main` Do not generate main entry point. -### `--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. - ### `--max-c-lines` Maximum number of lines in generated C files. Use 0 for unlimited.