.. _best-practices-error-warning-messaging:

===========================================
How To Generate Warnings And Error Messages
===========================================

--print-callstack-on-error
--------------------------

The option ``--print-callstack-on-error`` makes the compiler print the
complete (compile-time) call chain at the point an error or warning is
issued. This may be useful because the cause of the issue may not be
at the location reported in the warning/error.


In Chapel code
--------------

* **compile-time** - use these functions:

      ``compilerWarning()`` - reports a "warning"

      ``compilerError()``   - reports an "error" and halts compilation

  - Arguments: any number of strings known at compile time(e.g. literals or params).

  - Compile-time-known control flow (e.g. 'if' on a param boolean expression) can be used to guard when they are issued.

  - Advanced: if the last argument is an int, it is the `errorDepth`: the error is reported as if it is in the function that deep in the Chapel call stack (not counting those in internal modules or generated by the compiler). 0 is for the location of the call to compilerWarning/Error itself. The default is 1.

    (Note: as of this writing, this will not necessarily work. Use ``--print-callstack-on-error`` if needed.)

  - These are defined in ``modules/internal/ChapelBase.chpl`` and also presented in the language spec.

* **run-time** - use these functions:

      ``halt()``       - unconditional error

      ``assert(test)`` - assertion

  - Both functions accept an arbitrary number of additional arguments,
    which are printed as part of the error message.
    
    ``(modules/standard/ChapelIO.chpl)``


In the runtime library
----------------------

* Respond to the user's erroneous actions:

  ::

      chpl_warning(const char* message, int32_t lineno, chpl_string filename)

      chpl_error(const char* message, int32_t lineno, chpl_string filename)

* Indicate an issue with the library code itself:

  ::
      
   chpl_internal_error(const char* message)

* (See ``runtime/src/error.c``.)


In the compiler
---------------

* Respond to the user's actions/errors:

      ``USR_PRINT`` - information message
      
      ``USR_WARN``  - warning
      
      ``USR_FATAL`` - error, abort compilation
      
      ``USR_FATAL_CONT``  - error, abort compilation at the end of the current pass (or upon a call to ``USR_STOP``)

* Issues with the compiler code itself (internal errors):

      ``INT_FATAL`` - error, abort compilation

      ``INT_ASSERT`` - an assertion

  Between these two, ``INT_FATAL`` is unconditional whereas ``INT_ASSERT`` fires only if its sole argument is false.

  Also, ``INT_ASSERT`` is intended to become a no-op in production builds of the compiler, whereas ``INT_FATAL`` will be in effect in any build.

* Each of the above macros (except ``USR_FATAL_CONT`` and ``INT_ASSERT``) takes a format string and optional arguments, which are all passed to printf or similar.

  If the format string is preceded by an AST node (``BaseAST*``), then that node's file and line number are printed before the error message.

  (See ``compiler/include/misc.h``.)