docs: initial LIT and FileCheck tutorial and updates in other pages

docs/01-what-is-filecheck.rst

@@ -1,7 +1,7 @@
 What is FileCheck.py
 ====================
 
-**FileCheck.py** is a Python port of the **LLVM's FileCheck**, "flexible
+**FileCheck.py** is a Python port of **LLVM's FileCheck**, "flexible
 pattern matching file verifier" [1_].
 
 LLVM's FileCheck is a command-line tool written in C++ which
@@ -15,118 +15,27 @@ of the commands run by LIT.
 Why Python port?
 ----------------
 
-There are software projects that would benefit from having a suite of LLVM LIT
+There are software projects that would benefit from having a suite of LIT-based
 integration tests. Mull mutation testing system is one example [4_].
 
-The problem is that you have to build FileCheck from LLVM sources which is not a trivial task for 1) people who are not aware with the LLVM infrastructure and 2) Python-based projects that would prefer to not have to build anything from LLVM sources in their CI process.
+The problem is that you have to build FileCheck from LLVM sources which is not a trivial task for 1) people who are not familiar with the LLVM infrastructure and
+2) Python-based projects which would prefer to not depend on anything C or
+C++-related including building dependencies from LLVM sources.
 
 The option of having pre-compiled binaries is a workaround, but it is not always
-possible to keep third-party binary artifacts in source code,
-(see https://github.com/doorstop-dev/doorstop/pull/431#issuecomment-549237579).
+possible to keep third-party binary artifacts in source code
+(see
+https://github.com/doorstop-dev/doorstop/pull/431#issuecomment-549237579).
 
-Simple example
---------------
+What's next?
+------------
 
-When writing LIT/FileCheck tests it is common to combine the LIT's ``RUN``
-commands and FileCheck's ``CHECK`` assertions in a single file.
+If you are new to FileCheck and integration testing using LIT, we recommend you
+to read the tutorials: :doc:`03-tutorial-hello-world` and
+:doc:`04-tutorial-lit-and-filecheck`.
 
-Passing test
-~~~~~~~~~~~~
-
-Test file ``01-pass.c``:
-
-.. code-block:: c
-
-    /**
-    ; RUN: clang %s -o %S/hello-world && %S/hello-world | filecheck %s
-    ; CHECK: Hello world
-     */
-
-    #include <stdio.h>
-    int main() {
-      printf("Hello world\n");
-      return 0;
-    }
-
-Command:
-
-.. code-block:: bash
-
-   $ lit 01-pass.c
-
-Output:
-
-.. code-block:: text
-
-    -- Testing: 1 tests, single process --
-    PASS: <unnamed> :: 01-pass.c (1 of 1)
-    Testing Time: 0.10s
-      Expected Passes    : 1
-
-Failing test
-~~~~~~~~~~~~
-
-Test file ``02-fail.c``:
-
-.. code-block:: c
-
-    /**
-    ; RUN: clang %s -o %S/hello-world && %S/hello-world | filecheck %s
-    ; CHECK: Wrong line
-     */
-
-    #include <stdio.h>
-    int main() {
-      printf("Hello world\n");
-      return 0;
-    }
-
-
-Command:
-
-.. code-block:: bash
-
-    $ lit 02-fail.c
-
-Output:
-
-.. code-block:: text
-
-    -- Testing: 1 tests, single process --
-    FAIL: <unnamed> :: 02-fail.c (1 of 1)
-    Testing Time: 0.11s
-    ********************
-    Failing Tests (1):
-        <unnamed> :: 02-fail.c
-
-      Unexpected Failures: 1
-
-The verbose version:
-
-.. code-block:: bash
-
-    $ lit -v 02-fail.c
-
-Produces more output:
-
-.. code-block:: text
-
-    -- Testing: 1 tests, single process --
-    FAIL: <unnamed> :: 02-fail.c (1 of 1)
-    ******************** TEST '<unnamed> :: 02-fail.c' FAILED ********************
-    02-fail.c:3:10: error: CHECK: expected string not found in input
-    ; CHECK: Wrong line
-             ^
-    <stdin>:1:1: note: scanning from here
-    Hello world
-    ...
-    ********************
-    Testing Time: 0.11s
-    ********************
-    Failing Tests (1):
-        <unnamed> :: 02-fail.c
-
-      Unexpected Failures: 1
+If you know how FileCheck and LIT work, you can check out the status of the port
+on the :doc:`07-roadmap` page.
 
 Links
 -----

docs/02-installation.rst

@@ -1,7 +1,14 @@
 Installation
 ============
 
-...
+FileCheck.py is a pip package:
 
+.. code-block:: bash
 
+    pip install filecheck
 
+LIT is also a pip package:
+
+.. code-block:: bash
+
+    pip install lit

docs/03-tutorial-hello-world.rst

@@ -98,11 +98,10 @@ With invalid input:
    $ echo $?
    1
 
-What next?
-----------
+What's next?
+------------
 
 `FileCheck` is rarely used alone. The main use case for `FileCheck` is to serve
 as an assertion matcher tool when it is used in a combination with the
-`LLVM LIT Integrated Tester <https://llvm.org/docs/CommandGuide/lit.html>`_ and
-this is what our next tutorial is about. Don't stop here and check it out right
-away.
+LLVM LIT Integrated Tester and this is what our next tutorial is about. Don't
+stop here and check it out right away: :doc:`04-tutorial-lit-and-filecheck`.

docs/04-tutorial-lit-and-filecheck.rst

@@ -0,0 +1,152 @@
+Tutorial: LIT and FileCheck
+===========================
+
+This tutorial assumes that you have installed ``lit`` and ``filecheck`` and have
+them available in your PATH:
+
+.. code-block:: bash
+
+   $ filecheck
+   /usr/local/bin/filecheck
+   <check-file> not specified
+
+.. code-block:: bash
+
+   $ lit
+   ...
+   lit: error: No inputs specified
+
+Minimal example
+---------------
+
+When writing LIT/FileCheck tests it is common, but not required, to combine
+LIT's ``RUN`` commands and FileCheck's ``CHECK`` assertions in a single file.
+
+Let's create a file ``minimal.itest`` with the following contents
+
+.. code-block:: text
+
+    RUN: echo "Hello world" | filecheck %s
+    CHECK: Hello world
+
+LIT expects a config file in a directory from which it is run. Let's create
+a minimal one called ``lit.cfg``:
+
+.. code-block:: text
+
+    import lit.formats
+    config.test_format = lit.formats.ShTest("0")
+
+Now we can run ``lit``:
+
+.. code-block:: bash
+
+    lit minimal.itest
+
+.. code-block:: bash
+
+    -- Testing: 1 tests, single process --
+    PASS: <unnamed> :: test.itest (1 of 1)
+    Testing Time: 0.10s
+      Expected Passes    : 1
+
+Example: testing output of C program
+------------------------------------
+
+Passing test
+~~~~~~~~~~~~
+
+Test file ``01-pass.c``:
+
+.. code-block:: c
+
+    /**
+    ; RUN: clang %s -o %S/hello-world && %S/hello-world | filecheck %s
+    ; CHECK: Hello world
+     */
+
+    #include <stdio.h>
+    int main() {
+      printf("Hello world\n");
+      return 0;
+    }
+
+Command:
+
+.. code-block:: bash
+
+   $ lit 01-pass.c
+
+Output:
+
+.. code-block:: text
+
+    -- Testing: 1 tests, single process --
+    PASS: <unnamed> :: 01-pass.c (1 of 1)
+    Testing Time: 0.10s
+      Expected Passes    : 1
+
+Failing test
+~~~~~~~~~~~~
+
+Test file ``02-fail.c``:
+
+.. code-block:: c
+
+    /**
+    ; RUN: clang %s -o %S/hello-world && %S/hello-world | filecheck %s
+    ; CHECK: Wrong line
+     */
+
+    #include <stdio.h>
+    int main() {
+      printf("Hello world\n");
+      return 0;
+    }
+
+
+Command:
+
+.. code-block:: bash
+
+    $ lit 02-fail.c
+
+Output:
+
+.. code-block:: text
+
+    -- Testing: 1 tests, single process --
+    FAIL: <unnamed> :: 02-fail.c (1 of 1)
+    Testing Time: 0.11s
+    ********************
+    Failing Tests (1):
+        <unnamed> :: 02-fail.c
+
+      Unexpected Failures: 1
+
+The verbose version:
+
+.. code-block:: bash
+
+    $ lit -v 02-fail.c
+
+Produces more output:
+
+.. code-block:: text
+
+    -- Testing: 1 tests, single process --
+    FAIL: <unnamed> :: 02-fail.c (1 of 1)
+    ******************** TEST '<unnamed> :: 02-fail.c' FAILED ********************
+    02-fail.c:3:10: error: CHECK: expected string not found in input
+    ; CHECK: Wrong line
+             ^
+    <stdin>:1:1: note: scanning from here
+    Hello world
+    ...
+    ********************
+    Testing Time: 0.11s
+    ********************
+    Failing Tests (1):
+        <unnamed> :: 02-fail.c
+
+      Unexpected Failures: 1

docs/index.rst

@@ -7,7 +7,7 @@ Welcome to FileCheck.py's documentation!
    01-what-is-filecheck
    02-installation
    03-tutorial-hello-world
-   04-tutorial-llvm-lit-and-filecheck
+   04-tutorial-lit-and-filecheck
    05-check-commands
    06-options
    07-roadmap

examples/lit-and-filecheck/minimal.itest

@@ -0,0 +1,2 @@
+RUN: echo "Hello world" | filecheck %s
+CHECK: Hello world

docs/examples/what-is-filecheck/lit.cfg → examples/lit.cfg

@@ -1,3 +1,2 @@
 import lit.formats
 config.test_format = lit.formats.ShTest("0")
-