add the trace system with a first test which is instance tracing

[nit.git] / share / man / nitc.md

diff --git a/share/man/nitc.md b/share/man/nitc.md
index a316782..d29a131 100644 (file)
--- 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,11 @@ 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.
+
 ## COMPILATION MODES
 
 ### `nitc` includes distinct compilation modes.
@@ -374,9 +396,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.
 
@@ -408,7 +427,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.
+
 
 ## INTERNAL OPTIONS
 
@@ -430,21 +477,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.