Help/command/foreach.rst

   1 foreach
   2 -------
   3
   4 Evaluate a group of commands for each value in a list.
   5
   6 .. code-block:: cmake
   7
   8   foreach(<loop_var> <items>)
   9     <commands>
  10   endforeach()
  11
  12 where ``<items>`` is a list of items that are separated by
  13 semicolon or whitespace.
  14 All commands between ``foreach`` and the matching ``endforeach`` are recorded
  15 without being invoked.  Once the ``endforeach`` is evaluated, the recorded
  16 list of commands is invoked once for each item in ``<items>``.
  17 At the beginning of each iteration the variable ``<loop_var>`` will be set
  18 to the value of the current item.
  19
  20 The scope of ``<loop_var>`` is restricted to the loop scope. See policy
  21 :policy:`CMP0124` for details.
  22
  23 The commands :command:`break` and :command:`continue` provide means to
  24 escape from the normal control flow.
  25
  26 Per legacy, the :command:`endforeach` command admits
  27 an optional ``<loop_var>`` argument.
  28 If used, it must be a verbatim
  29 repeat of the argument of the opening
  30 ``foreach`` command.
  31
  32 .. code-block:: cmake
  33
  34   foreach(<loop_var> RANGE <stop>)
  35
  36 In this variant, ``foreach`` iterates over the numbers
  37 0, 1, ... up to (and including) the nonnegative integer ``<stop>``.
  38
  39 .. code-block:: cmake
  40
  41   foreach(<loop_var> RANGE <start> <stop> [<step>])
  42
  43 In this variant, ``foreach`` iterates over the numbers from
  44 ``<start>`` up to at most ``<stop>`` in steps of ``<step>``.
  45 If ``<step>`` is not specified, then the step size is 1.
  46 The three arguments ``<start>`` ``<stop>`` ``<step>`` must
  47 all be nonnegative integers, and ``<stop>`` must not be
  48 smaller than ``<start>``; otherwise you enter the danger zone
  49 of undocumented behavior that may change in future releases.
  50
  51 .. code-block:: cmake
  52
  53   foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
  54
  55 In this variant, ``<lists>`` is a whitespace or semicolon
  56 separated list of list-valued variables. The ``foreach``
  57 command iterates over each item in each given list.
  58 The ``<items>`` following the ``ITEMS`` keyword are processed
  59 as in the first variant of the ``foreach`` command.
  60 The forms ``LISTS A`` and ``ITEMS ${A}`` are
  61 equivalent.
  62
  63 The following example shows how the ``LISTS`` option is
  64 processed:
  65
  66 .. code-block:: cmake
  67
  68   set(A 0;1)
  69   set(B 2 3)
  70   set(C "4 5")
  71   set(D 6;7 8)
  72   set(E "")
  73   foreach(X IN LISTS A B C D E)
  74       message(STATUS "X=${X}")
  75   endforeach()
  76
  77 yields
  78 ::
  79
  80   -- X=0
  81   -- X=1
  82   -- X=2
  83   -- X=3
  84   -- X=4 5
  85   -- X=6
  86   -- X=7
  87   -- X=8
  88
  89
  90 .. code-block:: cmake
  91
  92   foreach(<loop_var>... IN ZIP_LISTS <lists>)
  93
  94 .. versionadded:: 3.17
  95
  96 In this variant, ``<lists>`` is a whitespace or semicolon
  97 separated list of list-valued variables. The ``foreach``
  98 command iterates over each list simultaneously setting the
  99 iteration variables as follows:
 100
 101 - if the only ``loop_var`` given, then it sets a series of
 102   ``loop_var_N`` variables to the current item from the
 103   corresponding list;
 104 - if multiple variable names passed, their count should match
 105   the lists variables count;
 106 - if any of the lists are shorter, the corresponding iteration
 107   variable is not defined for the current iteration.
 108
 109 .. code-block:: cmake
 110
 111   list(APPEND English one two three four)
 112   list(APPEND Bahasa satu dua tiga)
 113
 114   foreach(num IN ZIP_LISTS English Bahasa)
 115       message(STATUS "num_0=${num_0}, num_1=${num_1}")
 116   endforeach()
 117
 118   foreach(en ba IN ZIP_LISTS English Bahasa)
 119       message(STATUS "en=${en}, ba=${ba}")
 120   endforeach()
 121
 122 yields
 123 ::
 124
 125   -- num_0=one, num_1=satu
 126   -- num_0=two, num_1=dua
 127   -- num_0=three, num_1=tiga
 128   -- num_0=four, num_1=
 129   -- en=one, ba=satu
 130   -- en=two, ba=dua
 131   -- en=three, ba=tiga
 132   -- en=four, ba=