BUILDING.md - third_party/vtr-verilog-to-routing - Git at Google

 # Building VTR #


 ## Overview ##

 VTR uses [CMake](https://cmake.org) as it's build system.

 CMake provides a portable cross-platform build systems with many useful features.

 ## Tested Compilers ##
 VTR requires a C++-14 compliant compiler.
 The following compilers are tested with VTR:

 * GCC/G++: 5, 6, 7, 8, 9
 * Clang/Clang++: 3.8, 6

 Other compilers may work but are untested (your milage may vary).

 ## 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.

 ### Dependencies ###

 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)

 For the VPR GUI you need:
  * Cairo
  * FreeType
  * Xft (libXft + libX11)
  * fontconfig
  * libgtk-3-dev

 For the [regression testing and benchmarking](README.developers.md#running-tests) you will need:
  * Perl + List::MoreUtils
  * Python
  * time

 It is also recommended you install the following development tools:
  * git
  * ctags
  * gdb
  * valgrind
  * clang-format-7

 For Docs generation you will need:
  * Doxygen
  * python-sphinx
  * python-sphinx-rtd-theme
  * python-recommonmark

 #### Debian & Ubuntu ####

 The following should be enough to get the tools, VPR GUI and tests going on a modern Debian or Ubuntu system:

 ```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
 ```

 For documentation generation these additional packages are required:

 ```shell
 apt-get install \
 	doxygen \
 	python-sphinx \
 	python-sphinx-rtd-theme \
 	python-recommonmark
 ```


 For development the following additional packages are useful:

 ```shell
 apt-get install \
 	git \
 	valgrind \
 	gdb \
 	ctags
 ```

 ### 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.
	# Building VTR #


	## Overview ##

	VTR uses [CMake](https://cmake.org) as it's build system.

	CMake provides a portable cross-platform build systems with many useful features.

	## Tested Compilers ##
	VTR requires a C++-14 compliant compiler.
	The following compilers are tested with VTR:

	* GCC/G++: 5, 6, 7, 8, 9
	* Clang/Clang++: 3.8, 6

	Other compilers may work but are untested (your milage may vary).

	## 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.

	### Dependencies ###

	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)

	For the VPR GUI you need:
	* Cairo
	* FreeType
	* Xft (libXft + libX11)
	* fontconfig
	* libgtk-3-dev

	For the [regression testing and benchmarking](README.developers.md#running-tests) you will need:
	* Perl + List::MoreUtils
	* Python
	* time

	It is also recommended you install the following development tools:
	* git
	* ctags
	* gdb
	* valgrind
	* clang-format-7

	For Docs generation you will need:
	* Doxygen
	* python-sphinx
	* python-sphinx-rtd-theme
	* python-recommonmark

	#### Debian & Ubuntu ####

	The following should be enough to get the tools, VPR GUI and tests going on a modern Debian or Ubuntu system:

	```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
	```

	For documentation generation these additional packages are required:

	```shell
	apt-get install \
	doxygen \
	python-sphinx \
	python-sphinx-rtd-theme \
	python-recommonmark
	```


	For development the following additional packages are useful:

	```shell
	apt-get install \
	git \
	valgrind \
	gdb \
	ctags
	```

	### 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.