Help/command/block.rst

   1 block
   2 -----
   3
   4 .. versionadded:: 3.25
   5
   6 Evaluate a group of commands with a dedicated variable and/or policy scope.
   7
   8 .. code-block:: cmake
   9
  10   block([SCOPE_FOR [POLICIES] [VARIABLES] ] [PROPAGATE <var-name>...])
  11     <commands>
  12   endblock()
  13
  14 All commands between ``block()`` and the matching :command:`endblock` are
  15 recorded without being invoked.  Once the :command:`endblock` is evaluated, the
  16 recorded list of commands is invoked inside the requested scopes, then the
  17 scopes created by the ``block()`` command are removed.
  18
  19 ``SCOPE_FOR``
  20   Specify which scopes must be created.
  21
  22   ``POLICIES``
  23     Create a new policy scope. This is equivalent to
  24     :command:`cmake_policy(PUSH)`.
  25
  26   ``VARIABLES``
  27     Create a new variable scope.
  28
  29   If ``SCOPE_FOR`` is not specified, this is equivalent to:
  30
  31   .. code-block:: cmake
  32
  33     block(SCOPE_FOR VARIABLES POLICIES)
  34
  35 ``PROPAGATE``
  36   When a variable scope is created by the :command:`block` command, this
  37   option sets or unsets the specified variables in the parent scope. This is
  38   equivalent to :command:`set(PARENT_SCOPE)` or :command:`unset(PARENT_SCOPE)`
  39   commands.
  40
  41   .. code-block:: cmake
  42
  43     set(var1 "INIT1")
  44     set(var2 "INIT2")
  45
  46     block(PROPAGATE var1 var2)
  47       set(var1 "VALUE1")
  48       unset(var2)
  49     endblock()
  50
  51     # Now var1 holds VALUE1, and var2 is unset
  52
  53   This option is only allowed when a variable scope is created. An error will
  54   be raised in the other cases.
  55
  56 When the ``block()`` is inside a :command:`foreach` or :command:`while`
  57 command, the :command:`break` and :command:`continue` commands can be used
  58 inside the block.
  59
  60 .. code-block:: cmake
  61
  62   while(TRUE)
  63     block()
  64        ...
  65        # the break() command will terminate the while() command
  66        break()
  67     endblock()
  68   endwhile()
  69
  70
  71 See Also
  72 ^^^^^^^^
  73
  74   * :command:`endblock`
  75   * :command:`return`
  76   * :command:`cmake_policy`