From d4df603c24e3f7ea700839e84b0b67eb43f8910e Mon Sep 17 00:00:00 2001 From: Jeff Goeders Date: Thu, 6 Jan 2022 12:01:37 -0700 Subject: [PATCH 1/3] Add python virtual environment Signed-off-by: Jeff Goeders --- .gitignore | 1 + CMakeLists.txt | 6 ++++++ cmake/modules/PyEnv.cmake | 7 +++++++ 3 files changed, 14 insertions(+) create mode 100644 cmake/modules/PyEnv.cmake diff --git a/.gitignore b/.gitignore index c22ddfec476..2e954bff985 100644 --- a/.gitignore +++ b/.gitignore @@ -104,6 +104,7 @@ ODIN_II/usefull_tools/**/track_completed #Python # *.pyc +/.venv # #Vim diff --git a/CMakeLists.txt b/CMakeLists.txt index 46c077ddf24..c9d9653b238 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -451,3 +451,9 @@ list(APPEND DIRS_TO_FORMAT_PY "${CMAKE_CURRENT_SOURCE_DIR}/vpr") list(APPEND DIRS_TO_FORMAT_PY "${CMAKE_CURRENT_SOURCE_DIR}/vtr_flow") include(AutoPyFormat) + + +# +# Python Environment setup +# +include(PyEnv) \ No newline at end of file diff --git a/cmake/modules/PyEnv.cmake b/cmake/modules/PyEnv.cmake new file mode 100644 index 00000000000..81caa161d32 --- /dev/null +++ b/cmake/modules/PyEnv.cmake @@ -0,0 +1,7 @@ +# Create a python virtual environment using venv and install all necessary packages +# wheel should be installed before the requirements.txt list to prevent errors. +add_custom_target(env + COMMAND python3 -m venv ../.venv + COMMAND . ../.venv/bin/activate && pip3 install wheel + COMMAND . ../.venv/bin/activate && pip3 install -r ../requirements.txt +) \ No newline at end of file From b444b9052c28e89fa22f2de8127a4c07a900a8f6 Mon Sep 17 00:00:00 2001 From: Jeff Goeders Date: Thu, 6 Jan 2022 12:03:51 -0700 Subject: [PATCH 2/3] Move to myst-parser for markdown, and reorg build instructions Signed-off-by: Jeff Goeders --- BUILDING.md | 256 +++-------------------- CONTRIBUTING.md | 2 +- README.developers.md | 18 +- doc/requirements.txt | 4 +- doc/src/BUILDING.md | 3 + doc/src/CONTRIBUTING.md | 2 + doc/src/LICENSE.md | 2 + doc/src/README.developers.md | 2 + doc/src/SUPPORT.md | 2 + doc/src/building/building.md | 1 - doc/src/building/index.rst | 7 - doc/src/conf.py | 39 +--- doc/src/contact.md | 27 +++ doc/src/contact.rst | 31 --- doc/src/dev/contributing/contributing.md | 1 - doc/src/dev/contributing/index.rst | 6 - doc/src/dev/developing.md | 1 - doc/src/dev/index.rst | 8 +- doc/src/dev/license.md | 1 - doc/src/dev/support.md | 1 - doc/src/index.rst | 3 +- doc/src/odin/dev_guide/contributing.md | 4 +- doc/src/quickstart/index.rst | 36 +++- doc/src/vtr/get_vtr.rst | 10 +- doc/src/vtr/index.rst | 3 +- doc/src/vtr/install_vtr.rst | 32 --- doc/src/vtr/optional_build_info.md | 194 +++++++++++++++++ doc/src/vtr/power_estimation/index.rst | 2 +- install_apt_packages.sh | 27 +++ 29 files changed, 343 insertions(+), 382 deletions(-) create mode 100644 doc/src/BUILDING.md create mode 100644 doc/src/CONTRIBUTING.md create mode 100644 doc/src/LICENSE.md create mode 100644 doc/src/README.developers.md create mode 100644 doc/src/SUPPORT.md delete mode 120000 doc/src/building/building.md delete mode 100644 doc/src/building/index.rst create mode 100644 doc/src/contact.md delete mode 100644 doc/src/contact.rst delete mode 120000 doc/src/dev/contributing/contributing.md delete mode 100644 doc/src/dev/contributing/index.rst delete mode 120000 doc/src/dev/developing.md delete mode 120000 doc/src/dev/license.md delete mode 120000 doc/src/dev/support.md delete mode 100644 doc/src/vtr/install_vtr.rst create mode 100644 doc/src/vtr/optional_build_info.md create mode 100755 install_apt_packages.sh diff --git a/BUILDING.md b/BUILDING.md index 61d3bf7e437..74d90f18e30 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,255 +1,49 @@ -# Building VTR # +# Building VTR -## Overview ## +## Setting up Your Environment -VTR uses [CMake](https://cmake.org) as it's build system. -CMake provides a portable cross-platform build systems with many useful features. +VTR requires several system packages. From the top-level directory, run the following script to install the required packages on a modern Debian or Ubuntu system: -## Tested Compilers ## -VTR requires a C++-14 compliant compiler. -It is tested against the default compilers of all Debian and Ubuntu releases within their standard support lifetime. Currently, those are the following: + ./install_apt_packages.sh -* GCC/G++: 7, 8, 9, 10, 11 -* Clang/Clang++: 6, 7, 10 -Other compilers may work but are untested (your milage may vary). +You will also need several Python packages. You can optionally install and activate a Python virtual environment so that you do not need to modify your system Python installation: -## Unix-like ## -For unix-like systems we provide a wrapper Makefile which supports the traditional `make` and `make clean` commands, but calls CMake behind the scenes. + make env + source .venv/bin/activate -### Dependencies ### +Then to install the Python packages: -For the basic tools you need: - * Bison & Flex - * cmake, make - * A modern C++ compiler supporting C++14 (such as GCC >= 4.9 or clang >= 3.6) + pip install -r requirements.txt -For the VPR GUI you need: - * Cairo - * FreeType - * Xft (libXft + libX11) - * fontconfig - * libgtk-3-dev +**Note:** If you chose to install the Python virtual environment, you will need to remember to activate it on any new terminal window you use, before you can run the VTR flow or regressions tests. -For the [regression testing and benchmarking](README.developers.md#running-tests) you will need: - * Perl + List::MoreUtils - * Python - * time +## Building -It is also recommended you install the following development tools: - * git - * ctags - * gdb - * valgrind - * clang-format-7 +From the top-level, run: -For Docs generation you will need: - * Doxygen - * python-sphinx - * python-sphinx-rtd-theme - * python-recommonmark + make -#### Debian & Ubuntu #### + which will build all the required tools. -The following should be enough to get the tools, VPR GUI and tests going on a modern Debian or Ubuntu system: +The complete VTR flow has been tested on 64-bit Linux systems. +The flow should work in other platforms (32-bit Linux, Windows with cygwin) but this is untested. -```shell -apt-get install \ - build-essential \ - flex \ - bison \ - cmake \ - fontconfig \ - libcairo2-dev \ - libfontconfig1-dev \ - libx11-dev \ - libxft-dev \ - libgtk-3-dev \ - perl \ - liblist-moreutils-perl \ - python \ - time -``` +*Full information about building VTR, including setting up required system packages and Python packages, can be found in [Optional Build Information](doc/src/vtr/optional_build_info.md) page.* -For documentation generation these additional packages are required: +Please [let us know](doc/src/contact.md) your experience with building VTR so that we can improve the experience for others. -```shell -apt-get install \ - doxygen \ - python-sphinx \ - python-sphinx-rtd-theme \ - python-recommonmark -``` +The tools included official VTR releases have been tested for compatibility. +If you download a different version of those tools, then those versions may not be mutually compatible with the VTR release. +## Verifying Installation -For development the following additional packages are useful: +To verfiy that VTR has been installed correctly run:: -```shell -apt-get install \ - git \ - valgrind \ - gdb \ - ctags -``` + ./vtr_flow/scripts/run_vtr_task.py basic_flow -#### Using Nix #### +The expected output is:: -Although the recommended platform is Debian or Ubuntu, Nix can be used to build VTR on other platforms, such as MacOS. - -If you don't have [Nix](https://nixos.org/nix/), you can [get it](https://nixos.org/nix/download.html) with: - -```shell -$ curl -L https://nixos.org/nix/install | sh -``` - -These commands will set up dependencies for Linux and MacOS and build VTR: - -```shell -#In the VTR root -$ nix-shell dev/nix/shell.nix -$ make -``` - -### Building using the Makefile wrapper ### -Run `make` from the root of the VTR source tree - -```shell -#In the VTR root -$ make -... -[100%] Built target vpr -``` - - -#### Specifying the build type #### -You can specify the build type by passing the `BUILD_TYPE` parameter. - -For instance to create a debug build (no optimization and debug symbols): - -```shell -#In the VTR root -$ make BUILD_TYPE=debug -... -[100%] Built target vpr -``` - - -#### Passing parameters to CMake #### -You can also pass parameters to CMake. - -For instance to set the CMake configuration variable `VTR_ENABLE_SANITIZE` on: - -```shell -#In the VTR root -$ make CMAKE_PARAMS="-DVTR_ENABLE_SANITIZE=ON" -... -[100%] Built target vpr -``` - -Both the `BUILD_TYPE` and `CMAKE_PARAMS` can be specified concurrently: -```shell -#In the VTR root -$ make BUILD_TYPE=debug CMAKE_PARAMS="-DVTR_ENABLE_SANITIZE=ON" -... -[100%] Built target vpr -``` - - -### Using CMake directly ### -You can also use cmake directly. - -First create a build directory under the VTR root: - -```shell -#In the VTR root -$ mkdir build -$ cd build - -#Call cmake pointing to the directory containing the root CMakeLists.txt -$ cmake .. - -#Build -$ make -``` - -#### Changing configuration on the command line #### -You can change the CMake configuration by passing command line parameters. - -For instance to set the configuration to debug: - -```shell -#In the build directory -$ cmake . -DCMAKE_BUILD_TYPE=debug - -#Re-build -$ make -``` - -#### Changing configuration interactively with ccmake #### -You can also use `ccmake` to to modify the build configuration. - -```shell -#From the build directory -$ ccmake . #Make some configuration change - -#Build -$ make -``` - -## Other platforms ## - -CMake supports a variety of operating systems and can generate project files for a variety of build systems and IDEs. -While VTR is developed primarily on Linux, it should be possible to build on different platforms (your milage may vary). -See the [CMake documentation](https://cmake.org) for more details about using cmake and generating project files on other platforms and build systems (e.g. Eclipse, Microsoft Visual Studio). - - -### Microsoft Windows ### - -*NOTE: VTR support on Microsoft Windows is considered experimental* - -#### Cygwin #### -[Cygwin](https://www.cygwin.com/) provides a POSIX (i.e. unix-like) environment for Microsoft Windows. - -From within the cygwin terminal follow the Unix-like build instructions listed above. - -Note that the generated executables will rely upon Cygwin (e.g. `cygwin1.dll`) for POSIX compatibility. - -#### Cross-compiling from Linux to Microsoft Windows with MinGW-W64 #### -It is possible to cross-compile from a Linux host system to generate Microsoft Windows executables using the [MinGW-W64](https://mingw-w64.org) compilers. -These can usually be installed with your Linux distribution's package manager (e.g. `sudo apt-get install mingw-w64` on Debian/Ubuntu). - -Unlike Cygwin, MinGW executables will depend upon the standard Microsoft Visual C++ run-time. - -To build VTR using MinGW: -```shell -#In the VTR root -$ mkdir build_win64 -$ cd build_win64 - -#Run cmake specifying the toolchain file to setup the cross-compilation environment -$ cmake .. -DCMAKE_TOOLCHAIN_FILE ../cmake/toolchains/mingw-linux-cross-compile-to-windows.cmake - -#Building will produce Windows executables -$ make -``` - -Note that by default the MS Windows target system will need to dynamically link to the `libgcc` and `libstdc++` DLLs. -These are usually found under /usr/lib/gcc on the Linux host machine. - -See the [toolchain file](cmake/toolchains/mingw-linux-cross-compile-to-windows.cmake) for more details. - -#### Microsoft Visual Studio #### -CMake can generate a Microsft Visual Studio project, enabling VTR to be built with the Microsoft Visual C++ (MSVC) compiler. - -##### Installing additional tools ##### -VTR depends on some external unix-style tools during it's buid process; in particular the `flex` and `bison` parser generators. - -One approach is to install these tools using [MSYS2](http://www.msys2.org/), which provides up-to-date versions of many unix tools for MS Windows. - -To ensure CMake can find the `flex` and `bison` executables you must ensure that they are available on your system path. -For instance, if MSYS2 was installed to `C:\msys64` you would need to ensure that `C:\msys64\usr\bin` was included in the system PATH environment variable. - -##### Generating the Visual Studio Project ##### -CMake (e.g. the `cmake-gui`) can then be configured to generate the MSVC project. + k6_N10_memSize16384_memData64_40nm_timing/ch_intrinsics...OK diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a1dec7b03f6..d6087275290 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -154,7 +154,7 @@ The following are general tips for making your pull requests easy to review (and * Keep changes small Large change sets are difficult and time-consuming to review. - If a change set is becoming too large, consider splitting it into smaller pieces; you'll probably want to [file an issue](#filling-feature-requests) to discuss things first. + If a change set is becoming too large, consider splitting it into smaller pieces; you'll probably want to [file an issue](#filling-enhancement-requests) to discuss things first. * Do one thing only diff --git a/README.developers.md b/README.developers.md index ab18e7967eb..d991f437e71 100644 --- a/README.developers.md +++ b/README.developers.md @@ -966,7 +966,7 @@ $ make this turns on more extensive assertion checking and re-builds VTR. ## GDB Pretty Printers -To make it easier to debug some of VTR's data structures with [GDB](www.gnu.org/gdb). +To make it easier to debug some of VTR's data structures with [GDB](https://www.sourceware.org/gdb/). ### STL Pretty Printers @@ -1145,7 +1145,7 @@ make CMAKE_PARAMS="-DVTR_IPO_BUILD=off" -j8 vpr # External Subtrees VTR includes some code which is developed in external repositories, and is integrated into the VTR source tree using [git subtrees](https://www.atlassian.com/blog/git/alternatives-to-git-submodule-git-subtree). -To simplify the process of working with subtrees we use the [`dev/external_subtrees.py`](./dev/external_subtrees.py) script. +To simplify the process of working with subtrees we use the [`dev/external_subtrees.py`](https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/dev/external_subtrees.py) script. For instance, running `./dev/external_subtrees.py --list` from the VTR root it shows the subtrees: ``` @@ -1159,7 +1159,7 @@ Component: libtatum Path: libs/EXTERNAL/libtatum URL: https://git Code included in VTR by subtrees should *not be modified within the VTR source tree*. Instead changes should be made in the relevant up-stream repository, and then synced into the VTR tree. -### Updating an existing Subtree +## Updating an existing Subtree 1. From the VTR root run: `./dev/external_subtrees.py $SUBTREE_NAME`, where `$SUBTREE_NAME` is the name of an existing subtree. For example to update the `libtatum` subtree: @@ -1167,7 +1167,7 @@ Instead changes should be made in the relevant up-stream repository, and then sy ./dev/external_subtrees.py --update libtatum ``` -### Adding a new Subtree +## Adding a new Subtree To add a new external subtree to VTR do the following: @@ -1207,7 +1207,7 @@ To add a new external subtree to VTR do the following: The first will squash all the upstream changes, the second will merge those changes into the current branch. -### Subtree Rational +## Subtree Rational VTR uses subtrees to allow easy tracking of upstream dependencies. @@ -1221,7 +1221,7 @@ See [here](https://blogs.atlassian.com/2013/05/alternatives-to-git-submodule-git # Finding Bugs with Coverity [Coverity Scan](https://scan.coverity.com) is a static code analysis service which can be used to detect bugs. -### Browsing Defects +## Browsing Defects To view defects detected do the following: 1. Get a coverity scan account @@ -1231,7 +1231,7 @@ To view defects detected do the following: 2. Browse the existing defects through the coverity web interface -### Submitting a build +## Submitting a build To submit a build to coverity do the following: 1. [Download](https://scan.coverity.com/download) the coverity build tool @@ -1264,7 +1264,7 @@ Note that we explicitly asked for gcc and g++, the coverity build tool defaults Once the build has been analyzed you can browse the latest results through the coverity web interface -### No files emitted +## No files emitted If you get the following warning from cov-build: [WARNING] No files were emitted. @@ -1303,5 +1303,5 @@ The following outlines the procedure to following when making an official VTR re * GitHub will automatically create a release based on the tag * Add the new change log entry to the [GitHub release description](https://github.com/verilog-to-routing/vtr-verilog-to-routing/releases) * Update the [ReadTheDocs configuration](https://readthedocs.org/projects/vtr/versions/) to build and serve documentation for the relevant tag (e.g. `v8.0.0`) - * Send a release announcement email to the [vtr-announce](vtr-announce@googlegroups.com) mailing list (make sure to thank all contributors!) + * Send a release announcement email to the [vtr-announce](mailto:vtr-announce@googlegroups.com) mailing list (make sure to thank all contributors!) diff --git a/doc/requirements.txt b/doc/requirements.txt index 1992b3d665b..936fd87da6d 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,15 +2,15 @@ # used by Read The Docs to install python required # modules with pip. -Sphinx==3.0 +Sphinx==3.1 sphinx_rtd_theme # Support custom domains sphinxcontrib-domaintools # Support Markdown -recommonmark sphinx-markdown-tables +myst_parser # Handle markdown cross-references git+https://github.com/SymbiFlow/sphinxcontrib-markdown-symlinks diff --git a/doc/src/BUILDING.md b/doc/src/BUILDING.md new file mode 100644 index 00000000000..1a07249aae5 --- /dev/null +++ b/doc/src/BUILDING.md @@ -0,0 +1,3 @@ +```{include} ../../BUILDING.md +:relative-docs: doc/src +``` \ No newline at end of file diff --git a/doc/src/CONTRIBUTING.md b/doc/src/CONTRIBUTING.md new file mode 100644 index 00000000000..e75758cf1fc --- /dev/null +++ b/doc/src/CONTRIBUTING.md @@ -0,0 +1,2 @@ +```{include} ../../CONTRIBUTING.md +``` \ No newline at end of file diff --git a/doc/src/LICENSE.md b/doc/src/LICENSE.md new file mode 100644 index 00000000000..99913ef0fac --- /dev/null +++ b/doc/src/LICENSE.md @@ -0,0 +1,2 @@ +```{include} ../../LICENSE.md +``` \ No newline at end of file diff --git a/doc/src/README.developers.md b/doc/src/README.developers.md new file mode 100644 index 00000000000..c052871ae7b --- /dev/null +++ b/doc/src/README.developers.md @@ -0,0 +1,2 @@ +```{include} ../../README.developers.md +``` \ No newline at end of file diff --git a/doc/src/SUPPORT.md b/doc/src/SUPPORT.md new file mode 100644 index 00000000000..f4eb7ca0ab8 --- /dev/null +++ b/doc/src/SUPPORT.md @@ -0,0 +1,2 @@ +```{include} ../../SUPPORT.md +``` \ No newline at end of file diff --git a/doc/src/building/building.md b/doc/src/building/building.md deleted file mode 120000 index 082cacfcbce..00000000000 --- a/doc/src/building/building.md +++ /dev/null @@ -1 +0,0 @@ -../../../BUILDING.md \ No newline at end of file diff --git a/doc/src/building/index.rst b/doc/src/building/index.rst deleted file mode 100644 index 3a526794c87..00000000000 --- a/doc/src/building/index.rst +++ /dev/null @@ -1,7 +0,0 @@ - -.. _building_vtr: - -.. toctree:: - :glob: - - building diff --git a/doc/src/conf.py b/doc/src/conf.py index c5773d2e615..59dd87d499c 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -18,8 +18,6 @@ import shutil import subprocess -# Markdown support -import recommonmark sys.path.append(".") sys.path.insert(0, os.path.abspath("../../vtr_flow/scripts/python_libs")) @@ -67,7 +65,7 @@ "sdcdomain", "archdomain", "rrgraphdomain", - "recommonmark", + "myst_parser", "sphinx.ext.autodoc", "sphinx.ext.graphviz", ] @@ -373,41 +371,10 @@ for prjname, prjdir in breathe_projects.items(): assert os.path.exists(prjdir) == True, "Regenerate doxygen XML for {}".format(prjname) - -def recommonmark_setup(app): - """Initialize Sphinx extension.""" - import sphinx - - if sphinx.version_info >= (1, 8): - app.add_source_suffix(".md", "markdown") - app.add_source_parser(LinkParser) - - return {"version": recommonmark.__version__, "parallel_read_safe": True} - - -# Override recommonmark setup -recommonmark.setup = recommonmark_setup +# Add page anchors for myst parser +myst_heading_anchors = 4 def setup(app): - github_code_repo = "https://github.com/verilog-to-routing/vtr-verilog-to-routing/" - github_code_branch = "blob/master/" - - docs_root_dir = os.path.realpath(os.path.dirname(__file__)) - code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..", "..")) - MarkdownSymlinksDomain.init_domain( - github_code_repo, github_code_branch, docs_root_dir, code_root_dir - ) - MarkdownSymlinksDomain.find_links() - app.add_domain(MarkdownSymlinksDomain) - app.add_config_value( - "recommonmark_config", - { - "github_code_repo": github_code_repo, - "enable_math": True, - "enable_inline_math": True, - }, - True, - ) app.add_stylesheet("css/vtr.css") diff --git a/doc/src/contact.md b/doc/src/contact.md new file mode 100644 index 00000000000..bf462918827 --- /dev/null +++ b/doc/src/contact.md @@ -0,0 +1,27 @@ + +# Contact + +## Mailing Lists +VTR maintains several mailing lists. +Most users will be interested in VTR Users and VTR Announce. + +* [VTR Announce](https://groups.google.com/forum/#!forum/vtr-announce) + + VTR release announcements (low traffic) + +* [VTR Users](https://groups.google.com/forum/#!forum/vtr-users): vtr-users@googlegroups.com + + Discussions about using the VTR project. + +* [VTR Devel](https://groups.google.com/forum/#!forum/vtr-devel): vtr-devel@googlegroups.com + + Discussions about VTR development. + +* [VTR Commits](https://groups.google.com/forum/#!forum/vtr-commits): + + Revision Control Commits to the VTR project. + +## Issue Tracker +Please file bugs on our [issue tracker](https://github.com/verilog-to-routing/vtr-verilog-to-routing/issues). + +Pull Requests are welcome! diff --git a/doc/src/contact.rst b/doc/src/contact.rst deleted file mode 100644 index c28022441e8..00000000000 --- a/doc/src/contact.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _contact: - -Contact -======= - -Mailing Lists -------------- -VTR maintains several mailing lists. -Most users will be interested in VTR Users and VTR Announce. - -* `VTR Announce `_ - - VTR release announcements (low traffic) - -* `VTR Users `_: vtr-users@googlegroups.com - - Discussions about using the VTR project. - -* `VTR Devel `_: vtr-devel@googlegroups.com - - Discussions about VTR development. - -* `VTR Commits `_: - - Revision Control Commits to the VTR project. - -Issue Tracker -------------- -Please file bugs on our `issue tracker `_. - -Patches are welcome! diff --git a/doc/src/dev/contributing/contributing.md b/doc/src/dev/contributing/contributing.md deleted file mode 120000 index 069558fad20..00000000000 --- a/doc/src/dev/contributing/contributing.md +++ /dev/null @@ -1 +0,0 @@ -../../../../CONTRIBUTING.md \ No newline at end of file diff --git a/doc/src/dev/contributing/index.rst b/doc/src/dev/contributing/index.rst deleted file mode 100644 index 4b3ca9aa11c..00000000000 --- a/doc/src/dev/contributing/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _contribution_guidelines: - -.. toctree:: - :glob: - - contributing diff --git a/doc/src/dev/developing.md b/doc/src/dev/developing.md deleted file mode 120000 index d7d781f7836..00000000000 --- a/doc/src/dev/developing.md +++ /dev/null @@ -1 +0,0 @@ -../../../README.developers.md \ No newline at end of file diff --git a/doc/src/dev/index.rst b/doc/src/dev/index.rst index 4b20453dbb5..8479b8bc462 100644 --- a/doc/src/dev/index.rst +++ b/doc/src/dev/index.rst @@ -6,10 +6,10 @@ Developer Guide .. toctree:: :glob: - contributing/index - developing + ../CONTRIBUTING + ../README.developers.md c_api_doc code_documentation tutorials/index - support - license + ../SUPPORT + ../LICENSE diff --git a/doc/src/dev/license.md b/doc/src/dev/license.md deleted file mode 120000 index 368ec7e5708..00000000000 --- a/doc/src/dev/license.md +++ /dev/null @@ -1 +0,0 @@ -../../../LICENSE.md \ No newline at end of file diff --git a/doc/src/dev/support.md b/doc/src/dev/support.md deleted file mode 120000 index 7811d359dd5..00000000000 --- a/doc/src/dev/support.md +++ /dev/null @@ -1 +0,0 @@ -../../../SUPPORT.md \ No newline at end of file diff --git a/doc/src/index.rst b/doc/src/index.rst index 17573887412..0b6eb4b0a03 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -17,7 +17,7 @@ Welcome to Verilog-to-Routing's documentation! Form more information on the Verilog-to-Routing (VTR) project see :ref:`vtr` and :ref:`vtr_cad_flow`. -For documentation and tutorials on the FPGA architecture description langauge see: :ref:`fpga_architecture_description`. +For documentation and tutorials on the FPGA architecture description language see: :ref:`fpga_architecture_description`. For more specific documentation about VPR see :ref:`vpr`. @@ -32,7 +32,6 @@ For more specific documentation about VPR see :ref:`vpr`. :maxdepth: 2 :caption: Usage - building/index vtr/index arch/index vpr/index diff --git a/doc/src/odin/dev_guide/contributing.md b/doc/src/odin/dev_guide/contributing.md index e366384c97b..23a87859a90 100644 --- a/doc/src/odin/dev_guide/contributing.md +++ b/doc/src/odin/dev_guide/contributing.md @@ -12,7 +12,7 @@ To create a pull request, clone the [vtr-verilog-to-routing repository](https:// Make changes to the branch that improve Odin II and correct the bug. **Important** In addition to correcting the bug, it is required that test cases (benchmarks) are created that reproduce the issue and are included in the regression tests. An example of a good test case could be the benchmark found in the "Issue" being addressed. -The results of these new tests need to be regenerate. See [regression tests](./regression_tests) for further instruction. +The results of these new tests need to be regenerate. See [regression tests](regression_test.md) for further instruction. Push these changes to the cloned repository and create the pull request. Add a description of the changes made and reference the "issue" that it corrects. There is a template provided on GitHub. @@ -29,7 +29,7 @@ Then, create a pull request with that branch and **include WIP in the title.** This will automatically indicate that this PR is not ready to be merged. Continue to work on the branch, pushing the commits regularly. Like a PR, test cases must be included through the use of benchmarks. -See [regression tests](./regression_tests) for further instruction. +See [regression tests](regression_test.md) for further instruction. ### Formating diff --git a/doc/src/quickstart/index.rst b/doc/src/quickstart/index.rst index 3679d5b718a..c824759d3cf 100644 --- a/doc/src/quickstart/index.rst +++ b/doc/src/quickstart/index.rst @@ -14,6 +14,24 @@ The first step is to `download VTR `_ an .. note:: Developers planning to modify VTR should clone the `VTR git repository `_. + +Environment Setup +----------------- +VTR requires several system packages and Python packages to build and run the flow. You can install the required system packages using the following command (this works on Ubuntu 18.04 and 20.04, but you may require different packages on other Linux distributions): + +.. code-block:: bash + + > ./install_apt_packages.sh + +Then, to install the required Python packages within a new virtual environment: + +.. code-block:: bash + + > make env + > source .venv/bin/activate + > pip install -r requirements.txt + + Build VTR --------- @@ -36,11 +54,9 @@ from the VTR root directory (hereafter referred to as :term:`$VTR_ROOT`) to buil To run the examples in this guide on your machine, either: * define VTR_ROOT as a variable in your shell (e.g. if ``~/trees/vtr`` is the path to the VTR source tree on your machine, run the equivalent of ``VTR_ROOT=~/trees/vtr`` in BASH) which will allow you to run the commands as written in this guide, or - * manually replace `$VTR_ROOT` in the example commandss below with your path to the VTR source tree. + * manually replace `$VTR_ROOT` in the example commands below with your path to the VTR source tree. -.. note:: If VTR fails to build you may need to install the :ref:`required dependencies `. - -For more details on building VTR on various operating systems/platforms see :ref:`Building VTR`. +For more details on building VTR on various operating systems/platforms see :doc:`Building VTR`. Running VPR @@ -368,7 +384,13 @@ Automatically Running the VTR Flow Running each stage of the flow manually is time consuming (and potentially error prone). For convenience, VTR provides a script (:ref:`run_vtr_flow`) which automates this process. -Lets make a new directory to work in named ``blink_run_flow``: +First, make sure you sure you have activated the Python virtual environment created at the beginning of this tutorial: + +.. code-block:: bash + + > source $VTR_ROOT/.venv/bin/activate + +Next, make a new directory to work in named ``blink_run_flow``: .. code-block:: bash @@ -463,7 +485,7 @@ Here are some possible next steps for users wishing to use VTR: * Discover how to :ref:`generate FASM ` for bitstream creation. - * :ref:`Suggest or make enhancements to VTR's documentation `. + * :doc:`Suggest or make enhancements to VTR's documentation `. Here are some possible next steps for developers wishing to modify and improve VTR: @@ -473,6 +495,6 @@ Here are some possible next steps for developers wishing to modify and improve V * Read through the :ref:`developer guide `. - * Look for :ref:`open issues to which you can contribute `. + * Look for :doc:`open issues to which you can contribute `. * Begin exploring the source code for the main tools in VTR (e.g. VPR in ``$VTR_ROOT/vpr/src``). diff --git a/doc/src/vtr/get_vtr.rst b/doc/src/vtr/get_vtr.rst index f25f26a05c2..54f45a7b1bc 100644 --- a/doc/src/vtr/get_vtr.rst +++ b/doc/src/vtr/get_vtr.rst @@ -6,7 +6,7 @@ Get VTR How to Cite ~~~~~~~~~~~ -Citations are important in academia, as they ensure contributors recieve credit for their efforts. +Citations are important in academia, as they ensure contributors receive credit for their efforts. Therefore please use the following paper as a general citation whenever you use VTR: K. E. Murray, O. Petelin, S. Zhong, J. M. Wang, M. ElDafrawy, J.-P. Legault, E. Sha, A. G. Graham, J. Wu, M. J. P. Walker, H. Zeng, P. Patros, J. Luu, K. B. Kent and V. Betz "VTR 8: High Performance CAD and Customizable FPGA Architecture Modelling", ACM TRETS, 2020 @@ -77,11 +77,11 @@ Here are some highlights of the |version| full release: Along with experiments for more conventional FPGAs, we also include an experiment that explores FPGAs with embedded floating-point cores investigated in :cite:`ho_floating_point_fpga` to illustrate the usage of the VTR framework to explore unconventional FPGA architectures. -Development Trunk -~~~~~~~~~~~~~~~~~ -The development trunk for the Verilog-to-Routing project is hosted at: +Development Repository +~~~~~~~~~~~~~~~~~~~~~~ +The development repository for the Verilog-to-Routing project is hosted at: https://github.com/verilog-to-routing/vtr-verilog-to-routing -Unlike the nicely packaged offical releases the code in a constant state of flux. +Unlike the nicely packaged official releases the code in a constant state of flux. You should expect that the tools are not always stable and that more work is needed to get the flow to run. diff --git a/doc/src/vtr/index.rst b/doc/src/vtr/index.rst index be581eec596..c73c1891d77 100644 --- a/doc/src/vtr/index.rst +++ b/doc/src/vtr/index.rst @@ -38,7 +38,8 @@ VTR also includes a set of benchmark designs known to work with the design flow. cad_flow get_vtr - install_vtr + ../BUILDING + optional_build_info running_vtr benchmarks power_estimation/index.rst diff --git a/doc/src/vtr/install_vtr.rst b/doc/src/vtr/install_vtr.rst deleted file mode 100644 index d5fa4a6a310..00000000000 --- a/doc/src/vtr/install_vtr.rst +++ /dev/null @@ -1,32 +0,0 @@ -Install VTR ------------ - -#. :ref:`Download ` the VTR release -#. Unpack the release in a directory of your choice (herafter referred to as :term:`$VTR_ROOT`) -#. Navigate to :term:`$VTR_ROOT` and run :: - - make - - which will build all the required tools. - -.. warning:: :term:`$VTR_ROOT` should be replaced with the path to the root of VTR source tree on your machine. - -The complete VTR flow has been tested on 64-bit Linux systems. -The flow should work in other platforms (32-bit Linux, Windows with cygwin) but this is untested. - -.. seealso:: More information about building VTR can be found in the :ref:`developer_guide` - -Please :ref:`let us know ` your experience with building VTR so that we can improve the experience for others. - -The tools included official VTR releases have been tested for compatibility. -If you download a different version of those tools, then those versions may not be mutually compatible with the VTR release. - -Verifying Installation -~~~~~~~~~~~~~~~~~~~~~~ -To verfiy that VTR has been installed correctly run:: - - $VTR_ROOT/vtr_flow/scripts/run_vtr_task.py basic_flow - -The expected output is:: - - k6_N10_memSize16384_memData64_40nm_timing/ch_intrinsics...OK diff --git a/doc/src/vtr/optional_build_info.md b/doc/src/vtr/optional_build_info.md new file mode 100644 index 00000000000..c6dfeb24d2e --- /dev/null +++ b/doc/src/vtr/optional_build_info.md @@ -0,0 +1,194 @@ +# Optional Build Information # + +This page contains additional information about the VTR build system, and how to build VTR on other OS platforms or with non-standard build options. If you only need to the default features of VTR on a Debian/Ubuntu system, the previous [Building VTR](../BUILDING.md) page should be sufficient and you can skip this page. + +## Dependencies + +Most package and Python dependencies can be installed using the instructions on the previous [Building VTR](../BUILDING.md) page. However, more detailed information is provided here. + +### CMake + +VTR uses [CMake](https://cmake.org) as it's build system. + +CMake provides a portable cross-platform build systems with many useful features. + +For unix-like systems we provide a wrapper Makefile which supports the traditional `make` and `make clean` commands, but calls CMake behind the scenes. + +### Tested Compilers +VTR requires a C++-14 compliant compiler. +It is tested against the default compilers of all Debian and Ubuntu releases within their standard support lifetime. Currently, those are the following: + +* GCC/G++: 7, 8, 9, 10, 11 +* Clang/Clang++: 6, 7, 10 + +Other compilers may work but are untested (your milage may vary). + +### Package Dependencies + + * At minimum you will require: + * A modern C++ compiler supporting C++14 (such as GCC >= 4.9 or clang >= 3.6) + * cmake, make + * bison, flex, pkg-config + * Additional packages are required for the VPR GUI (Cairo, FreeType, libXft, libX11, fontconfig, libgtk-3-dev) + * The scripts to run the entire VTR flow, as well as the regressions scripts, require Python3 and Python packages listed in the *requirements.txt* file. + * Developers may also wish to install other packages (git, ctags, gdb, valgrind, clang-format-7) + * To generate the documentation you will need Sphinx, Doxygen, and several Python packages. The Python packages can be installed with the following command: + + pip install -r doc/requirements.txt + +## Build Options + +### Build Type +You can specify the build type by passing the `BUILD_TYPE` parameter. + +For instance to create a debug build (no optimization and debug symbols): + +```shell +#In the VTR root +$ make BUILD_TYPE=debug +... +[100%] Built target vpr +``` + + +### Passing parameters to CMake +You can also pass parameters to CMake. + +For instance to set the CMake configuration variable `VTR_ENABLE_SANITIZE` on: + +```shell +#In the VTR root +$ make CMAKE_PARAMS="-DVTR_ENABLE_SANITIZE=ON" +... +[100%] Built target vpr +``` + +Both the `BUILD_TYPE` and `CMAKE_PARAMS` can be specified concurrently: +```shell +#In the VTR root +$ make BUILD_TYPE=debug CMAKE_PARAMS="-DVTR_ENABLE_SANITIZE=ON" +... +[100%] Built target vpr +``` + + +### Using CMake directly +You can also use cmake directly. + +First create a build directory under the VTR root: + +```shell +#In the VTR root +$ mkdir build +$ cd build + +#Call cmake pointing to the directory containing the root CMakeLists.txt +$ cmake .. + +#Build +$ make +``` + +#### Changing configuration on the command line +You can change the CMake configuration by passing command line parameters. + +For instance to set the configuration to debug: + +```shell +#In the build directory +$ cmake . -DCMAKE_BUILD_TYPE=debug + +#Re-build +$ make +``` + +#### Changing configuration interactively with ccmake +You can also use `ccmake` to to modify the build configuration. + +```shell +#From the build directory +$ ccmake . #Make some configuration change + +#Build +$ make +``` + +## Other platforms + +CMake supports a variety of operating systems and can generate project files for a variety of build systems and IDEs. +While VTR is developed primarily on Linux, it should be possible to build on different platforms (your milage may vary). +See the [CMake documentation](https://cmake.org) for more details about using cmake and generating project files on other platforms and build systems (e.g. Eclipse, Microsoft Visual Studio). + + +### Nix + +Nix can be used to build VTR on other platforms, such as MacOS. + +If you don't have [Nix](https://nixos.org/nix/), you can [get it](https://nixos.org/nix/download.html) with: + +```shell +$ curl -L https://nixos.org/nix/install | sh +``` + +These commands will set up dependencies for Linux and MacOS and build VTR: + +```shell +#In the VTR root +$ nix-shell dev/nix/shell.nix +$ make +``` + +### Microsoft Windows + +*NOTE: VTR support on Microsoft Windows is considered experimental* + +#### WSL + +The [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/) (WSL), "lets developers run a GNU/Linux environment -- including most command-line tools, utilities, and applications -- directly on Windows, unmodified, without the overhead of a traditional virtual machine or dual-boot setup." + +This is the recommended way to run VTR on Windows systems. + +#### Cygwin #### +[Cygwin](https://www.cygwin.com/) provides a POSIX (i.e. unix-like) environment for Microsoft Windows. + +From within the cygwin terminal follow the Unix-like build instructions listed above. + +Note that the generated executables will rely upon Cygwin (e.g. `cygwin1.dll`) for POSIX compatibility. + +#### Cross-compiling from Linux to Microsoft Windows with MinGW-W64 #### +It is possible to cross-compile from a Linux host system to generate Microsoft Windows executables using the [MinGW-W64](https://mingw-w64.org) compilers. +These can usually be installed with your Linux distribution's package manager (e.g. `sudo apt-get install mingw-w64` on Debian/Ubuntu). + +Unlike Cygwin, MinGW executables will depend upon the standard Microsoft Visual C++ run-time. + +To build VTR using MinGW: +```shell +#In the VTR root +$ mkdir build_win64 +$ cd build_win64 + +#Run cmake specifying the toolchain file to setup the cross-compilation environment +$ cmake .. -DCMAKE_TOOLCHAIN_FILE ../cmake/toolchains/mingw-linux-cross-compile-to-windows.cmake + +#Building will produce Windows executables +$ make +``` + +Note that by default the MS Windows target system will need to dynamically link to the `libgcc` and `libstdc++` DLLs. +These are usually found under /usr/lib/gcc on the Linux host machine. + +See the [toolchain file](https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/cmake/toolchains/mingw-linux-cross-compile-to-windows.cmake) for more details. + +#### Microsoft Visual Studio #### +CMake can generate a Microsft Visual Studio project, enabling VTR to be built with the Microsoft Visual C++ (MSVC) compiler. + +##### Installing additional tools ##### +VTR depends on some external unix-style tools during it's buid process; in particular the `flex` and `bison` parser generators. + +One approach is to install these tools using [MSYS2](http://www.msys2.org/), which provides up-to-date versions of many unix tools for MS Windows. + +To ensure CMake can find the `flex` and `bison` executables you must ensure that they are available on your system path. +For instance, if MSYS2 was installed to `C:\msys64` you would need to ensure that `C:\msys64\usr\bin` was included in the system PATH environment variable. + +##### Generating the Visual Studio Project ##### +CMake (e.g. the `cmake-gui`) can then be configured to generate the MSVC project. diff --git a/doc/src/vtr/power_estimation/index.rst b/doc/src/vtr/power_estimation/index.rst index 9651b66286e..4d5258f3d6e 100644 --- a/doc/src/vtr/power_estimation/index.rst +++ b/doc/src/vtr/power_estimation/index.rst @@ -399,7 +399,7 @@ The user may override this method by providing the buffer size as shown below: The size is the drive strength of the buffer, relative to a minimum-sized inverter. Input Connection Boxes -"""""""""""""""" +"""""""""""""""""""""" Input connection boxes are modelled as the following components (:numref:`fig_power_cb`): diff --git a/install_apt_packages.sh b/install_apt_packages.sh new file mode 100755 index 00000000000..ac225737a46 --- /dev/null +++ b/install_apt_packages.sh @@ -0,0 +1,27 @@ +sudo apt-get update + +# Base packages to compile and run basic regression tests +sudo apt-get install -y \ + make \ + cmake \ + build-essential \ + pkg-config \ + bison \ + flex \ + python3-dev \ + python3-venv + +# Required for graphics +sudo apt-get install -y \ + libgtk-3-dev \ + libx11-dev + +# Required for yosys front-end +sudo apt-get install -y \ + clang \ + tcl-dev \ + libreadline-dev + +# Required to build the documentation +sudo apt-get install -y \ + sphinx-common From ac2d1ef0e87335815fe74dfebee5328bc1dfe362 Mon Sep 17 00:00:00 2001 From: Jeff Goeders Date: Fri, 7 Jan 2022 16:18:34 -0700 Subject: [PATCH 3/3] Add comments to python venv instructions Signed-off-by: Jeff Goeders --- BUILDING.md | 2 +- doc/src/quickstart/index.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 74d90f18e30..1a413af8d1d 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -18,7 +18,7 @@ Then to install the Python packages: pip install -r requirements.txt -**Note:** If you chose to install the Python virtual environment, you will need to remember to activate it on any new terminal window you use, before you can run the VTR flow or regressions tests. +**Note:** If you chose to install the Python virtual environment, you will need to remember to activate it on any new terminal window you use, before you can run the VTR flow or regressions tests (`source .venv/bin/activate`). ## Building diff --git a/doc/src/quickstart/index.rst b/doc/src/quickstart/index.rst index c824759d3cf..2df68649247 100644 --- a/doc/src/quickstart/index.rst +++ b/doc/src/quickstart/index.rst @@ -23,13 +23,13 @@ VTR requires several system packages and Python packages to build and run the fl > ./install_apt_packages.sh -Then, to install the required Python packages within a new virtual environment: +Then, to install the required Python packages (optionally within a new Python virtual environment): .. code-block:: bash - > make env - > source .venv/bin/activate - > pip install -r requirements.txt + > make env # optional: install python virtual environment + > source .venv/bin/activate # optional: activate python virtual environment + > pip install -r requirements.txt # install python packages (in virtual environment if prior commands run, system wide otherwise) Build VTR