Merge pull request #1374 from ucb-bar/upgrade-vlsi

docs/VLSI/Advanced-Usage.rst

@@ -3,14 +3,22 @@
 Advanced Usage
 ==============
 
-Hammer Development
+Hammer Development and Upgrades
-------------------
+-------------------------------
 If you need to develop Hammer within Chipyard or use a version of Hammer beyond the latest PyPI release, clone the `Hammer repository <https://github.com/ucb-bar/hammer>`__ somewhere else on your disk. Then:
 
 .. code-block:: shell
     
     pip install -e <path/to/hammer>
 
+To bump specific plugins to their latest commits and install them, you can use the upgrade script from the Chipyard root directory, with arguments for match patterns for the plugin names:
+
+.. code-block:: shell
+
+    ./scripts/upgrade-vlsi.sh <pattern(s)>
+
+If you would like to upgrade your Hammer installation to the latest PyPI release and bump all of your plugins at once, run the above script without arguments. WARNING: this may pull in plugin changes that are newer than the latest Hammer release and cause incompatibility issues.
+
 Alternative RTL Flows
 ---------------------
 The Make-based build system provided supports using Hammer without using RTL generated by Chipyard. To push a custom Verilog module through, one only needs to append the following environment variables to the ``make buildfile`` command (or edit them directly in the Makefile).

scripts/upgrade-vlsi.sh

@@ -1,8 +1,14 @@
 #!/usr/bin/env bash
 
+# This script updates Hammer and plugins.
+# ./scripts/upgrade-vlsi.sh <pattern(s)> will upgrade plugins matching the pattern list.
+# ./scripts/upgrade-vlsi.sh will upgrade all plugins and bump hammer-vlsi to the latest released version. Only do this upon a new Hammer release.
+
 # exit script if any command fails
 set -e
 set -o pipefail
+# except for grep in the pipe
+clgrep() { grep $@ || test $? = 1; }
 
 # exit script if not in Chipyard conda env
 if [[ `basename $CONDA_PREFIX` != .conda-env ]]; then
@@ -11,24 +17,31 @@ if [[ `basename $CONDA_PREFIX` != .conda-env ]]; then
 fi
 
 # Get hammer submodules
-package_names=$(git ls-files --stage | grep 160000 | awk '$4 ~/vlsi\/hammer.*/ {print $4}')
+if [ $# -gt 0 ]; then
-package_list=(${package_names})
+    patterns=()
-plen="${#package_list[@]}"
+    for arg in $@; do
-
+        patterns+=("-e" $arg)
-if [[ ${plen} -gt 0 ]]; then
-    for p in "${package_list[@]}"; do
-        cd ${p}
-        echo "Updating current directory: $PWD"
-        git checkout `basename "$(git rev-parse --abbrev-ref origin/HEAD)"`
-        git pull
-        cd - > /dev/null
-        git add ${p}
-        pip install -e ${p} --upgrade
     done
+    package_list=($(git ls-files --stage | grep 160000 | clgrep ${patterns[@]} | awk '$4 ~/vlsi\/hammer.*/ {print $4}'))
+else
+    package_list=($(git ls-files --stage | grep 160000 | awk '$4 ~/vlsi\/hammer.*/ {print $4}'))
+    # Also upgrade hammer-vlsi.
+    pip install hammer-vlsi --upgrade
 fi
 
-# Upgrade hammer-vlsi separately.
+# exit if requested package not found (case of an unmatched pattern in a list is not handled)
-pip install hammer-vlsi --upgrade
+if [ -z ${package_list} ]; then
-
+    echo "No Hammer plugins matching these patterns found: $@"
-
+    exit
+fi
 
+# upgrade to latest commit in default branch
+for p in ${package_list[@]}; do
+    echo "Updating ${p}"
+    cd ${p}
+    git checkout `basename "$(git rev-parse --abbrev-ref origin/HEAD)"`
+    git pull
+    cd - > /dev/null
+    git add ${p}
+    pip install -e ${p} --upgrade
+done