From 3f118defa59c999ea37675023683011d1cb4a40d Mon Sep 17 00:00:00 2001
From: Jeroen van Straten <jeroen.van.straten@gmail.com>
Date: Tue, 16 Aug 2022 16:38:00 +0200
Subject: [PATCH] docs: improve error messages for Python out-of-tree builds
 (#35) (#38)

---
 py/README.md                             | 30 ++++++++++++++++++++----
 py/substrait_validator_build/__init__.py | 24 +++++++++++++++++--
 2 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/py/README.md b/py/README.md
index e0dacb62..3b83891a 100644
--- a/py/README.md
+++ b/py/README.md
@@ -15,11 +15,31 @@ If you want to build manually, running something along the lines of
 `pip install .` should work. You should only need to have a
 [rust](https://www.rust-lang.org/tools/install) compiler installed.
 
-Be aware that this project relies on submodules, so you need to check those out
-first. If you've done that and get weird errors, try running
-`./prepare_build.py populate` manually first. The protobuf generation logic has
-to be run very early in the build process, and while this should be done
-automatically, the hook is not very reliable.
+If you want to create wheels or sdists of your own, you can do so using
+maturin (note the manual prepare_build.py invocation, see hints):
+
+```console
+user@host:~$ pip install maturin
+...
+user@host:~$ ./prepare_build.py populate
+user@host:~$ maturin build
+...
+📦 Built wheel for CPython 3.x to /path/to/substrait-validator/target/wheels/substrait_validator-x.y.z-cp3xx-cp3xx-linux_x86_64.whl
+user@host:~$ maturin sdist
+...
+📦 Built source distribution to /path/to/substrait-validator/target/wheels/substrait_validator-x.y.z.tar.gz
+```
+
+Some hints if you run into issues:
+
+ - This project relies on submodules, so you need to check those out first.
+ - Out-of-tree builds are not supported, so you may need to beat pip into
+   submission if you're using an old version or it otherwise insists on
+   building from a temp directory.
+ - If you get weird errors, try running `./prepare_build.py populate` manually
+   first. The protobuf generation logic has to be run very early in the build
+   process, and while this is done automatically for most build methods, not
+   all methods provide a hook for this.
 
 ## Building wheels and source distributions
 
diff --git a/py/substrait_validator_build/__init__.py b/py/substrait_validator_build/__init__.py
index 9212996e..ccb33180 100644
--- a/py/substrait_validator_build/__init__.py
+++ b/py/substrait_validator_build/__init__.py
@@ -3,6 +3,7 @@
 from maturin import *
 import shutil
 import os
+import sys
 
 
 _PATHS = [
@@ -55,8 +56,27 @@ def _prepare():
     # If the local_dependencies directory exists, pip is building the package
     # from a source distribution. In that case, the build environment is
     # already as it should be.
-    if not os.path.isdir("local_dependencies"):
-        populate()
+    if os.path.isdir("local_dependencies"):
+        return
+
+    # Outside of building from specially-prepared sdist packages, we don't
+    # support out-of-tree builds, because that breaks Maturin and Cargo. The
+    # error messages you'd get if you were to try would be cryptic at best, so
+    # we detect this and fail more gently here.
+    if os.path.basename(os.path.realpath(".")) != "py":
+        print(
+            "\n"
+            "=================================================================\n"
+            "Out-of-tree build detected. This is not supported. Please\n"
+            "configure pip (or whatever build system you're using) to build\n"
+            "in-tree, for example using an editable install.\n"
+            "See https://github.com/substrait-io/substrait-validator/issues/35\n"
+            "=================================================================\n",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    populate()
 
 
 _maturin_prepare_metadata_for_build_wheel = (