Check that FireSim is running on tagged branch (#931)

* Check for tagged release in build-setup

* Bump CI to work with tag validate

* Autogen tag for docs | Misc. updates

* Forgot a n

* [ci skip] update comments

* Small update to comment [ci skip]

.github/scripts/initialize-manager.py

@@ -31,7 +31,7 @@ def initialize_manager(max_runtime):
             run("git clone {} {}".format(ci_workdir, manager_fsim_dir))
 
         with cd(manager_fsim_dir):
-            run("./build-setup.sh --fast")
+            run("./build-setup.sh --fast --skip-validate")
 
         # Initialize marshal submodules early because it appears some form of
         # contention between submodule initialization and the jgit SBT plugin

.readthedocs.yml

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

build-setup-nolog.sh

@@ -19,15 +19,17 @@ RDIR=$(pwd)
 FASTINSTALL=false
 IS_LIBRARY=false
 SKIP_TOOLCHAIN=false
+SKIP_VALIDATE=false
 
 function usage
 {
-    echo "usage: build-setup.sh [ fast | --fast] [--skip-toolchain] [--library]"
+    echo "usage: build-setup.sh [ fast | --fast] [--skip-toolchain] [--library] [--skip-validate]"
     echo "   fast: if set, pulls in a pre-compiled RISC-V toolchain for an EC2 manager instance"
     echo "   skip-toolchain: if set, skips RISC-V toolchain handling (cloning or building)."
     echo "                   The user must define $RISCV in their env to provide their own toolchain."
     echo "   library: if set, initializes submodules assuming FireSim is being used"
     echo "            as a library submodule. Implies --skip-toolchain "
+    echo "   skip-validate: if set, skips checking if user is on release tagged branch"
 }
 
 if [ "$1" == "--help" -o "$1" == "-h" -o "$1" == "-H" ]; then
@@ -48,6 +50,9 @@ do
         --skip-toolchain)
             SKIP_TOOLCHAIN=true;
             ;;
+        --skip-validate)
+            SKIP_VALIDATE=true;
+            ;;
         -h | -H | --help)
             usage
             exit
@@ -64,6 +69,21 @@ do
     shift
 done
 
+# 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 FireSim.\nType \"y\" to continue if this is intended, otherwise see https://docs.fires.im/en/stable/Initial-Setup/Setting-up-your-Manager-Instance.html#setting-up-the-firesim-repo: " validate
+        [[ $validate == [yY] ]] || exit 5
+        echo "Setting up non-official FireSim release"
+    fi
+else
+    echo "Setting up official FireSim release: $tag"
+fi
+
 if [ "$SKIP_TOOLCHAIN" = true ]; then
     if [ -z "$RISCV" ]; then
         echo "ERROR: You must set the RISCV environment variable before running"

docs/Initial-Setup/Setting-up-your-Manager-Instance.rst

@@ -95,12 +95,17 @@ Setting up the FireSim Repo
 
 We're finally ready to fetch FireSim's sources. Run:
 
-::
+.. parsed-literal::
 
     git clone https://github.com/firesim/firesim
     cd firesim
+    # checkout latest official firesim release
+    # note: this may not be the latest release if the documentation version != "stable"
+    git checkout |version|
     ./build-setup.sh fast
 
+The ``build-setup.sh`` script will validate that you are on a tagged branch,
+otherwise it will prompt for confirmation.
 This will have initialized submodules and installed the RISC-V tools and
 other dependencies.
 

docs/conf.py

@@ -8,6 +8,7 @@
 
 import shutil
 import os
+import subprocess
 
 # -- Path setup --------------------------------------------------------------
 
@@ -19,18 +20,37 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-
 # -- Project information -----------------------------------------------------
 
 project = u'FireSim'
 copyright = u'2018, Sagar Karandikar, Howard Mao, Donggyu Kim, David Biancolin, Alon Amid, and Berkeley Architecture Research'
 author = u'Sagar Karandikar, Howard Mao, Donggyu Kim, David Biancolin, Alon Amid, and Berkeley Architecture Research'
 
-# 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
 
 # -- General configuration ---------------------------------------------------
 
@@ -115,6 +135,15 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'FireSimdoc'
 
+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 @@
-.. FireSim documentation master file, created by
-   sphinx-quickstart on Thu Apr 26 23:51:51 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to FireSim's documentation!
-===================================
+Welcome to FireSim's documentation (version "|version|")!
+===========================================================
 
 New to FireSim? Jump to the :ref:`firesim-basics` page for more info.