[doc] streamline frontpage README. Move details to online documentation. Easier for newbee to find guidelines

README.md

@@ -1,5 +1,7 @@
 # Getting Started with OpenFPGA <img src="./docs/source/overview/figures/OpenFPGA_logo.png" width="200" align="right">
-[![linux build](https://github.com/LNIS-Projects/OpenFPGA/workflows/linux_build/badge.svg)](https://github.com/LNIS-Projects/OpenFPGA/actions?query=workflow%3Alinux_build)
+[![Test](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/build.yml/badge.svg)](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/build.yml)
+[![Cell Library Tests](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/cell_lib_test.yml/badge.svg)](https://github.com/lnis-uofu/OpenFPGA/actions/workflows/cell_lib_test.yml)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Documentation Status](https://readthedocs.org/projects/openfpga/badge/?version=master)](https://openfpga.readthedocs.io/en/master/?badge=master)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/lnis-uofu/OpenFPGA/master?urlpath=vscode)
 
@@ -18,77 +20,10 @@ We also recommend potential users check out the summary of [**technical capabili
 
 **A tutorial **video about **how to compile** can be** found [here](https://youtu.be/F9sMRmDewM0)**
 
-Before starting, we strongly recommend you read the required dependencies at [**compilation guidelines**](https://openfpga.readthedocs.io/en/master/tutorials/getting_started/compile/).
+Detailed guidelines are available at [**compilation guidelines**](https://openfpga.readthedocs.io/en/master/tutorials/getting_started/compile/).
+Before starting, we strongly recommend you read the required dependencies and ensure that they are correctly installed.
 It also includes detailed information about the docker image.
 
----
-
-**Compilation Steps:**
-
-```bash
-# Clone the repository and go inside it
-git clone https://github.com/LNIS-Projects/OpenFPGA.git && cd OpenFPGA
-make all
-```
-
----
-
-**Quick Compilation Verification**
-
-To quickly verify the tool is well compiled, the user can run the following command from the OpenFPGA root directory.
-```bash
-source openfpga.sh
-run-task compilation_verification --debug --show_thread_logs
-```
-
-*Python3 and iVerilog v10.1+ are required. GUI will pop up if enabled during compilation.*
-
----
-
-**Supported Operating Systems**
-
-We currently target OpenFPGA for:
- 1. Ubuntu 18.04
- 2. Red Hat 7.5
-
-*The tool was tested with these operating systems. It might work with earlier versions and other distributions.*
-
-## Running with pre-built docker image
-
-```bash
-# To get the docker image from the repository,
-docker pull ghcr.io/lnis-uofu/openfpga-master:latest
-
-# To invoke openfpga_shell
-docker run -it ghcr.io/lnis-uofu/openfpga-master:latest openfpga/openfpga bash
-```
-
-## Backward compatibility with OpenFPGA v1.1
-
-OpenFPGA v1.2 is a major upgrade over v1.1, which upgrades the internal VPR engine.
-The (VPR) architecture files used with v1.1 may not be compatible with v1.2.
-
-You can upgrade your architecture files with script
-
-```bash
-python3 openfpga_flow/scripts/arch_file_updater.py \
-    --input_file ${v1.1_arch_file} \
-    --output_file ${v1.2_compatible_arch_file}
-```
-
-Or, If you want to stay with v1.1, the final build was (tag: [_OpenFPGA:v1.1.541](https://github.com/lnis-uofu/OpenFPGA/tree/v1.1.541
-))
-
-```bash
-https://github.com/lnis-uofu/OpenFPGA/tree/v1.1.541
-```
-
-or you can download the docker image
-
-```bash
-docker pull ghcr.io/lnis-uofu/openfpga-master:v1.1.541
-```
-
 ## Documentation
 
 OpenFPGA's [full documentation](https://openfpga.readthedocs.io/en/master/) includes tutorials, descriptions of the design flow, and tool options.
@@ -96,3 +31,7 @@ OpenFPGA's [full documentation](https://openfpga.readthedocs.io/en/master/) incl
 ## Tutorials
 
 You can find a set of [tutorials](https://openfpga.readthedocs.io/en/master/tutorials/), with which you get familiar with the tool and use OpenFPGA for various purposes.
+
+## Backward Compatibility
+
+If you were using an old version of OpenFPGA and are now interested to move to the latest version, please check out the [developer guidelines](https://openfpga.readthedocs.io/en/master/dev_manual/back_compatibile).

docs/source/dev_manual/back_compatible.rst

@@ -0,0 +1,30 @@
+.. dev_manual_backward_compatibility::
+
+Backward compatibility
+======================
+
+OpenFPGA v1.1
+-------------
+
+OpenFPGA v1.2 is a major upgrade over v1.1, which upgrades the internal VPR engine.
+The (VPR) architecture files used with v1.1 may not be compatible with v1.2.
+
+You can upgrade your architecture files with script
+
+..code-block:: bash
+
+  python3 openfpga_flow/scripts/arch_file_updater.py \
+      --input_file ${v1.1_arch_file} \
+      --output_file ${v1.2_compatible_arch_file}
+
+Or, If you want to stay with v1.1, the final build was (tag: `OpenFPGA:v1.1.541 <https://github.com/lnis-uofu/OpenFPGA/tree/v1.1.541>`_))
+
+.. code-block:: bash
+
+  https://github.com/lnis-uofu/OpenFPGA/tree/v1.1.541
+
+or you can download the docker image
+
+.. code-block:: bash
+
+  docker pull ghcr.io/lnis-uofu/openfpga-master:v1.1.541

docs/source/dev_manual/index.rst

@@ -7,3 +7,5 @@
    version_number
 
    regression_tests
+
+   back_compatible

docs/source/tutorials/getting_started/compile.rst

@@ -9,8 +9,21 @@ How to Compile
 
   .. youtube:: F9sMRmDewM0
 
-General Guidelines
+Supported Operating Systems
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenFPGA is continously tested with Ubuntu 20.04. 
+It might work with earlier versions and other distributions.
+
+In addition to continous integration, our community users have tested OpenFPGA on their local machines using the following operating systems:
+
+- CentOS 7.8
+- CentOS 8
+- Ubuntu 18.04
+- Ubuntu 21.04
+
+Build Steps
+~~~~~~~~~~~
 OpenFPGA uses CMake to generate the Makefile scripts.
 In general, please follow the steps to compile
 
@@ -20,13 +33,13 @@ In general, please follow the steps to compile
   cd OpenFPGA
   make all
 
-.. note:: OpenFPGA requires gcc/g++ version >5
+.. note:: OpenFPGA requires gcc/g++ version > 7 and clang version > 6.
 
 .. note:: cmake3.12+ is recommended to compile OpenFPGA with GUI
 
 .. note:: Recommend using ``make -j<int>`` to accelerate the compilation, where ``<int>`` denotes the number of cores to be used in compilation.
 
-.. note:: VPR's GUI requires gtk-3, and can be enabled with ``cmake .. -DVPR_USE_EZGL=on``
+.. note:: VPR's GUI requires gtk-3, and can be enabled with ``make .. CMAKE_FLAGS="-DVPR_USE_EZGL=on"``
 
 **Quick Compilation Verification**
 
@@ -62,6 +75,8 @@ The following options are available for a custom build
   - ``DOPENFPGA_WITH_TEST=[ON|OFF]``: Enable/Disable the test build
   - ``DOPENFPGA_WITH_YOSYS=[ON|OFF]``: Enable/Disable the build of yosys. Note that when disabled, the build of yosys-plugin is also disabled
   - ``DOPENFPGA_WITH_YOSYS_PLUGIN=[ON|OFF]``: Enable/Disable the build of yosys-plugin.
+  - ``DOPENFPGA_WITH_VERSION=[ON|OFF]``: Enable/Disable the build of version number. When disabled, version number will be displayed as an empty string.
+  - ``DOPENFPGA_WITH_SWIG=[ON|OFF]``: Enable/Disable the build of SWIG, which is required for integrating to high-level interface.
 
 .. warning:: By default, only required modules in *Verilog-to-Routing* (VTR) is enabled. On other words, ``abc``, ``odin``, ``yosys`` and other add-ons inside VTR are not built. If you want to enable them, please look into the dedicated options of CMake scripts.  
 
@@ -76,7 +91,7 @@ In particular, OpenFPGA requires specific versions for the following dependencie
   version >3.12 for graphical interface
 
 :iverilog:
-  version 10.1+ is required to run Verilog-to-Verification flow
+  version 10.3+ is required to run Verilog-to-Verification flow
   
 :python dependencies:
   python packages are also required:
@@ -85,12 +100,10 @@ In particular, OpenFPGA requires specific versions for the following dependencie
 
   python3 -m pip install -r requirements.txt
 
-
 .. _install_dependencies_build: https://github.com/lnis-uofu/OpenFPGA/blob/master/.github/workflows/install_dependencies_build.sh
 
-
+Running with pre-built docker image
-Running with the docker image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Users can skip the traditional installation process by using the Dockerized version
 of the OpenFPGA tool. The OpenFPGA project maintains the docker image/Github package of