From 975e2174e2b0f3988cd3a20dda32f1d04be7aab0 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Mon, 29 Aug 2022 23:48:41 +0000 Subject: [PATCH] [ci skip] Update docs + Add mechanism to skip validate check --- .github/ISSUE_TEMPLATE/bug-report.yml | 2 +- docs/Chipyard-Basics/Initial-Repo-Setup.rst | 29 ++++++++++++++++----- scripts/build-toolchain-extra.sh | 13 ++++++--- 3 files changed, 33 insertions(+), 11 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml index bcc09091..f06cf04d 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -31,7 +31,7 @@ body: description: OS setup for reproducibility placeholder: OS information value: | - Ex: Output of `uname -a` / `lsb_release -a` / `printenv` + Ex: Output of `uname -a` + `lsb_release -a` + `printenv` + `conda list` validations: required: true diff --git a/docs/Chipyard-Basics/Initial-Repo-Setup.rst b/docs/Chipyard-Basics/Initial-Repo-Setup.rst index 227da4a8..e2c91173 100644 --- a/docs/Chipyard-Basics/Initial-Repo-Setup.rst +++ b/docs/Chipyard-Basics/Initial-Repo-Setup.rst @@ -25,10 +25,14 @@ Default Requirements Installation In Chipyard, we use the `Conda `__ package manager to help manage system dependencies. Conda allows users to create an "environment" that holds system dependencies like ``make``, ``gcc``, etc. +.. Note:: Chipyard can also run on systems without a Conda installation. However, users on these systems must manually install toolchains and dependencies. + First Chipyard requires there to be Conda installed on the system. -Please refer to the `Conda installation instructions `__ on how to install Conda. +Please refer to the `Conda installation instructions `__ on how to install Conda with the Miniforge installer. Afterwards, verify that Conda is a sufficient version (we test on version 4.12.0/4.13.0 but higher is most likely fine). +.. Note:: If you have installed conda separately from this documentation (i.e. from miniconda or full Anaconda), please ensure you follow https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge to use ``conda-forge`` packages without any issues. + .. code-block:: shell conda --version # must be version 4.12.0 or higher @@ -81,7 +85,7 @@ Next go ahead and activate the conda environment that was setup. conda activate chipyard -We recommend that you add this "activate" command your ``.bashrc`` (or other environment setup file). +We recommend that you add this "activate" command to your ``.bashrc`` (or other environment setup file). Fetch Chipyard Sources ~~~~~~~~~~~~~~~~~~~~~~ @@ -102,19 +106,30 @@ Obtaining a Toolchain ------------------------ Currently there are two toolchains, one for normal RISC-V programs called ``riscv-tools``, and another for Hwacha/Gemmini called ``esp-tools``. -To get a basic ``riscv-tools`` installation (which is the only thing needed for most Chipyard use-cases), just the following steps are necessary. +To get a basic ``riscv-tools`` compiler installation (which is the only thing needed for most Chipyard use-cases), just the following steps are necessary. .. code-block:: shell - conda install -c ucb-bar riscv-tools # for a normal risc-v toolchain + conda install -c ucb-bar riscv-tools # for a normal risc-v compiler -.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should obtain the ``esp-tools`` toolchain by adding the ``esp-tools`` argument to the command above. +.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should obtain the ``esp-tools`` compiler by substituting the ``esp-tools`` argument to the command above. Once the command is run, the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables will be set properly. -.. Note:: If you are a power user and would like to build your own toolchain, you can refer to the https://github.com/ucb-bar/riscv-tools-feedstock and https://github.com/ucb-bar/esp-tools-feedstock repositories (submoduled in the ``toolchains`` directory) on how to build a toolchain yourself. +.. Note:: If you are a power user and would like to build your own compiler, you can refer to the https://github.com/ucb-bar/riscv-tools-feedstock and https://github.com/ucb-bar/esp-tools-feedstock repositories (submoduled in the ``toolchains`` directory) on how to build a toolchain yourself. -.. Note:: If can deactivate/activate a toolchain (but keep it installed) by running ``source $CONDA_PREFIX/etc/conda/deactivate.d/deactivate-${PKG_NAME}.sh`` or ``$CONDA_PREFIX/etc/conda/activate.d/activate-${PKG_NAME}.sh`` (``PKG_NAME`` for example is ``ucb-bar-riscv-tools``). This will modify the aforementioned 3 environment variables. +.. Note:: You can deactivate/activate a compiler/toolchain (but keep it installed) by running ``source $CONDA_PREFIX/etc/conda/deactivate.d/deactivate-${PKG_NAME}.sh`` or ``$CONDA_PREFIX/etc/conda/activate.d/activate-${PKG_NAME}.sh`` (``PKG_NAME`` for example is ``ucb-bar-riscv-tools``). This will modify the aforementioned 3 environment variables. + +Afterwards, we need to install extra toolchain utilities/tests used by Chipyard. +This is done by the following: + +.. code-block:: shell + + ./scripts/build-toolchain-extra.sh riscv-tools # or esp-tools respectively + +This command builds utilities like Spike, RISC-V Proxy Kernel, libgloss, and RISC-V tests from source for a specific toolchain type. + +.. Note:: By default, the ``build-toolchain-extra.sh`` script installs to ``$CONDA_PREFIX/``. Thus, if you uninstall the compiler using ``conda remove`` these utilities/tests will also have to be re-installed/built. Sourcing ``env.sh`` ------------------- diff --git a/scripts/build-toolchain-extra.sh b/scripts/build-toolchain-extra.sh index c347d4ac..dfdcbc9a 100755 --- a/scripts/build-toolchain-extra.sh +++ b/scripts/build-toolchain-extra.sh @@ -33,6 +33,7 @@ usage() { echo " --prefix PREFIX : Install destination. If unset, defaults to $CONDA_PREFIX/riscv-tools" echo " or $CONDA_PREFIX/esp-tools" echo " --clean-after-install : Run make clean in calls to module_make and module_build" + echo " --skip-validate : Skip prompt checking for conda" echo " --help -h : Display this message" exit "$1" } @@ -48,6 +49,7 @@ die() { TOOLCHAIN="riscv-tools" CLEANAFTERINSTALL="" RISCV="" +SKIP_VALIDATE=false # getopts does not support long options, and is inflexible while [ "$1" != "" ]; @@ -62,6 +64,9 @@ do CLEANAFTERINSTALL="true" ;; riscv-tools | esp-tools) TOOLCHAIN=$1 ;; + --skip-validate) + SKIP_VALIDATE=true; + ;; * ) error "invalid option $1" usage 1 ;; @@ -69,9 +74,11 @@ do shift done -if [ -z ${CONDA_DEFAULT_ENV+x} ]; then - error "ERROR: No conda environment detected. Did you activate the conda environment (e.x. 'conda activate chipyard')?" - exit 1 +if [ "$SKIP_VALIDATE" = false ]; then + if [ -z ${CONDA_DEFAULT_ENV+x} ]; then + error "ERROR: No conda environment detected. Did you activate the conda environment (e.x. 'conda activate chipyard')?" + exit 1 + fi fi if [ -z "$RISCV" ] ; then