Merge pull request #1114 from ucb-bar/check-for-tagged

Check that Chipyard is running a tagged release

.github/scripts/remote-do-rtl-build.sh

@@ -15,7 +15,7 @@ SCRIPT_DIR="$( cd "$( dirname "$0" )" && pwd )"
 source $SCRIPT_DIR/defaults.sh
 
 cd $REMOTE_CHIPYARD_DIR
-./scripts/init-submodules-no-riscv-tools.sh
+./scripts/init-submodules-no-riscv-tools.sh --skip-validate
 ./scripts/init-fpga.sh
 
 TOOLS_DIR=$REMOTE_RISCV_DIR

.github/scripts/remote-run-firesim-scala-tests.sh

@@ -18,7 +18,7 @@ export PATH="$RISCV/bin:$PATH"
 # This would generally be handled by build-setup.sh/firesim-setup.sh
 REMOTE_FIRESIM_SYSROOT=$REMOTE_FIRESIM_DIR/lib-install
 
-./scripts/init-submodules-no-riscv-tools.sh
+./scripts/init-submodules-no-riscv-tools.sh --skip-validate
 cd $REMOTE_CHIPYARD_DIR/sims/firesim/sim/firesim-lib/src/main/cc/lib
 git submodule update --init elfutils libdwarf
 cd $REMOTE_CHIPYARD_DIR/sims/firesim

.readthedocs.yml

@@ -1,7 +1,16 @@
 version: 2
+
+build:
+    os: ubuntu-20.04
+    tools:
+        python: "3.6"
+
 formats: all
+
 sphinx:
-  configuration: docs/conf.py
+    configuration: docs/conf.py
+    fail_on_warning: true
+
 python:
-   install:
-      - requirements: docs/requirements.txt
+    install:
+        - requirements: docs/requirements.txt

docs/Chipyard-Basics/Initial-Repo-Setup.rst

@@ -29,13 +29,17 @@ Setting up the Chipyard Repo
 
 Start by fetching Chipyard's sources. Run:
 
-.. code-block:: shell
+.. parsed-literal::
 
     git clone https://github.com/ucb-bar/chipyard.git
     cd chipyard
+    # checkout latest official chipyard release
+    # note: this may not be the latest release if the documentation version != "stable"
+    git checkout |version|
     ./scripts/init-submodules-no-riscv-tools.sh
 
 This will initialize and checkout all of the necessary git submodules.
+This will also validate that you are on a tagged branch, otherwise it will prompt for confirmation.
 
 When updating Chipyard to a new version, you will also want to rerun this script to update the submodules.
 Using git directly will try to initialize all submodules; this is not recommended unless you expressly desire this behavior.

docs/conf.py

@@ -20,6 +20,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import os
+import subprocess
 
 # -- General configuration ------------------------------------------------
 
@@ -59,11 +61,32 @@
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
-# The short X.Y version.
-version = u''
-# The full version, including alpha/beta/rc tags.
-release = u''
+
+on_rtd = os.environ.get("READTHEDOCS") == "True"
+if on_rtd:
+    for item, value in os.environ.items():
+        print("[READTHEDOCS] {} = {}".format(item, value))
+
+if on_rtd:
+    rtd_version = os.environ.get("READTHEDOCS_VERSION")
+    if rtd_version == "latest":
+        version = "main" # TODO: default to what "latest" points to
+    elif rtd_version == "stable":
+        # get the latest git tag (which is what rtd normally builds under "stable")
+        # this works since rtd builds things within the repo
+        process = subprocess.Popen(["git", "describe", "--exact-match", "--tags"], stdout=subprocess.PIPE)
+        output = process.communicate()[0].decode("utf-8").strip()
+        if process.returncode == 0:
+            version = output
+        else:
+            version = "v?.?.?" # this should not occur as "stable" is always pointing to tagged version
+    else:
+        version = rtd_version # name of a branch
+else:
+    version = "v?.?.?"
+
+# for now make these match
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -132,6 +155,17 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Chipyarddoc'
 
+# -- Misc Options ---------------------------------------------------------
+
+html_context = {
+    "version": version
+}
+
+# add rst to end of each rst source file
+# can put custom strings here that are generated from this file
+rst_epilog = f"""
+.. |overall_version| replace:: {version}
+"""
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/index.rst

@@ -1,10 +1,5 @@
-.. Chipyard documentation master file, created by
-   sphinx-quickstart on Fri Mar  8 11:46:38 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Chipyard's documentation!
-====================================
+Welcome to Chipyard's documentation (version "|version|")!
+==========================================================
 
 .. image:: ./_static/images/chipyard-logo.svg
 

scripts/firesim-setup.sh

@@ -13,5 +13,5 @@ cd "${scripts_dir}/.."
 # Reenable the FireSim submodule
 git config --unset submodule.sims/firesim.update || true
 cd sims/firesim
-./build-setup.sh "$@" --library
+./build-setup.sh "$@" --library --skip-validate
 cd "$RDIR"

scripts/init-submodules-no-riscv-tools-nolog.sh

@@ -4,6 +4,34 @@
 set -e
 set -o pipefail
 
+SKIP_VALIDATE=false
+
+function usage
+{
+    echo "Usage: $0 [--skip-validate]"
+    echo "Initialize Chipyard submodules and setup initial env.sh script."
+    echo ""
+    echo "  --skip-validate    Skip prompt checking for tagged release"
+}
+
+while test $# -gt 0
+do
+   case "$1" in
+        --skip-validate)
+            SKIP_VALIDATE=true;
+            ;;
+        -h | -H | --help)
+            usage
+            exit 1
+            ;;
+        *) echo "ERROR: bad argument $1"
+            usage
+            exit 2
+            ;;
+    esac
+    shift
+done
+
 # Check that git version is at least 1.7.8
 MYGIT=$(git --version)
 MYGIT=${MYGIT#'git version '} # Strip prefix
@@ -17,6 +45,21 @@ if [ "$MINGIT" != "$(echo -e "$MINGIT\n$MYGIT" | sort -V | head -n1)" ]; then
   false
 fi
 
+# before doing anything verify that you are on a release branch/tag
+set +e
+tag=$(git describe --exact-match --tags)
+tag_ret_code=$?
+set -e
+if [ $tag_ret_code -ne 0 ]; then
+    if [ "$SKIP_VALIDATE" = false ]; then
+        read -p "WARNING: You are not on an official release of Chipyard.\nType \"y\" to continue if this is intended, otherwise see https://chipyard.readthedocs.io/en/stable/Chipyard-Basics/Initial-Repo-Setup.html#setting-up-the-chipyard-repo: " validate
+        [[ $validate == [yY] ]] || exit 3
+        echo "Setting up non-official Chipyard release"
+    fi
+else
+    echo "Setting up official Chipyard release: $tag"
+fi
+
 # On macOS, use GNU readlink from 'coreutils' package in Homebrew/MacPorts
 if [ "$(uname -s)" = "Darwin" ] ; then
     READLINK=greadlink