Merge pull request #1091 from Pinata-Consulting/docker-run-script

docker: add a ./or script to run GUI from within docker image

Author: maliberty

flow/util/README.md

@@ -0,0 +1,59 @@
+Building example design using Docker image
+==========================================
+
+The `docker_shell` script is used as a prefix to launch a command within the OpenROAD docker image.
+
+This script is set up to run the OpenROAD GUI from
+within the Docker image on the host platform.
+
+Also, the current working directory is mapped into the Docker image using the current user's credentials.
+
+Build docker image
+------------------
+
+First build the docker image:
+
+```
+cd OpenROAD-flow-scripts
+sudo ./setup.sh
+./build_openroad.sh
+```
+
+Build an example design and run the GUI:
+
+```
+cd flow
+util/docker_shell make
+util/docker_shell make gui_final
+```
+
+You can also launch an interactive bash session:
+
+```
+util/docker_shell bash
+```
+
+If you need to use a different Docker image than default, override by using the `docker_shell_IMAGE`
+environment variable:
+
+```
+OR_IMAGE=openroad/flow-centos7-builder:v1234 util/docker_shell make
+```
+
+Using `docker_shell` from outside of `OpenROAD-flow-scripts/flow` folder
+------------------------------------------------------------------------
+
+If you have designs you are keeping in a git source repository that is not
+a fork of the OpenROAD-flow-scripts git repository, you can still use
+the `docker_shell` script.
+
+Two ways to use `docker_shell`
+
+1. Simply invoke it from the ORFS location.
+2. Copy the script into your source folder. This would allow you
+   to build and publish a Docker image to a private Docker repository
+   and lock the ORFS version to the version of your source code. This
+   gives you a way to deploy updates of ORFS
+   easily, publish a new Docker image, modify the copy of `docker_shell`
+   and create a pull request to possibly test your upgrade on your private
+   build serves.

flow/util/docker_shell

@@ -0,0 +1,37 @@
+#!/bin/bash
+set -ex
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+WORKSPACE=$(pwd)
+
+XSOCK=/tmp/.X11-unix
+XAUTH=/tmp/.docker.xauth
+xauth nlist :0 | sed -e 's/^..../ffff/' | xauth -f $XAUTH nmerge -
+ARGUMENTS=$@
+
+if test -t 0; then
+    DOCKER_INTERACTIVE=-ti
+fi
+
+# Most of these options below has to do with allowing to
+# run the OpenROAD GUI from within Docker.
+docker run -u $(id -u ${USER}):$(id -g ${USER}) \
+ -e LIBGL_ALWAYS_SOFTWARE=1 \
+ -e "QT_X11_NO_MITSHM=1" \
+ -e XDG_RUNTIME_DIR=/tmp/xdg-run \
+ -e DISPLAY=$DISPLAY \
+ -e QT_XKB_CONFIG_ROOT=/usr/share/X11/xkb \
+ -v $XSOCK:$XSOCK \
+ -v $XAUTH:$XAUTH \
+ -e XAUTHORITY=$XAUTH \
+ -e FLOW_HOME=/OpenROAD-flow-scripts/flow/ \
+ -e MAKEFILES=/OpenROAD-flow-scripts/flow/Makefile \
+ -v $WORKSPACE:`pwd` \
+ $DOCKER_INTERACTIVE \
+ ${OR_IMAGE:-openroad/flow-centos7-builder:latest} \
+ bash -c "set -ex
+ mkdir /tmp/xdg-run
+ . ./env.sh
+ cd $WORKSPACE
+ $ARGUMENTS
+"