[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.

Add common artifacts to the `.gitignore` such as the new `build` directory, and
other Python-related things.

Author: JoeLoser

.github/workflows/examples.yml

@@ -0,0 +1,60 @@
+name: Test Examples
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test-examples:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    env:
+      DEBIAN_FRONTEND: noninteractive
+      LLVM_VERSION: 17
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v2
+
+      - name: Download Modular installer
+        run: |
+          curl -s https://get.modular.com | sh -
+
+      - name: Install stable Mojo compiler
+        run: |
+          # The <auth_token> of "examples" is arbitrary but something
+          # needs to be provided.
+          modular auth examples
+          modular install mojo
+
+      - 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.LLVM_VERSION}}
+
+          # Make common LLVM binaries (including FileCheck) in our PATH so they work when used in an unversioned context
+          # For example, instead of saying `FileCheck-17` which exists in `/usr/bin`, this allows us to just call
+          # FileCheck unqualified.
+          sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-${{env.LLVM_VERSION}} 100
+          sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-${{env.LLVM_VERSION}} 100
+          sudo update-alternatives --install /usr/bin/lld lld /usr/bin/lld-${{env.LLVM_VERSION}} 100
+          sudo update-alternatives --install /usr/bin/ld.lld ld.lld /usr/bin/ld.lld-${{env.LLVM_VERSION}} 100
+          sudo update-alternatives --install /usr/bin/lldb lldb /usr/bin/lldb-${{env.LLVM_VERSION}} 100
+          sudo update-alternatives --install /usr/bin/FileCheck FileCheck /usr/bin/FileCheck-${{env.LLVM_VERSION}} 100
+
+
+          python3 -m pip install lit
+
+      - name: Run examples
+        run: |
+          export MODULAR_HOME="/home/runner/.modular"
+          export PATH="/home/runner/.modular/pkg/packages.modular.com_mojo/bin:$PATH"
+          ./scripts/run-examples.sh

.gitignore

@@ -0,0 +1,18 @@
+# Build directory
+/build
+
+# Reference: https://github.com/github/gitignore/blob/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/

examples/lit.cfg.py

@@ -0,0 +1,56 @@
+# ===----------------------------------------------------------------------=== #
+# 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(__file__).parent.resolve()
+
+# 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",
+        "PATH",
+    ]
+)

scripts/run-examples.sh

@@ -0,0 +1,25 @@
+#!/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
+
+BUILD_DIR="${REPO_ROOT}"/build
+mkdir -p "${BUILD_DIR}"
+
+# Run the examples using `lit`.
+lit -sv "${EXAMPLES_DIR}"