Improve handling of linking errors (#262)

Two issues are addressed:
- if a user doesn't have the first compiler in the list, they would
  always receive a warning
- the error raised for the linking process assumes the source is a lack
  of supported compiler

frontend/catalyst/compiler.py

@@ -423,12 +423,12 @@ def _attempt_link(compiler, flags, infile, outfile, options):
             command = [compiler] + flags + [infile, "-o", outfile]
             run_writing_command(command, options)
             return True
-        except subprocess.CalledProcessError:
-            msg = (
-                f"Compiler {compiler} failed during execution of command {command}. "
-                "Will attempt fallback on available compilers."
-            )
-            warnings.warn(msg, UserWarning)
+        except subprocess.CalledProcessError as e:
+            # Only warn in verbose mode, as users might see it otherwise in regular use.
+            if options.verbose:
+                msg = f"Compiler {compiler} failed to link executable and returned with exit code "
+                msg += f"{e.returncode}. Output was: {e.output}.\nCommand: {command}"
+                warnings.warn(msg, UserWarning)
             return False
 
     @staticmethod
@@ -464,13 +464,15 @@ def run(infile, outfile=None, flags=None, fallback_compilers=None, options=None)
             flags = CompilerDriver.get_default_flags()
         if fallback_compilers is None:
             fallback_compilers = CompilerDriver._default_fallback_compilers
+        if options is None:
+            options = CompileOptions()
         for compiler in CompilerDriver._available_compilers(fallback_compilers):
             success = CompilerDriver._attempt_link(compiler, flags, infile, outfile, options)
             if success:
                 return outfile
-        msg = f"Unable to link {infile}. All available compiler options exhausted. "
-        msg += "Please provide a compatible compiler via $CATALYST_CC."
-        raise EnvironmentError(msg)
+        msg = f"Unable to link {infile}. Please check the output for any error messages. If no "
+        msg += "compiler was found by Catalyst, please specify a compatible one via $CATALYST_CC."
+        raise CompileError(msg)
 
 
 class Compiler:

frontend/test/pytest/test_compiler.py

@@ -98,7 +98,7 @@ def test_compiler_failed_warning(self):
         """Test that a warning is emitted when a compiler failed."""
         with pytest.warns(UserWarning, match="Compiler .* failed .*"):
             # pylint: disable=protected-access
-            CompilerDriver._attempt_link("cc", [""], "in.o", "out.so", None)
+            CompilerDriver._attempt_link("cc", [""], "in.o", "out.so", CompileOptions(verbose=True))
 
 
 class TestCompilerErrors:
@@ -142,9 +142,8 @@ def test_link_failure(self):
         with tempfile.NamedTemporaryFile(mode="w+", encoding="utf-8", suffix=".o") as invalid_file:
             invalid_file.write("These are invalid contents.")
             invalid_file.flush()
-            with pytest.raises(EnvironmentError, match="Unable to link .*"):
-                with pytest.warns(UserWarning, match="Compiler cc failed during execution"):
-                    CompilerDriver.run(invalid_file.name, fallback_compilers=["cc"])
+            with pytest.raises(CompileError, match="Unable to link .*"):
+                CompilerDriver.run(invalid_file.name, fallback_compilers=["cc"])
 
     @pytest.mark.parametrize(
         "pipeline",