[thirdparty/gcc.git] / gcc / doc / cpp / conditional-uses.rst

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

.. _conditional-uses:

Conditional Uses
****************

There are three general reasons to use a conditional.

* A program may need to use different code depending on the machine or
  operating system it is to run on.  In some cases the code for one
  operating system may be erroneous on another operating system; for
  example, it might refer to data types or constants that do not exist on
  the other system.  When this happens, it is not enough to avoid
  executing the invalid code.  Its mere presence will cause the compiler
  to reject the program.  With a preprocessing conditional, the offending
  code can be effectively excised from the program when it is not valid.

* You may want to be able to compile the same source file into two
  different programs.  One version might make frequent time-consuming
  consistency checks on its intermediate data, or print the values of
  those data for debugging, and the other not.

* A conditional whose condition is always false is one way to exclude code
  from the program but keep it as a sort of comment for future reference.

Simple programs that do not need system-specific logic or complex
debugging hooks generally will not need to use preprocessing
conditionals.
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	.. _conditional-uses:
	7
	8	Conditional Uses
	9	****************
	10
	11	There are three general reasons to use a conditional.
	12
	13	* A program may need to use different code depending on the machine or
	14	operating system it is to run on. In some cases the code for one
	15	operating system may be erroneous on another operating system; for
	16	example, it might refer to data types or constants that do not exist on
	17	the other system. When this happens, it is not enough to avoid
	18	executing the invalid code. Its mere presence will cause the compiler
	19	to reject the program. With a preprocessing conditional, the offending
	20	code can be effectively excised from the program when it is not valid.
	21
	22	* You may want to be able to compile the same source file into two
	23	different programs. One version might make frequent time-consuming
	24	consistency checks on its intermediate data, or print the values of
	25	those data for debugging, and the other not.
	26
	27	* A conditional whose condition is always false is one way to exclude code
	28	from the program but keep it as a sort of comment for future reference.
	29
	30	Simple programs that do not need system-specific logic or complex
	31	debugging hooks generally will not need to use preprocessing
3ed1b4ce	32	conditionals.