llvm.org GIT mirror llvm / 3177949
Streamline the mentions of grep and FileCheck in TestingGuide.rst grep is now only mentioned once in a sentence that explicitly says it's deprecated. For FileCheck, there's no reason to repeat part of the documentation that exists in CommandGuide/FileCheck. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@172835 91177308-0d34-0410-b5e6-96231b3b80d8 Eli Bendersky 6 years ago
1 changed file(s) with 7 addition(s) and 37 deletion(s). Raw diff Collapse all Expand all
230230 - You can't do ``2>&1``. That will cause :program:`lit` to write to a file
231231 named ``&1``. Usually this is done to get stderr to go through a pipe. You
232232 can do that with ``|&`` so replace this idiom:
233 ``... 2>&1 | grep`` with ``... |& grep``
233 ``... 2>&1 | FileCheck`` with ``... |& FileCheck``
234234 - You can only redirect to a file, not to another descriptor and not
235235 from a here document.
236236
237237 There are some quoting rules that you must pay attention to when writing
238238 your RUN lines. In general nothing needs to be quoted. :program:`lit` won't
239239 strip off any quote characters so they will get passed to the invoked program.
240 For example:
241
242 .. code-block:: bash
243
244 ... | grep 'find this string'
245
246 This will fail because the ``'`` characters are passed to ``grep``. This would
247 make ``grep`` to look for ``'find`` in the files ``this`` and
248 ``string'``. To avoid this use curly braces to tell :program:`lit` that it
249 should treat everything enclosed as one value. So our example would become:
250
251 .. code-block:: bash
252
253 ... | grep {find this string}
240 To avoid this use curly braces to tell :program:`lit` that it should treat
241 everything enclosed as one value.
254242
255243 In general, you should strive to keep your RUN lines as simple as possible,
256 using them only to run tools that generate the output you can then examine. The
257 recommended way to examine output to figure out if the test passes it using the
258 :doc:`FileCheck tool `. The usage of ``grep`` in RUN
259 lines is discouraged.
244 using them only to run tools that generate textual output you can then examine.
245 The recommended way to examine output to figure out if the test passes it using
246 the :doc:`FileCheck tool `. *[The usage of grep in RUN
247 lines is deprecated - please do not send or commit patches that use it.]*
260248
261249 Fragile tests
262250 -------------
294282
295283 To make your tests robust, always use ``opt ... < %s`` in the RUN line.
296284 :program:`opt` does not output a ``ModuleID`` when input comes from stdin.
297
298 The FileCheck utility
299 ---------------------
300
301 A powerful feature of the RUN lines is that it allows any arbitrary
302 commands to be executed as part of the test harness. While standard
303 (portable) unix tools like ``grep`` work fine on run lines, as you see
304 above, there are a lot of caveats due to interaction with shell syntax,
305 and we want to make sure the run lines are portable to a wide range of
306 systems. Another major problem is that ``grep`` is not very good at checking
307 to verify that the output of a tools contains a series of different
308 output in a specific order. The :program:`FileCheck` tool was designed to
309 help with these problems.
310
311 :program:`FileCheck` is designed to read a file to check from standard input,
312 and the set of things to verify from a file specified as a command line
313 argument. :program:`FileCheck` is described in :doc:`the FileCheck man page
314 `.
315285
316286 Variables and substitutions
317287 ---------------------------