[Docs] Docker shell update (#1427)

* Docker shell update

---------

Signed-off-by: luarss <[email protected]>
Co-authored-by: Vitor Bandeira <[email protected]>

Author: luarss

docs/user/BuildWithDocker.md

@@ -85,6 +85,14 @@ make
 exit
 ```
 
+Alternatively you may also use the `docker_shell` utility as follows.
+It is important that you are in the `flow` directory. 
+
+```shell
+cd flow
+util/docker_shell make
+```
+
 ## Enable GUI support
 
 To use the GUI feature you will need to start the docker with the
@@ -112,10 +120,19 @@ Then use:
 docker run --rm -it -e DISPLAY=<IP_LIKE_FROM_TUTORIAL>:0 --network host --privileged <IMAGE_NAME>
 ```
 
-## Docker Shell Utility
+Alternatively, you may also use the `docker_shell` utility for GUI as follows. 
+It is important that you are in the `flow` directory. 
 
-Alternatively, use `docker_shell` to automate the above commands using the
-user's parameters. Do refer to the documentation [here](./DockerShell.md).
+```shell
+cd flow
+util/docker_shell gui_final
+```
+
+```{note}
+`docker_shell` is a helpful utility to automate the 
+aforementioned Docker commands using the user's parameters. 
+Do refer to the documentation [here](./DockerShell.md).
+```
 
 ## Build Docker Image for Different OS
 

docs/user/DockerShell.md

@@ -1,4 +1,62 @@
-```{include} ../../flow/util/README.md
+Building example design using Docker image
+==========================================
+
+The `docker_shell` script is used as a prefix to launch a command using a OpenROAD docker image.
+
+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
+./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
 ```
 
+If you have built your OpenROAD Docker image using prebuilt binaries, 
+you might want to source custom paths for your modules as follows.
+
+```
+OR_IMAGE=openroad_prebuilt_image YOSYS_CMD=/oss-cad-suite/bin/yosys 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/README.md

@@ -4,6 +4,9 @@ set -ex
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
 WORKSPACE=$(pwd)
+YOSYS_CMD=${YOSYS_CMD:-/OpenROAD-flow-scripts/tools/install/yosys/bin/yosys}
+OPENROAD_EXE=${OPENROAD_EXE:-/OpenROAD-flow-scripts/tools/install/OpenROAD/bin/openroad}
+KLAYOUT_CMD=${KLAYOUT_CMD:-/usr/bin/klayout}
 
 XSOCK=/tmp/.X11-unix
 XAUTH=/tmp/.docker.xauth
@@ -27,13 +30,15 @@ docker run -u $(id -u ${USER}):$(id -g ${USER}) \
  -e XAUTHORITY=$XAUTH \
  -e FLOW_HOME=/OpenROAD-flow-scripts/flow/ \
  -e MAKEFILES=/OpenROAD-flow-scripts/flow/Makefile \
- -v $WORKSPACE:`pwd` \
+ -e YOSYS_CMD=$YOSYS_CMD \
+ -e OPENROAD_EXE=$OPENROAD_EXE \
+ -e KLAYOUT_CMD=$KLAYOUT_CMD \
+ -v $WORKSPACE:/OpenROAD-flow-scripts/flow \
  --network host \
  $DOCKER_INTERACTIVE \
  ${OR_IMAGE:-openroad/flow-ubuntu22.04-builder:latest} \
  bash -c "set -ex
  mkdir /tmp/xdg-run
- . ./env.sh
- cd $WORKSPACE
+ cd /OpenROAD-flow-scripts/flow
  $ARGUMENTS
 "