1foreach
2-------
3
4Evaluate 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
12where ``<items>`` is a list of items that are separated by
13semicolon or whitespace.
14All commands between ``foreach`` and the matching ``endforeach`` are recorded
15without being invoked.  Once the ``endforeach`` is evaluated, the recorded
16list of commands is invoked once for each item in ``<items>``.
17At the beginning of each iteration the variable ``<loop_var>`` will be set
18to the value of the current item.
19
20The scope of ``<loop_var>`` is restricted to the loop scope. See policy
21:policy:`CMP0124` for details.
22
23The commands :command:`break` and :command:`continue` provide means to
24escape from the normal control flow.
25
26Per legacy, the :command:`endforeach` command admits
27an optional ``<loop_var>`` argument.
28If used, it must be a verbatim
29repeat of the argument of the opening
30``foreach`` command.
31
32.. code-block:: cmake
33
34  foreach(<loop_var> RANGE <stop>)
35
36In this variant, ``foreach`` iterates over the numbers
370, 1, ... up to (and including) the nonnegative integer ``<stop>``.
38
39.. code-block:: cmake
40
41  foreach(<loop_var> RANGE <start> <stop> [<step>])
42
43In this variant, ``foreach`` iterates over the numbers from
44``<start>`` up to at most ``<stop>`` in steps of ``<step>``.
45If ``<step>`` is not specified, then the step size is 1.
46The three arguments ``<start>`` ``<stop>`` ``<step>`` must
47all be nonnegative integers, and ``<stop>`` must not be
48smaller than ``<start>``; otherwise you enter the danger zone
49of undocumented behavior that may change in future releases.
50
51.. code-block:: cmake
52
53  foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
54
55In this variant, ``<lists>`` is a whitespace or semicolon
56separated list of list-valued variables. The ``foreach``
57command iterates over each item in each given list.
58The ``<items>`` following the ``ITEMS`` keyword are processed
59as in the first variant of the ``foreach`` command.
60The forms ``LISTS A`` and ``ITEMS ${A}`` are
61equivalent.
62
63The following example shows how the ``LISTS`` option is
64processed:
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
77yields
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
96In this variant, ``<lists>`` is a whitespace or semicolon
97separated list of list-valued variables. The ``foreach``
98command iterates over each list simultaneously setting the
99iteration 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
122yields
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=
133