Add documentation for required dependencies and fix build-setup.sh issues

[StephenMoreOSU]

Background Work

• Yes, I searched the mailing list
• Yes, I searched the documentation

Feature Description

Chipyard Version and Hash

hash: 69eba86
version: 1.13.0

Steps taken / Explanation

When cloning a fresh repo and following the instructions in the initial setup docs I found that I would encounter a series of errors. I was able to fix them but the amount of effort required to get chipyard up and running could be reduced by adding a few things in the documentation and a minor modification of the build-setup.sh script.

Errors encountered

1. conda-lock is not mentioned explicitly as a dependency to chipyard. It should be added to docs mentioning it as a dependency to make this clear.

2. As mentioned in issues Build-setup issue #2016 and build-setup.sh $(which conda) returns function #2002, the conda binary path provided to conda-lock in the build-setup.sh script uses $(which conda) as shown here. For me and in the referenced issues, this results in providing a bash function to the conda-lock command rather than the expected binary path which results in an error that looks something like this:

Error: Got unexpected extra arguments ({ \local cmd="${1-__missing__}"; case "$cmd" in activate | deactivate) __conda_activate "$@" ;; install | update | upgrade | remove | uninstall) __conda_exe "$@" || \return; __conda_reactivate ;; *) __conda_exe "$@" ;; esac } ~/chipyard/conda-reqs/conda-lock-reqs/conda-requirements-riscv-tools-linux-64.conda-lock.yml)
+ exit_if_last_command_failed
+ local exitcode=2
+ '[' 2 -ne 0 ']'
+ die 'Build script failed with exit code 2 at step 1: Conda environment setup' 2
+ error 'Build script failed with exit code 2 at step 1: Conda environment setup'
+ echo 'build-setup.sh: Build script failed with exit code 2 at step 1: Conda environment setup'
build-setup.sh: Build script failed with exit code 2 at step 1: Conda environment setup
+ exit 2

This issue may come from using a different conda installer than miniforge as recommended in the docs but I feel that as conda is widely used it would be common for many people to already have it on their systems (I personally had used the miniconda installer) which makes this worth fixing or at least mentioning in documentation.

3. Once the build script gets to step 9, Pre-compiling FireMarshal buildroot sources, I encountered the following error:

TaskError - taskid:~/chipyard/software/firemarshal/images/firechip/br-base/br-base.img
PythonAction Error
Traceback (most recent call last):
  File "~/chipyard/.conda-env/lib/python3.10/site-packages/doit/action.py", line 461, in execute
    returned_value = self.py_callable(*self.args, **kwargs)
  File "~/chipyard/software/firemarshal/wlutil/build.py", line 603, in makeImage
    wlutil.applyOverlay(config['img'], config['overlay'])
  File "~/chipyard/software/firemarshal/wlutil/wlutil.py", line 753, in applyOverlay
    copyImgFiles(img, flist, 'in')
  File "~/chipyard/software/firemarshal/wlutil/wlutil.py", line 702, in copyImgFiles
    with mountImg(img, getOpt('mount-dir')):
  File "~/chipyard/.conda-env/lib/python3.10/contextlib.py", line 135, in __enter__
    return next(self.gen)
  File "~/chipyard/software/firemarshal/wlutil/wlutil.py", line 629, in mountImg
    run(['guestmount', '--pid-file', pidPath, '-o', f'uid={uid}', '-o', f'gid={gid}', '-a', imgPath, '-m', '/dev/sda', mntPath])
  File "~/chipyard/software/firemarshal/wlutil/wlutil.py", line 521, in run
    p = sp.Popen(*args, universal_newlines=True, stderr=sp.STDOUT, stdout=sp.PIPE, **kwargs)
  File "~/chipyard/.conda-env/lib/python3.10/subprocess.py", line 971, in __init__
    self._execute_child(args, executable, preexec_fn, close_fds,
  File "~/chipyard/.conda-env/lib/python3.10/subprocess.py", line 1863, in _execute_child
    raise child_exception_type(errno_num, err_msg, err_filename)
FileNotFoundError: [Errno 2] No such file or directory: 'guestmount'

ERROR: Failed to build workload br-base.json
Log available at: ~/chipyard/software/firemarshal/logs/br-base-build-2024-10-04--21-56-16-RT61S0E381MW2VGG.log
ERROR: FAILURE: 1 builds failed
build-setup.sh: Build script failed with exit code 1 at step 9: Pre-compiling FireMarshal buildroot sources

This turned out to be from my system not containing the guestmount binary on its PATH. This could be fixed by adding guestmount as a dependency for chipyard in the docs.

Once I added the above fixes I was able to run the script to completion.
I'd be happy to submit a PR to include these fixes on the docs but I'm a bit unclear on the contribution guidelines so will leave it with this issue.

Motivating Example

It would be useful for users to be able to look at the getting started page and have everything work out of the box rather than having to debug the build-setup script themselves.