docs: improve Python install notes and build error messages (substrai…

…t-io#36)

README.md

@@ -40,10 +40,15 @@ Command-line interface
 ----------------------
 
 The easiest way to play around with the validator is via the command-line
-interface provided by the Python `substrait-validator` module. At the time of
-writing, the package is not yet available on PyPI, but it should be easy enough
-to build from source (see the `py` subdirectory). After installing, you should
-be able to run:
+interface provided by the Python `substrait-validator` module. You can install
+this from PyPI using pip:
+
+```console
+user@host:~$ pip install substrait-validator
+```
+
+You can also build it from source if you want; see the `py` subdirectory. After
+installing, you should be able to run:
 
 ```console
 user@host:~$ substrait-validator

py/README.md

@@ -5,13 +5,21 @@ validator library.
 
 ## Installation
 
-No wheels are published yet at this time, so you have 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.
+The easiest way to install the validator is to get it from PyPI:
 
-If you want to do an editable install, you must run
-`./prepare_build.py populate` first.
+```console
+user@host:~$ pip install substrait-validator
+```
+
+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.
 
 ## Building wheels and source distributions
 

py/build.rs

@@ -19,6 +19,13 @@ fn main() {
     let input_paths = if std::path::Path::new("local_dependencies").exists() {
         vec!["proto"]
     } else {
+        assert!(
+            std::path::Path::new("..")
+                .join("substrait")
+                .join("proto")
+                .exists(),
+            "Could not find (git-root)/substrait/proto. Did you check out submodules?"
+        );
         vec!["../proto", "../substrait/proto"]
     };
 

py/substrait_validator_build/__init__.py

@@ -31,8 +31,17 @@ def _copytree(source, dest):
         files = os.listdir(source)
         for f in files:
             _copytree(os.path.join(source, f), os.path.join(dest, f))
-    else:
+    elif os.path.isfile(source):
         shutil.copyfile(source, dest)
+    else:
+        rel_path = os.path.relpath(source, "..")
+        abs_path = os.path.realpath(source)
+        path = os.path.join("(git-root)", rel_path)
+        msg = f"Could not find {path}."
+        if rel_path.startswith("substrait"):
+            msg = f"{msg} Did you check out submodules?"
+        msg = f"{msg} Full path = {abs_path}"
+        raise FileNotFoundError(msg)
 
 
 def populate():

rs/build.rs

@@ -71,6 +71,12 @@ fn main() -> Result<()> {
         let validator_git_dir = manifest_dir.join("..");
         let substrait_git_dir = validator_git_dir.join("substrait");
 
+        // Give a proper error message if submodules aren't checked out.
+        assert!(
+            substrait_git_dir.join("proto").exists(),
+            "Could not find (git-root)/substrait/proto. Did you check out submodules?"
+        );
+
         // Synchronize the YAML extension file schema.
         synchronize(
             &substrait_git_dir,