Merge: Portable stack-traces

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

diff --git a/share/man/nitc.md b/share/man/nitc.md
index 75da7c8..9e0fbf5 100644 (file)
--- a/share/man/nitc.md
+++ b/share/man/nitc.md
@@ -20,7 +20,7 @@ By default, the generated executables are produced in the current directory.
 
 Internally, nitc rely on the presence of a C compiler. Usually gcc (but nitc was successfully tested with clang).
 A compilation directory is therefore created and (re-)used.
-By default, the compilation directory is named `.nit_compile`.
+By default, the compilation directory is named `nit_compile` and is removed after the compilation.
 (see `--compile-dir` for details.)
 
 Currently, because Nit is still in heavy development, the compilation directory is not cleaned after the compilation.
@@ -115,11 +115,14 @@ See the documentation of these specific modules for details.
 
 `--log`
 :   Generate various log files.
-    Currently unused.
+
+    The tool will generate some files in the logging directory (see `--log-dir`).
+    These files are intended to the advanced user and the developers of the tools.
 
 `--log-dir`
 :   Directory where to generate log files.
-    Currently unused.
+
+    By default the directory is called `logs` in the working directory.
 
 
 `-h`, `-?`, `--help`
@@ -165,7 +168,9 @@ See the documentation of these specific modules for details.
 `--compile-dir`
 :   Directory used to generate temporary files.
 
-    By default, it is named `.nit_compile`.
+    By default, it is named `nit_compile` and created in the current directory and destroyed after the compilation.
+
+    If the option `--compile_dir` or `--no-cc` is used, then the directory is not destroyed and let as is.
 
 `--no-cc`
 :   Do not invoke the C compiler.
@@ -181,6 +186,8 @@ See the documentation of these specific modules for details.
     Only the C files required for the program are generated.
     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`
 :   Additional module to mix-in.
 
@@ -353,6 +360,16 @@ Usually you do not need them since they make the generated code slower.
 `--no-shortcut-equal`
 :   Always call == in a polymorphic way.
 
+`--no-tag-primitive`
+:   Use only boxes for primitive types.
+
+The separate compiler uses tagged values to encode common primitive types like Int, Bool and Char.
+This option disables tags and forces such primitive values to be boxed.
+The drawback is that each boxing costs a memory allocation thus increases the amount of work for the garbage collector.
+
+However, in some cases, it is possible that this option improves performance since the absence of tags simplify the implementation
+of OO mechanisms like method calls or equality tests.
+
 `--no-inline-intern`
 :   Do not inline call to intern methods.
 
@@ -387,8 +404,18 @@ They are useless for a normal user.
 `--no-main`
 :   Do not generate main entry point.
 
-`--stacktrace`
-:   Control the generation of stack traces.
+`--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.
@@ -422,6 +449,11 @@ They are useless for a normal user.
 `--stub-man`
 :   Generate a stub manpage in pandoc markdown format.
 
+`--keep-going`
+:   Continue after errors, whatever the consequences.
+
+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.
+This option is used to test the robustness of the tools by allowing phases to progress on incorrect data.
 
 # ENVIRONMENT VARIABLES
 
@@ -459,6 +491,20 @@ They are useless for a normal user.
     * large: disable the GC and just allocate a large memory area to use for all instantiation.
     * help: show the list of available options.
 
+`NIT_NO_STACK`
+:   Runtime control of stack traces.
+
+    By default, stack traces are printed when a runtime errors occurs during the execution of a compiled program.
+    When setting this environment variable to a non empty value, such stack traces are disabled.
+
+    The environment variable is used when programs are executed, not when they are compiled.
+    Thus, you do not need to recompile programs in order to disable generated stack traces.
+
+    Note that stack traces require that, during the compilation, development files of the library `libunwind` are available.
+    If they are not available, then programs are compiled without any stack trace support.
+
+    To completely disable stack traces, see the option `--no-stacktrace`.
+
 # SEE ALSO
 
 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>