[thirdparty/gcc.git] / gcc / doc / cpp / diagnostics.rst

..
  Copyright 1988-2022 Free Software Foundation, Inc.
  This is part of the GCC manual.
  For copying conditions, see the copyright.rst file.

.. index:: diagnostic, reporting errors, reporting warnings, #error

.. _diagnostics:

Diagnostics
-----------

The directive :samp:`#error` causes the preprocessor to report a fatal
error.  The tokens forming the rest of the line following :samp:`#error`
are used as the error message.

You would use :samp:`#error` inside of a conditional that detects a
combination of parameters which you know the program does not properly
support.  For example, if you know that the program will not run
properly on a VAX, you might write

.. code-block:: c++

  #ifdef __vax__
  #error "Won't work on VAXen.  See comments at get_last_object."
  #endif

If you have several configuration parameters that must be set up by
the installation in a consistent way, you can use conditionals to detect
an inconsistency and report it with :samp:`#error`.  For example,

.. code-block:: c++

  #if !defined(FOO) && defined(BAR)
  #error "BAR requires FOO."
  #endif

.. index:: #warning

The directive :samp:`#warning` is like :samp:`#error`, but causes the
preprocessor to issue a warning and continue preprocessing.  The tokens
following :samp:`#warning` are used as the warning message.

You might use :samp:`#warning` in obsolete header files, with a message
directing the user to the header file which should be used instead.

Neither :samp:`#error` nor :samp:`#warning` macro-expands its argument.
Internal whitespace sequences are each replaced with a single space.
The line must consist of complete tokens.  It is wisest to make the
argument of these directives be a single string constant; this avoids
problems with apostrophes and the like.
Commit	Line	Data
c63539ff ML	1	..
	2	Copyright 1988-2022 Free Software Foundation, Inc.
	3	This is part of the GCC manual.
	4	For copying conditions, see the copyright.rst file.
	5
	6	.. index:: diagnostic, reporting errors, reporting warnings, #error
	7
	8	.. _diagnostics:
	9
	10	Diagnostics
	11	-----------
	12
	13	The directive :samp:`#error` causes the preprocessor to report a fatal
	14	error. The tokens forming the rest of the line following :samp:`#error`
	15	are used as the error message.
	16
	17	You would use :samp:`#error` inside of a conditional that detects a
	18	combination of parameters which you know the program does not properly
	19	support. For example, if you know that the program will not run
	20	properly on a VAX, you might write
	21
	22	.. code-block:: c++
	23
	24	#ifdef __vax__
	25	#error "Won't work on VAXen. See comments at get_last_object."
	26	#endif
	27
	28	If you have several configuration parameters that must be set up by
	29	the installation in a consistent way, you can use conditionals to detect
	30	an inconsistency and report it with :samp:`#error`. For example,
	31
	32	.. code-block:: c++
	33
	34	#if !defined(FOO) && defined(BAR)
	35	#error "BAR requires FOO."
	36	#endif
	37
	38	.. index:: #warning
	39
	40	The directive :samp:`#warning` is like :samp:`#error`, but causes the
	41	preprocessor to issue a warning and continue preprocessing. The tokens
	42	following :samp:`#warning` are used as the warning message.
	43
	44	You might use :samp:`#warning` in obsolete header files, with a message
	45	directing the user to the header file which should be used instead.
	46
	47	Neither :samp:`#error` nor :samp:`#warning` macro-expands its argument.
	48	Internal whitespace sequences are each replaced with a single space.
	49	The line must consist of complete tokens. It is wisest to make the
	50	argument of these directives be a single string constant; this avoids
3ed1b4ce	51	problems with apostrophes and the like.