@@ -619,6 +619,15 @@ RUN lines:
619619 ``%else %{<else branch>%} `` is optional and treated like ``%else %{%} ``
620620 if not present.
621621
622+ ``%(line) ``, ``%(line+<number>) ``, ``%(line-<number>) ``
623+
624+ The number of the line where this substitution is used, with an
625+ optional integer offset. These expand only if they appear
626+ immediately in ``RUN: ``, ``DEFINE: ``, and ``REDEFINE: `` directives.
627+ Occurrences in substitutions defined elsewhere are never expanded.
628+ For example, this can be used in tests with multiple RUN lines,
629+ which reference the test file's line numbers.
630+
622631**LLVM-specific substitutions: **
623632
624633``%shlibext ``
@@ -633,12 +642,6 @@ RUN lines:
633642
634643 Example: ``.exe `` (Windows), empty on Linux.
635644
636- ``%(line) ``, ``%(line+<number>) ``, ``%(line-<number>) ``
637- The number of the line where this substitution is used, with an optional
638- integer offset. This can be used in tests with multiple RUN lines, which
639- reference test file's line numbers.
640-
641-
642645**Clang-specific substitutions: **
643646
644647``%clang ``
@@ -670,8 +673,199 @@ RUN lines:
670673 output affects test results. It's usually easy to tell: just look for
671674 redirection or piping of the ``FileCheck `` call's stdout or stderr.
672675
673- To add more substitutions, look at ``test/lit.cfg `` or ``lit.local.cfg ``.
676+ .. _Test-specific substitutions :
677+
678+ **Test-specific substitutions: **
679+
680+ Additional substitutions can be defined as follows:
681+
682+ - Lit configuration files (e.g., ``lit.cfg `` or ``lit.local.cfg ``) can define
683+ substitutions for all tests in a test directory. They do so by extending the
684+ substitution list, ``config.substitutions ``. Each item in the list is a tuple
685+ consisting of a pattern and its replacement, which lit applies using python's
686+ ``re.sub `` function.
687+ - To define substitutions within a single test file, lit supports the
688+ ``DEFINE: `` and ``REDEFINE: `` directives, described in detail below. So that
689+ they have no effect on other test files, these directives modify a copy of the
690+ substitution list that is produced by lit configuration files.
691+
692+ For example, the following directives can be inserted into a test file to define
693+ ``%{cflags} `` and ``%{fcflags} `` substitutions with empty initial values, which
694+ serve as the parameters of another newly defined ``%{check} `` substitution:
695+
696+ .. code-block :: llvm
697+
698+ ; DEFINE: %{cflags} =
699+ ; DEFINE: %{fcflags} =
700+
701+ ; DEFINE: %{check} = \
702+ ; DEFINE: %clang_cc1 -verify -fopenmp -fopenmp-version=51 %{cflags} \
703+ ; DEFINE: -emit-llvm -o - %s | \
704+ ; DEFINE: FileCheck %{fcflags} %s
705+
706+
707+ file to be shared with other test files. Either way, the test file can then
708+ specify directives like the following to redefine the parameter substitutions as
709+ desired before each use of ``%{check} `` in a ``RUN: `` line:
710+
711+ .. code-block :: llvm
712+
713+ ; REDEFINE: %{cflags} = -triple x86_64-apple-darwin10.6.0 -fopenmp-simd
714+ ; REDEFINE: %{fcflags} = -check-prefix=SIMD
715+ ; RUN: %{check}
716+
717+ ; REDEFINE: %{cflags} = -triple x86_64-unknown-linux-gnu -fopenmp-simd
718+ ; REDEFINE: %{fcflags} = -check-prefix=SIMD
719+ ; RUN: %{check}
720+
721+ ; REDEFINE: %{cflags} = -triple x86_64-apple-darwin10.6.0
722+ ; REDEFINE: %{fcflags} = -check-prefix=NO-SIMD
723+ ; RUN: %{check}
724+
725+ ; REDEFINE: %{cflags} = -triple x86_64-unknown-linux-gnu
726+ ; REDEFINE: %{fcflags} = -check-prefix=NO-SIMD
727+ ; RUN: %{check}
728+
729+ DEFINE: `` directives for the
730+ parameter substitutions in the above example serve a second purpose: they
731+ establish the substitution order so that both ``%{check} `` and its parameters
732+ expand as desired. There's a simple way to remember the required definition
733+ order in a test file: define a substitution before any substitution that might
734+ refer to it.
735+
736+ In general, substitution expansion behaves as follows:
737+
738+ - Upon arriving at each ``RUN: `` line, lit expands all substitutions in that
739+ ``RUN: `` line using their current values from the substitution list. No
740+ substitution expansion is performed immediately at ``DEFINE: `` and
741+ ``REDEFINE: `` directives except ``%(line) ``, ``%(line+<number>) ``, and
742+ ``%(line-<number>) ``.
743+ - When expanding substitutions in a ``RUN: `` line, lit makes only one pass
744+ through the substitution list by default. In this case, a substitution must
745+ have been inserted earlier in the substitution list than any substitution
746+ appearing in its value in order for the latter to expand. (For greater
747+ flexibility, you can enable multiple passes through the substitution list by
748+ setting `recursiveExpansionLimit `_ in a lit configuration file.)
749+ - While lit configuration files can insert anywhere in the substitution list,
750+ the insertion behavior of the ``DEFINE: `` and ``REDEFINE: `` directives is
751+ specified below and is designed specifically for the use case presented in the
752+ example above.
753+ - Defining a substitution in terms of itself, whether directly or via other
754+ substitutions, should be avoided. It usually produces an infinitely recursive
755+ definition that cannot be fully expanded. It does *not * define the
756+ substitution in terms of its previous value, even when using ``REDEFINE: ``.
757+
758+ The relationship between the ``DEFINE: `` and ``REDEFINE: `` directive is
759+ analogous to the relationship between a variable declaration and variable
760+ assignment in many programming languages:
761+
762+ - ``DEFINE: %{name} = value ``
763+
764+ This directive assigns the specified value to a new substitution whose
765+ pattern is ``%{name} ``, or it reports an error if there is already a
766+ substitution whose pattern contains ``%{name} `` because that could produce
767+ confusing expansions (e.g., a lit configuration file might define a
768+ substitution with the pattern ``%{name}\[0\] ``). The new substitution is
769+ inserted at the start of the substitution list so that it will expand first.
770+ Thus, its value can contain any substitution previously defined, whether in
771+ the same test file or in a lit configuration file, and both will expand.
772+
773+ - ``REDEFINE: %{name} = value ``
774+
775+ This directive assigns the specified value to an existing substitution whose
776+ pattern is ``%{name} ``, or it reports an error if there are no substitutions
777+ with that pattern or if there are multiple substitutions whose patterns
778+ contain ``%{name} ``. The substitution's current position in the substitution
779+ list does not change so that expansion order relative to other existing
780+ substitutions is preserved.
781+
782+ The following properties apply to both the ``DEFINE: `` and ``REDEFINE: ``
783+ directives:
784+
785+ - **Substitution name **: In the directive, whitespace immediately before or
786+ after ``%{name} `` is optional and discarded. ``%{name} `` must start with
787+ ``%{ ``, it must end with ``} ``, and the rest must start with a letter or
788+ underscore and contain only alphanumeric characters, hyphens, underscores, and
789+ colons. This syntax has a few advantages:
790+
791+ - It is impossible for ``%{name} `` to contain sequences that are special in
792+ python's ``re.sub `` patterns. Otherwise, attempting to specify
793+ ``%{name} `` as a substitution pattern in a lit configuration file could
794+ produce confusing expansions.
795+ - The braces help avoid the possibility that another substitution's pattern
796+ will match part of ``%{name} `` or vice-versa, producing confusing
797+ expansions. However, the patterns of substitutions defined by lit
798+ configuration files and by lit itself are not restricted to this form, so
799+ overlaps are still theoretically possible.
800+
801+ - **Substitution value **: The value includes all text from the first
802+ non-whitespace character after ``= `` to the last non-whitespace character. If
803+ there is no non-whitespace character after ``= ``, the value is the empty
804+ string. Escape sequences that can appear in python ``re.sub `` replacement
805+ strings are treated as plain text in the value.
806+ - **Line continuations **: If the last non-whitespace character on the line after
807+ ``: `` is ``\ ``, then the next directive must use the same directive keyword
808+ (e.g., ``DEFINE: ``) , and it is an error if there is no additional directive.
809+ That directive serves as a continuation. That is, before following the rules
810+ above to parse the text after ``: `` in either directive, lit joins that text
811+ together to form a single directive, replaces the ``\ `` with a single space,
812+ and removes any other whitespace that is now adjacent to that space. A
813+ continuation can be continued in the same manner. A continuation containing
814+ only whitespace after its ``: `` is an error.
815+
816+ .. _recursiveExpansionLimit :
817+
818+ **recursiveExpansionLimit: **
819+
820+ As described in the previous section, when expanding substitutions in a ``RUN: ``
821+ line, lit makes only one pass through the substitution list by default. Thus,
822+ if substitutions are not defined in the proper order, some will remain in the
823+ ``RUN: `` line unexpanded. For example, the following directives refer to
824+ ``%{inner} `` within ``%{outer} `` but do not define ``%{inner} `` until after
825+ ``%{outer} ``:
826+
827+ .. code-block :: llvm
828+
829+ ; By default, this definition order does not enable full expansion.
830+
831+ ; DEFINE: %{outer} = %{inner}
832+ ; DEFINE: %{inner} = expanded
833+
834+ ; RUN: echo '%{outer}'
835+
836+ DEFINE: `` inserts substitutions at the start of the substitution list, so
837+ ``%{inner} `` expands first but has no effect because the original ``RUN: `` line
838+ does not contain ``%{inner} ``. Next, ``%{outer} `` expands, and the output of
839+ the ``echo `` command becomes:
840+
841+ .. code-block :: shell
842+
843+ %{inner}
844+
845+
846+ ``%{outer} `` and ``%{inner} ``. However, if a test has a complex set of
847+ substitutions that can all reference each other, there might not exist a
848+ sufficient substitution order.
849+
850+ To address such use cases, lit configuration files support
851+ ``config.recursiveExpansionLimit ``, which can be set to a non-negative integer
852+ to specify the maximum number of passes through the substitution list. Thus, in
853+ the above example, setting the limit to 2 would cause lit to make a second pass
854+ that expands ``%{inner} `` in the ``RUN: `` line, and the output from the ``echo ``
855+ command when then be:
856+
857+ .. code-block :: shell
858+
859+ expanded
860+
861+ RUN: ``
862+ line has stopped changing. In the above example, setting the limit higher than
863+ 2 is thus harmless.
674864
865+ To facilitate debugging, after reaching the limit, lit will make one extra pass
866+ and report an error if the ``RUN: `` line changes again. In the above example,
867+ setting the limit to 1 will thus cause lit to report an error instead of
868+ producing incorrect output.
675869
676870Options
677871-------
0 commit comments