[Docs] FAQ Update + Support for WSL (#1140)

* FAQ change for update ORFS
* modified build_openroad and build with docker instruction
* WSL instructions, pictures to b added
* made changes to dev guide and toc, prebuilt instructions, WSL instructions
Signed-off-by: luarss <[email protected]>

Author: luarss

build_openroad.sh

@@ -251,8 +251,8 @@ __docker_build()
                 cp .dockerignore{,.bak}
                 sed -i '/flow\/platforms/d' .dockerignore
         fi
-        ./etc/DockerHelper.sh create -target=dev -os="${DOCKER_OS_NAME}"
-        ./etc/DockerHelper.sh create -target=builder -os="${DOCKER_OS_NAME}"
+        ./etc/DockerHelper.sh create -target=dev -os="${DOCKER_OS_NAME}" -threads="${PROC}"
+        ./etc/DockerHelper.sh create -target=builder -os="${DOCKER_OS_NAME}" -threads="${PROC}"
         if [ ! -z "${DOCKER_COPY_PLATFORMS+x}" ]; then
                 mv .dockerignore{.bak,}
         fi

docs/contrib/DeveloperGuide.md

@@ -1,9 +1,6 @@
 # Developer Guide
 
-## Building
-
-Instructions for building are available [here](../index.md#getting-started-with-openroad-flow-scripts).
-
-## Logger
-
-Instructions for logging are available on [OpenROAD documentation](https://openroad.readthedocs.io/en/latest/contrib/Logger.html).
+- Integrate a new platform to OpenROAD Flow: [Guide](./PlatformBringUp.md).
+- Adding a new design: [Guide](../user/AddingNewDesign.md).
+- Continuous Integration: [Guide](./CI.md).
+- How do I update the codebase? There are different ways to update your codebase depending on the method you installed it. We provide detailed instructions in this [guide](../user/FAQS.md).

docs/images/wsl_1.webp

@@ -46,17 +46,18 @@ with 24-hour turnaround time.
 To build the binaries and run `gcd` through the flow:
 
 - Minimum: 1 CPU core and 8GB RAM.
-- Recommend: 4 CPU cores and 16GB of RAM.
+- Recommended: 4 CPU cores and 16GB of RAM.
 
 > **Note** `gcd` is a small design, and thus requires less computational power.
 > Larger designs may require better hardware.
 
 #### Build or Installing ORFS Dependencies
 
-We support three major ways of installation:
+We support four major ways of installation:
 
 - [Docker](./user/BuildWithDocker.md)
 - [Pre-built Binaries](./user/BuildWithPrebuilt.md)
+- [Windows Subsystem for Linux (WSL)](./user/BuildWithWSL.md)
 - [Local Installation](./user/BuildLocally.md)
 
 You may also choose use the build script to customise your build process.

docs/images/wsl_2.webp

@@ -26,12 +26,7 @@ entries:
   title: Getting Involved
 
 - file: contrib/DeveloperGuide.md
-  title: Developer Guide
-  entries:
-  - file: contrib/PlatformBringUp.md
-    title: Guide to Integrate a New Platform into the OpenROAD Flow
-  - file: contrib/CI.md
-    title: CI
+  title: Developer's Guide
 
 - file: contrib/CODE_OF_CONDUCT.md
   title: Code of Conduct

docs/index.md

@@ -38,11 +38,10 @@ cd OpenROAD-flow-scripts
 
 ## Verify Installation
 
-The binaries are only available from inside the Docker container, thus to
-start one use:
+The binaries are only available from inside a Docker container. Here is an example of starting a container from the created Docker image. 
 
 ``` shell
-docker run --rm -it -u $(id -u ${USER}):$(id -g ${USER}) -v $(pwd)/flow:/OpenROAD-flow-scripts/flow openroad/flow-$OS_NAME-builder
+docker run --rm -it -u $(id -u ${USER}):$(id -g ${USER}) -v $(pwd)/flow:/OpenROAD-flow-scripts/flow openroad/flow-centos7-builder
 ```
 
 Then, inside docker:

docs/toc.yml

@@ -7,6 +7,8 @@ Instructions for installing:
 - [Klayout>=0.28.8](https://www.klayout.de/build.html)
 - [Yosys>=0.21](https://github.com/YosysHQ/oss-cad-suite-build/blob/master/README.md#installation)
 
+> **TIP**: Unfortunately KLayout maintainers do not provide Debian 10/11 compatible packages. You can follow the build-from-sources instruction (Version >=0.25) and Ubuntu 22 instructions [here](https://www.klayout.de/build.html#:~:text=Building%20KLayout%20on%20Linux%20(Version%20%3E%3D%200.25)). 
+
 ## Install OpenROAD
 Download pre-built binaries with self-contained dependencies
 included from the Precision Innovations' Github releases
@@ -39,7 +41,10 @@ git clone https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts.git
 ```
 Export path variables accordingly.
 ```
-export PATH="<extracted_location>/oss-cad-suite/bin:$PATH" #yosys
+export PATH="<yosys_location>/bin:$PATH" 
+export PATH="<klayout_location>/bin:$PATH" # only if built from source
+export LD_LIBRARY_PATH="<klayout_location>/bin:$PATH" # only if built from source
+
 yosys -help
 openroad -help
 cd flow

docs/user/BuildWithDocker.md

@@ -0,0 +1,39 @@
+# Build with WSL
+Windows Subsystem for Linux, or WSL for short is a way for you to mount a Linux-based OS onto your Windows machine, allowing you to build OpenROAD-flow-scripts both locally and via Docker. 
+
+## Install WSL
+Instructions to install WSL can be found [here](https://learn.microsoft.com/en-us/windows/wsl/install). You may use any kernel supported, such as: CentOS 7, Ubuntu 20.04, Ubuntu 22.04, RHEL 8, Debian 10 and Debian 11.
+
+We recommend that users follow the Docker build by continuing onto the guide below. However, if you wish to install locally, you may follow the build locally instructions [here](./BuildLocally.md).
+
+> **TIP**: You may delete your WSL kernel using this [guide](https://pureinfotech.com/remove-linux-distro-wsl/).
+
+
+## Docker configuration
+This section assumes you have set up Docker for Windows already. If not, please refer to the Docker official website for instructions [here](https://docs.Docker.com/desktop/install/windows-install/).
+
+You need to enable the following options to allow WSL to use Docker. 
+
+General > Use the WSL 2 Based engine (should be default selection)
+![WSL1](../images/wsl_1.webp)
+
+Resources > WSL integration > Enable integration with my default WSL distro and select "Ubuntu-22.04", or the distribution you installed.  
+![WSL2](../images/wsl_2.webp)
+
+## Accessing WSL
+You may access WSL from the app named "Ubuntu 22.04 LTS". Run the following:
+```
+sudo apt-get update; sudo apt-get upgrade; sudo apt install -y build-essential python3 python3-venv python3-pip make
+```
+Verify if Docker is running
+```
+docker run hello-world
+```
+You should see:
+
+```
+Hello from Docker!
+This message shows that your installation appears to be working correctly.
+```
+
+If everything is successful up to this point, congratulations! You are now ready to follow the [Docker guide](./BuildWithDocker.md) as you have configured a Linux system with necessary dependencies. 

docs/user/BuildWithPrebuilt.md

@@ -14,6 +14,32 @@ the appropriate repository or start a discussion.
 Thank you for your willingness to contribute. Please see the
 [Getting Involved](../contrib/GettingInvolved) guide.
 
+## How do I update OpenROAD-flow scripts?
+
+Depending on how you installed OpenROAD-flow-scripts, there are different ways of updating. Regardless, here are the common first steps:
+
+```
+cd OpenROAD-flow-scripts
+git checkout master
+git pull
+```
+
+Now your local copy of ORFS should be up-to-date. The next step is to build it again with the following command: 
+
+For WSL/docker based installation, run:
+```
+./build_openroad.sh --clean
+```
+
+For local installation, run:
+```
+./build_openroad.sh --local --clean
+```
+
+For pre-built binaries, you can run the flow after `git pull` is done.
+
+> **TIP**: For development purposes, it is a good practice to work on branches and leave master untouched. 
+> To update your branch, simply run `git checkout <BRANCH>; git merge master`
 ## How do I update the design reference files?
 
 See how to update the Metrics [here](../contrib/Metrics.md).