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