Add python -m __static__ for running Static Python scripts

Allow users to run Static Python files with a single command:

    python -m __static__ script.py

This installs the Static Python loader and executes the script through
it, so both the entry file and all its imports benefit from Static
Python compilation. Previously users had to write a separate bootstrap
file that called loader.install() before importing their code.

Also updates the tutorial documentation to document this new approach
as the recommended way to get started.

Resolves T256371881

Author: Subbarao Garlapati

cinderx/Docs/StaticPython/tutorial.md

@@ -5,17 +5,22 @@
 Static Python is still under development, and there are a lot of rough
 edges, including probably bugs that can crash the interpreter.
 
-Getting full benefit from Static Python (with cross-module compilation)
-requires a module loader able to detect Static Python modules based on
-some marker (we use the presence of `import __static__`) and compile
-them using the Static Python bytecode compiler. Such a loader is
-included (at
-`compiler.strict.loader.StrictSourceFileLoader`) and you can
-install it by calling `compiler.strict.loader.install()` in
-the `main` module of your program (before anything else is imported.)
-Note this means the main module itself cannot be Static Python. You can
-also just set the `PYTHONINSTALLSTRICTLOADER` environment variable to a
-nonzero value, and the loader will be installed for you.
+The simplest way to run a Static Python script is:
+
+    python -m __static__ script.py
+
+This installs the Static Python loader and executes your script. Both
+the entry script and any modules it imports that use `import __static__`
+will be compiled through the Static Python pipeline.
+
+### Manual loader installation
+
+For more control, you can install the loader yourself by calling
+`cinderx.compiler.strict.loader.install()` in the `main` module of
+your program (before anything else is imported.) Note this means the
+main module itself cannot be Static Python. You can also just set the
+`PYTHONINSTALLSTRICTLOADER` environment variable to a nonzero value,
+and the loader will be installed for you.
 
 Once you've installed the loader, any module with `import __static__`
 as its first line of code (barring optional docstring and optional
@@ -25,6 +30,8 @@ immutable modules that can\'t have side effects at import time --
 without Static Python. `import __static__` also implies Strict, so you
 should never use both.)
 
+### Compiling individual files
+
 It is also possible to try out Static Python on simple examples by
 running `./python -m compiler --static somemod.py`. This will compile
 and execute `somemod.py` as Static Python. Add `--dis` to also dump a

cinderx/PythonLib/__static__/__main__.py

@@ -0,0 +1,44 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+
+"""Run a Python script with Static Python compilation.
+
+Usage: python -m __static__ script.py [args...]
+"""
+
+import importlib.util
+import os
+import sys
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python -m __static__ <script.py> [args...]", file=sys.stderr)
+        sys.exit(1)
+
+    script = sys.argv[1]
+    if not os.path.isfile(script):
+        print(f"Error: {script!r} is not a file", file=sys.stderr)
+        sys.exit(1)
+
+    sys.argv[:] = sys.argv[1:]
+
+    from cinderx.compiler.strict.loader import install, StrictSourceFileLoader
+
+    install()
+
+    script_dir = os.path.dirname(os.path.abspath(script))
+    if script_dir not in sys.path:
+        sys.path.insert(0, script_dir)
+
+    loader = StrictSourceFileLoader("__main__", script)
+    spec = importlib.util.spec_from_file_location("__main__", script, loader=loader)
+    if spec is None:
+        print(f"Error: could not load {script!r}", file=sys.stderr)
+        sys.exit(1)
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["__main__"] = module
+    spec.loader.exec_module(module)
+
+
+main()

cinderx/PythonLib/test_cinderx/test___static__/__init__.py

@@ -1,5 +1,6 @@
 # Copyright (c) Meta Platforms, Inc. and affiliates.
 # flake8: noqa
 from .test_enum import TestEnum
+from .test_module_runner import TestStaticModuleRunner
 from .test_native_utils import TestNativeInvoke
 from .tests import StaticTests

cinderx/PythonLib/test_cinderx/test___static__/test_module_runner.py

@@ -0,0 +1,65 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import os
+import subprocess
+import sys
+import tempfile
+import textwrap
+import unittest
+
+
+class TestStaticModuleRunner(unittest.TestCase):
+    def test_entry_script_is_statically_compiled(self):
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".py", delete=False
+        ) as f:
+            f.write(textwrap.dedent("""
+                import __static__
+                from cinderx.compiler.consts import CI_CO_STATICALLY_COMPILED
+
+                def add(x: int, y: int) -> int:
+                    return x + y
+
+                assert add.__code__.co_flags & CI_CO_STATICALLY_COMPILED
+            """))
+            script_path = f.name
+
+        try:
+            result = subprocess.run(
+                [sys.executable, "-m", "__static__", script_path],
+                capture_output=True, text=True, timeout=30,
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+        finally:
+            os.unlink(script_path)
+
+    def test_imported_module_is_statically_compiled(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            lib_path = os.path.join(tmpdir, "sp_lib.py")
+            with open(lib_path, "w") as f:
+                f.write(textwrap.dedent("""
+                    import __static__
+
+                    def compute(x: int, y: int) -> int:
+                        return x + y
+                """))
+
+            main_path = os.path.join(tmpdir, "sp_main.py")
+            with open(main_path, "w") as f:
+                f.write(textwrap.dedent("""
+                    import __static__
+                    from cinderx.compiler.consts import CI_CO_STATICALLY_COMPILED
+                    from sp_lib import compute
+
+                    assert compute.__code__.co_flags & CI_CO_STATICALLY_COMPILED
+                """))
+
+            result = subprocess.run(
+                [sys.executable, "-m", "__static__", main_path],
+                capture_output=True, text=True, timeout=30,
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()