Features/build instructions (#697)

* init command

* add spack-python script to find 'the one main root' of an experiment

* add in part that dumps the build log

* add env vars; also take initial build log and try to extract just the build commands (not 100% accurate yet)

* style fix

* style fix

* unnecessary import

* Create showBuild.rst

* Adding showBuild to index/scripts

---------

Co-authored-by: pearce8 <pearce8@llnl.gov>
Co-authored-by: Stephanie Brink <brink2@llnl.gov>
Co-authored-by: Riyaz Haque <5333387+rfhaque@users.noreply.github.com>

Author: 4 people

docs/index.rst

@@ -43,18 +43,6 @@
    set-of-experiments
    run-binary
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Benchpark Utils
-
-   diffBuildSpecs
-   diffExperimentBuilds
-   diffExperimentSpecs
-   diffPackageCommits
-   diffSystemSpecs
-   scripts
-   developer-scripts
-
 .. toctree::
    :maxdepth: 1
    :caption: Contributing
@@ -65,6 +53,17 @@
    add-a-dryrun
    update-a-system-config
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Benchpark Utils
+
+   diffBuildSpecs
+   diffExperimentBuilds
+   diffExperimentSpecs
+   diffPackageCommits
+   diffSystemSpecs
+   showBuild
+
 .. toctree::
    :maxdepth: 2
    :caption: API Docs

docs/showBuild.rst

@@ -0,0 +1,31 @@
+.. Copyright 2023 Lawrence Livermore National Security, LLC and other
+   Benchpark Project Developers. See the top-level COPYRIGHT file for details.
+
+   SPDX-License-Identifier: Apache-2.0
+
+
+=============================================
+Show how Benchpark/Spack Built the Experiment
+=============================================
+
+If you create a Ramble workspace with Benchpark:
+
+```
+bin/benchpark experiment init --dest=def-raja-perf raja-perf
+bin/benchpark system init --dest=def-ruby llnl-cluster cluster=ruby compiler=gcc
+bin/benchpark setup def-raja-perf/ def-ruby/ workspace/
+. `pwd`/workspace/setup.sh
+ramble --disable-progress-bar --workspace-dir `pwd`/workspace/def-raja-perf/def-ruby/workspace workspace setup
+```
+
+You will now be able to `benchpark show-build dump`, a command that will dump a log of how Spack built the experiment:
+
+```
+bin/benchpark show-build dump /usr/workspace/scheibel/oslic/benchpark2/workspace/def-raja-perf/def-ruby/workspace/ build-test/
+```
+
+for this example, it will add the following artifacts to `build-test/`
+
+1. `build-raja-perf.log`: a full log of all build commands and their output
+2. `extracted-commands.txt`: [1] but with most output filtered out (generally much easier to understand what commands to run to do the build)
+3. `spack-build-env.txt`: the environment variables set at build time

lib/benchpark/cmd/show_build.py

@@ -0,0 +1,87 @@
+# Copyright 2023 Lawrence Livermore National Security, LLC and other
+# Benchpark Project Developers. See the top-level COPYRIGHT file for details.
+#
+# Copyright 2013-2023 Spack Project Developers.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import os.path
+import re
+import shutil
+
+import benchpark.paths
+from benchpark.runtime import run_command
+
+
+def _find_env_root(basedir):
+    for root, _, fnames in os.walk(basedir):
+        if "spack.yaml" in fnames:
+            return root
+    raise Exception(f"Could not find spack.yaml in {basedir}")
+
+
+def extract_build_commands(log_file):
+    extracted = []
+    with open(log_file, "r", encoding="utf-8") as f:
+        for line in f.readlines():
+            match = re.match(r"^==>\s*\[.*\]\s*(\S.*)", line)
+            if not match:
+                continue
+            extract = match.group(1)
+            if any(x in extract for x in ["cmake", "configure", "make"]):
+                extracted.append(extract)
+    return extracted
+
+
+def show_build_dump(args):
+    env_root = _find_env_root(args.workspace)
+
+    determine_exp = os.path.join(
+        benchpark.paths.benchpark_root, "lib", "scripts", "determine-exp.py"
+    )
+    out, err = run_command(f"spack -e {env_root} python {determine_exp}")
+    experiment_name = out.strip()
+
+    logs_out = os.path.join(args.destdir, f"build-{experiment_name}.log")
+    if not os.path.exists(logs_out):
+        with open(logs_out, "w") as f:
+            run_command(f"spack -e {env_root} logs {experiment_name}", stdout=f)
+
+    build_cmds = extract_build_commands(logs_out)
+    cmds_out = os.path.join(args.destdir, "extracted-commands.txt")
+    if not os.path.exists(cmds_out):
+        with open(cmds_out, "w", encoding="utf-8") as f:
+            for cmd in build_cmds:
+                f.write(f"{cmd}\n")
+
+    # Spack also stores env vars for the build in the install dir, copy them
+    out, err = run_command(f"spack -e {env_root} location -i {experiment_name}")
+    install_location = out.strip()
+    env_vars_path = os.path.join(install_location, ".spack", "spack-build-env.txt")
+    env_vars_out = os.path.join(args.destdir, os.path.basename(env_vars_path))
+    if not os.path.exists(env_vars_out):
+        shutil.copy(env_vars_path, env_vars_out)
+
+
+def setup_parser(root_parser):
+    show_build_subparser = root_parser.add_subparsers(dest="show_build_subcommand")
+
+    dump_parser = show_build_subparser.add_parser("dump")
+    dump_parser.add_argument(
+        "workspace",
+        help="A Ramble workspace you want to want to generate build instructions for",
+    )
+    dump_parser.add_argument("destdir", help="Put all needed resources here")
+
+
+def command(args):
+    actions = {
+        "dump": show_build_dump,
+    }
+    if args.show_build_subcommand in actions:
+        actions[args.show_build_subcommand](args)
+    else:
+        raise ValueError(
+            f"Unknown subcommand for 'show-build': {args.show_build_subcommand}"
+        )

lib/benchpark/runtime.py

@@ -39,21 +39,23 @@ def git_clone_commit(url, commit, destination):
         run_command(f"git checkout {commit}")
 
 
-def run_command(command_str, env=None):
+def run_command(command_str, env=None, stdout=None, stderr=None):
+    stdout = stdout or subprocess.PIPE
+    stderr = stderr or subprocess.PIPE
     proc = subprocess.Popen(
         shlex.split(command_str),
         env=env,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
+        stdout=stdout,
+        stderr=stderr,
         text=True,
     )
-    stdout, stderr = proc.communicate()
+    out, err = proc.communicate()
     if proc.returncode != 0:
         raise RuntimeError(
             f"Failed command: {command_str}\nOutput: {stdout}\nError: {stderr}"
         )
 
-    return (stdout, stderr)
+    return (out, err)
 
 
 class Command:

lib/main.py

@@ -43,6 +43,7 @@
 import benchpark.cmd.system  # noqa: E402
 import benchpark.cmd.experiment  # noqa: E402
 import benchpark.cmd.setup  # noqa: E402
+import benchpark.cmd.show_build  # noqa: E402
 import benchpark.cmd.unit_test  # noqa: E402
 import benchpark.cmd.info  # noqa: E402
 import benchpark.cmd.list  # noqa: E402
@@ -190,6 +191,11 @@ def init_commands(subparsers, actions_dict):
     )
     benchpark.cmd.info.setup_parser(info_parser)
 
+    show_build_parser = subparsers.add_parser(
+        "show-build", help="Show how spack built a benchmark"
+    )
+    benchpark.cmd.show_build.setup_parser(show_build_parser)
+
     list_parser = subparsers.add_parser(
         "list", help="List experiments, systems, benchmarks, and modifiers"
     )
@@ -206,6 +212,7 @@ def init_commands(subparsers, actions_dict):
     actions_dict["unit-test"] = benchpark.cmd.unit_test.command
     actions_dict["audit"] = benchpark.cmd.audit.command
     actions_dict["info"] = benchpark.cmd.info.command
+    actions_dict["show-build"] = benchpark.cmd.show_build.command
     actions_dict["list"] = benchpark.cmd.list.command
     if analyze_installed:
         benchpark.cmd.analyze.setup_parser(analyze_parser)

lib/scripts/determine-exp.py

@@ -0,0 +1,15 @@
+import spack.environment as ev
+
+
+def main():
+    x = ev.active_environment()
+    y = list(x.concrete_roots())
+    # There may be multiple roots in the env. Assume that the experiment of
+    # interest is the largest dag (every other root should just be an attempt
+    # to constrain dependencies of this experiment).
+    z = max(y, key=lambda i: sum(1 for _ in i.traverse()))
+    print(z.name)
+
+
+if __name__ == "__main__":
+    main()