[Examples] Add ability to run and test examples

Add a `lit.cfg.py` in the `examples` directory which sets up the lit config for
example Mojo files (notebooks not yet supported).  Add a wrapper script,
`run-examples.sh` which creates a build directory and invokes `lit` using this
configuration.

Go one step further and create a GitHub workflow that puts all of the pieces
together to download the latest stable Mojo compiler and test the examples using
the provided script.

The `scripts/run-examples.sh` is something that can be run both locally and in
CI.

.github/workflows/examples.yml

@@ -0,0 +1,48 @@
+name: Test Examples
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test-examples:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    env:
+      DEBIAN_FRONTEND: noninteractive
+      TARGET_LLVM_VERSION: 17
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v2
+
+      - name: "Get the modular installer, install mojo compiler"
+        run: |
+          echo "Downloading the latest Mojo Compiler"
+          curl https://get.modular.com | sh - && modular auth examples
+          modular install mojo
+
+          # Set MODULAR_HOME env variable
+          echo 'MODULAR_HOME="/home/runner/.modular"' >> $GITHUB_ENV
+
+          # Add `mojo` to `PATH`
+          echo "${MODULAR_HOME}/pkg/packages.modular.com_mojo/bin" >> $GITHUB_PATH
+
+          mojo --version
+
+      - name: Setup python
+        uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c
+        with:
+          python-version: 3.12
+
+      - name: Install build tools
+        run: |
+          wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh ${{env.TARGET_LLVM_VERSION}}
+
+          python3 -m pip install lit
+
+      - name: Run the examples
+        run: |
+          ./scripts/run-examples.sh

.gitignore

@@ -0,0 +1,2 @@
+/build
+*.pyc

examples/lit.cfg.py

@@ -0,0 +1,55 @@
+# ===----------------------------------------------------------------------=== #
+# Copyright (c) 2024, Modular Inc. All rights reserved.
+#
+# Licensed under the Apache License v2.0 with LLVM Exceptions:
+# https://llvm.org/LICENSE.txt
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ===----------------------------------------------------------------------=== #
+
+from pathlib import Path
+
+import lit.formats
+import lit.llvm
+
+config.test_format = lit.formats.ShTest(True)
+
+# name: The name of this test suite.
+config.name = "Mojo Public Examples"
+
+# suffixes: A list of file extensions to treat as test files.
+# TODO: Enable notebooks
+config.suffixes = [".mojo", ".🔥"]
+
+config.excludes = [
+    # No RUN: directive, just bare examples
+    "hello_interop.mojo",
+    "matmul.mojo"
+]
+
+# Have the examples run in the build directory.
+# The `run-examples.sh` script creates the build directory.
+build_root = Path.cwd().parent / "build"
+
+# Execute the examples inside this part of the build
+# directory to avoid polluting the source tree.
+config.test_exec_root = build_root / "examples"
+
+# test_source_root: The root path where tests are located.
+config.test_source_root = Path.cwd()
+
+# Substitute %mojo for just `mojo` itself.
+config.substitutions.insert(0, ("%mojo", "mojo"))
+
+# Pass through several environment variables
+# to the underlying subprocesses that run the tests.
+lit.llvm.initialize(lit_config, config)
+lit.llvm.llvm_config.with_system_environment(
+    [
+        "MODULAR_HOME",
+    ]
+)

scripts/run-examples.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# ===----------------------------------------------------------------------=== #
+# Copyright (c) 2024, Modular Inc. All rights reserved.
+#
+# Licensed under the Apache License v2.0 with LLVM Exceptions:
+# https://llvm.org/LICENSE.txt
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ===----------------------------------------------------------------------=== #
+
+set -euo pipefail
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+REPO_ROOT="${SCRIPT_DIR}"/../
+EXAMPLES_DIR="${REPO_ROOT}"/examples
+
+echo "Creating build directory"
+BUILD_DIR="${REPO_ROOT}"/build
+mkdir -p "${BUILD_DIR}"
+
+# Change into the examples dir where lit.cfg.py is
+# and then invoke lit to run the examples.
+(cd "${EXAMPLES_DIR}" && lit -sv .)