aboutsummaryrefslogtreecommitdiffstats
path: root/doc/building
diff options
context:
space:
mode:
authorPatrick Lehmann <Patrick.Lehmann@tu-dresden.de>2017-03-04 21:16:30 +0100
committertgingold <tgingold@users.noreply.github.com>2017-12-10 12:02:05 +0100
commit4459eedc856870f9bc05497d4286c128b269e275 (patch)
treea0473fa2810d145de47d1c3747c58ae19f722588 /doc/building
parentcab44a1f8580880e59e9ccfd7d98e71fa111b16a (diff)
downloadghdl-4459eedc856870f9bc05497d4286c128b269e275.tar.gz
ghdl-4459eedc856870f9bc05497d4286c128b269e275.tar.bz2
ghdl-4459eedc856870f9bc05497d4286c128b269e275.zip
More restructuring.
Diffstat (limited to 'doc/building')
-rw-r--r--doc/building/PrecompileVendorPrimitives.rst214
-rw-r--r--doc/building/gcc/GNULinux-GNAT.rst32
-rw-r--r--doc/building/gcc/Windows-MinGW-GNAT.rst30
-rw-r--r--doc/building/gcc/index.rst47
-rw-r--r--doc/building/llvm/GNULinux-GNAT.rst12
-rw-r--r--doc/building/llvm/Windows-MinGW-GNAT.rst26
-rw-r--r--doc/building/llvm/index.rst30
7 files changed, 247 insertions, 144 deletions
diff --git a/doc/building/PrecompileVendorPrimitives.rst b/doc/building/PrecompileVendorPrimitives.rst
index 2495055b0..d0bf55394 100644
--- a/doc/building/PrecompileVendorPrimitives.rst
+++ b/doc/building/PrecompileVendorPrimitives.rst
@@ -236,7 +236,7 @@ Selectable Options for the Bash Scripts:
* Common parameters to most scripts:
- .. code-block::
+ .. code-block:: raw
-h --help Print the embedded help page(s).
-c --clean Cleanup directory before analyzing.
@@ -247,126 +247,186 @@ Selectable Options for the Bash Scripts:
* `compile-altera.sh`
- Selectable libraries:
-
- -a --all Compile all libraries, including common libraries, packages and device libraries.
- --altera Compile base libraries like 'altera' and 'altera_mf'
- --max Compile device libraries for Max CPLDs
- --arria Compile device libraries for Arria FPGAs
- --cyclone Compile device libraries for Cyclone FPGAs
- --stratix Compile device libraries for Stratix FPGAs
- Compile options:
+ Selectable libraries:
+
+ .. code-block:: raw
- --vhdl93 Compile selected libraries with VHDL-93 (default).
- --vhdl2008 Compile selected libraries with VHDL-2008.
+ -a --all Compile all libraries, including common libraries, packages and device libraries.
+ --altera Compile base libraries like 'altera' and 'altera_mf'
+ --max Compile device libraries for Max CPLDs
+ --arria Compile device libraries for Arria FPGAs
+ --cyclone Compile device libraries for Cyclone FPGAs
+ --stratix Compile device libraries for Stratix FPGAs
-* `compile-xilinx-ise.sh`
+ Compile options:
+
+ .. code-block:: raw
+
- Selectable libraries:
+ --vhdl93 Compile selected libraries with VHDL-93 (default).
+ --vhdl2008 Compile selected libraries with VHDL-2008.
- -a --all Compile all libraries, including common libraries, packages and device libraries.
- --unisim Compile the unisim primitives
- --unimacro Compile the unimacro macros
- --simprim Compile the simprim primitives
- --corelib Compile the xilinxcorelib macros
- --secureip Compile the secureip primitives
- Compile options:
+* `compile-xilinx-ise.sh`
- --vhdl93 Compile selected libraries with VHDL-93 (default).
- --vhdl2008 Compile selected libraries with VHDL-2008.
+ Selectable libraries:
+
+ .. code-block:: raw
+
+ -a --all Compile all libraries, including common libraries, packages and device libraries.
+ --unisim Compile the unisim primitives
+ --unimacro Compile the unimacro macros
+ --simprim Compile the simprim primitives
+ --corelib Compile the xilinxcorelib macros
+ --secureip Compile the secureip primitives
+
+ Compile options:
+
+ .. code-block:: raw
+
+ --vhdl93 Compile selected libraries with VHDL-93 (default).
+ --vhdl2008 Compile selected libraries with VHDL-2008.
* `compile-xilinx-vivado.sh`
- Selectable libraries:
-
- -a --all Compile all libraries, including common libraries, packages and device libraries.
- --unisim Compile the unisim primitives
- --unimacro Compile the unimacro macros
- --secureip Compile the secureip primitives
- Compile options:
+ Selectable libraries:
+
+ .. code-block:: raw
+
+ -a --all Compile all libraries, including common libraries, packages and device libraries.
+ --unisim Compile the unisim primitives
+ --unimacro Compile the unimacro macros
+ --secureip Compile the secureip primitives
- --vhdl93 Compile selected libraries with VHDL-93 (default).
- --vhdl2008 Compile selected libraries with VHDL-2008.
+ Compile options:
+
+ .. code-block:: raw
+
+ --vhdl93 Compile selected libraries with VHDL-93 (default).
+ --vhdl2008 Compile selected libraries with VHDL-2008.
* `compile-osvvm.sh`
- Selectable libraries:
-
- -a --all Compile all.
- --osvvm Compile the OSVVM library.
+ Selectable libraries:
+
+ .. code-block:: raw
+
+ -a --all Compile all.
+ --osvvm Compile the OSVVM library.
* `compile-vunit.sh`
- Selectable libraries:
+ Selectable libraries:
+
+ .. code-block:: raw
+
+ -a --all Compile all.
+ --osvvm Compile the VUnit library.
+
+* `compile-uvvm.sh`
+
+ Selectable libraries:
+
+ .. code-block:: raw
+
+ -a --all Compile all.
+ --uvvm Compile the VUnit library.
- -a --all Compile all.
- --osvvm Compile the VUnit library.
Selectable Options for the PowerShell Scripts:
----------------------------------------------
* Common parameters to all scripts:
-
- -Help Print the embedded help page(s).
- -Clean Cleanup directory before analyzing.
- -SuppressWarnings Don't show warnings. Report errors only.
+
+ .. code-block:: raw
+
+ -Help Print the embedded help page(s).
+ -Clean Cleanup directory before analyzing.
+ -SuppressWarnings Don't show warnings. Report errors only.
* `compile-altera.ps1`
- Selectable libraries:
+ Selectable libraries:
+
+ .. code-block:: raw
+
+ -All Compile all libraries, including common libraries, packages and device libraries.
+ -Altera Compile base libraries like 'altera' and 'altera_mf'
+ -Max Compile device libraries for Max CPLDs
+ -Arria Compile device libraries for Arria FPGAs
+ -Cyclone Compile device libraries for Cyclone FPGAs
+ -Stratix Compile device libraries for Stratix FPGAs
- -All Compile all libraries, including common libraries, packages and device libraries.
- -Altera Compile base libraries like 'altera' and 'altera_mf'
- -Max Compile device libraries for Max CPLDs
- -Arria Compile device libraries for Arria FPGAs
- -Cyclone Compile device libraries for Cyclone FPGAs
- -Stratix Compile device libraries for Stratix FPGAs
- Compile options:
+ Compile options:
+
+ .. code-block:: raw
- -VHDL93 Compile selected libraries with VHDL-93 (default).
- -VHDL2008 Compile selected libraries with VHDL-2008.
+ -VHDL93 Compile selected libraries with VHDL-93 (default).
+ -VHDL2008 Compile selected libraries with VHDL-2008.
* `compile-xilinx-ise.ps1`
- Selectable libraries:
+ Selectable libraries:
+
+ .. code-block:: raw
+
+ -All Compile all libraries, including common libraries, packages and device libraries.
+ -Unisim Compile the unisim primitives
+ -Unimacro Compile the unimacro macros
+ -Simprim Compile the simprim primitives
+ -CoreLib Compile the xilinxcorelib macros
+ -Secureip Compile the secureip primitives
- -All Compile all libraries, including common libraries, packages and device libraries.
- -Unisim Compile the unisim primitives
- -Unimacro Compile the unimacro macros
- -Simprim Compile the simprim primitives
- -CoreLib Compile the xilinxcorelib macros
- -Secureip Compile the secureip primitives
- Compile options:
+ Compile options:
+
+ .. code-block:: raw
- -VHDL93 Compile selected libraries with VHDL-93 (default).
- -VHDL2008 Compile selected libraries with VHDL-2008.
+ -VHDL93 Compile selected libraries with VHDL-93 (default).
+ -VHDL2008 Compile selected libraries with VHDL-2008.
* `compile-xilinx-vivado.ps1`
- Selectable libraries:
+ Selectable libraries:
+
+ .. code-block:: raw
- -All Compile all libraries, including common libraries, packages and device libraries.
- -Unisim Compile the unisim primitives
- -Unimacro Compile the unimacro macros
- -Secureip Compile the secureip primitives
- Compile options:
+ -All Compile all libraries, including common libraries, packages and device libraries.
+ -Unisim Compile the unisim primitives
+ -Unimacro Compile the unimacro macros
+ -Secureip Compile the secureip primitives
- -VHDL93 Compile selected libraries with VHDL-93 (default).
- -VHDL2008 Compile selected libraries with VHDL-2008.
+ Compile options:
+
+ .. code-block:: raw
+
+ -VHDL93 Compile selected libraries with VHDL-93 (default).
+ -VHDL2008 Compile selected libraries with VHDL-2008.
* `compile-osvvm.ps1`
- Selectable libraries:
+ Selectable libraries:
+
+ .. code-block:: raw
- -All Compile all.
- -OSVVM Compile the OSVVM library.
+ -All Compile all.
+ -OSVVM Compile the OSVVM library.
* `compile-vunit.ps1`
- Selectable libraries:
+ Selectable libraries:
+
+ .. code-block:: raw
+
+ -All Compile all.
+ -VUnit Compile the VUnit library.
+
+* `compile-uvvm.ps1`
+
+ Selectable libraries:
+
+ .. code-block:: raw
- -All Compile all.
- -VUnit Compile the VUnit library.
+ -All Compile all.
+ -UVVM Compile the UVVM libraries.
--------------------------------------------------------------------------------
diff --git a/doc/building/gcc/GNULinux-GNAT.rst b/doc/building/gcc/GNULinux-GNAT.rst
index d72de34a2..e35768fdb 100644
--- a/doc/building/gcc/GNULinux-GNAT.rst
+++ b/doc/building/gcc/GNULinux-GNAT.rst
@@ -24,3 +24,35 @@ On Linux, GHDL is configured by ``configure`` and build by ``make``.
../configure --prefix=PREFIX
make
sudo make install
+
+.. TODO::
+ - First configure GHDL, specify GCC source dir and :samp:`prefix` (replace :samp:`/usr/local` with your desired installation directory)::
+
+ ./configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local
+
+ - Then, invoke :samp:`make` to copy GHDL sources in the source dir::
+
+ make copy-sources
+
+ .. HINT:: There are some dependencies for building GCC (:samp:`gmp`, :samp:`mpfr` and :samp:`mpc`). If you have not them installed on your system, you can either build them manually or use the :samp:`download_prerequisite` script provided in the GCC source tree (recommended): :samp:`cd /path/to/gcc/source/dir && ./contrib/download_prerequisites`
+
+ - Then, configure GCC. The list of :samp:`--disable` configure options can be adjusted to your needs. GHDL does not require all these optional libraries and disabling them will speed-up the build::
+
+ ../gcc-4.9.3/configure --prefix=/usr/local --enable-languages=c,vhdl \
+ --disable-bootstrap --disable-lto --disable-multilib --disable-libssp \
+ --disable-libgomp --disable-libquadmath ``.
+
+ .. HINT:: Note that the prefix directory must be the same as the one used to configure GHDL. If you have manually built :samp:`gmp`/:samp:`mpfr`/:samp:`mpc` (without using the script in :samp:`contrib`) and if you have installed them in a non-standard directory, you may need to add :samp:`--with-gmp=GMP_INSTALL_DIR`.
+
+ - Then, build and install GCC::
+
+ make -j2 && make install
+
+ .. HINT:: If you don't want to install :samp:`makeinfo`, do :samp:`make install MAKEINFO=false` instead.
+
+ - Last, build and install GHDL libraries::
+
+ cd /path/to/ghdl/source/dir
+ make ghdllib
+ make install
+ \ No newline at end of file
diff --git a/doc/building/gcc/Windows-MinGW-GNAT.rst b/doc/building/gcc/Windows-MinGW-GNAT.rst
new file mode 100644
index 000000000..0ba1526bb
--- /dev/null
+++ b/doc/building/gcc/Windows-MinGW-GNAT.rst
@@ -0,0 +1,30 @@
+.. _BUILD:gcc:Windows-MinGW-GNAT:
+
+GHDL with GCC backend build on Windows with GCC/GNAT (MinGW)
+############################################################
+
+.. TODO::
+ Under investigation on how to build that beast.
+
+.. #
+ On Windows with MinGW, GHDL is configured by ``configure`` and build by ``make``.
+
+ * First, GHDL needs to be configured. It is common to specify a ``PREFIX``
+ (installation directory like ``/usr/local`` or ``/opt/ghdl``). Without any
+ other option, ``configure`` select `mcode` as backend.
+
+ * Next, ``make`` starts the compilation process.
+
+ * Finally, ``make install`` installs GHDL into the installation directory
+ specified by ``PREFIX``.
+
+ .. rubric:: Example:
+
+ .. code-block:: Bash
+
+ cd <ghdl>
+ mkdir build
+ cd build
+ ../configure --prefix=PREFIX
+ make
+ make install
diff --git a/doc/building/gcc/index.rst b/doc/building/gcc/index.rst
index 73c9d1e97..377392681 100644
--- a/doc/building/gcc/index.rst
+++ b/doc/building/gcc/index.rst
@@ -6,20 +6,20 @@ GCC Backend
.. rubric:: Requirements
* GCC (Gnu Compiler Collection)
+* GCC source files
* GNAT (Ada compiler for GCC)
.. rubric:: Supported platforms
-* :ref:`GNU/Linux with GCC <BUILD:mcode:GNULinux-GCC>`
-* :ref:`Windows (x86_64) with GNAT GPL (x86) <BUILD:mcode:Windows-GNATGPL>`
-* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:mcode:Windows-WinGW>`
+* :ref:`GNU/Linux with GCC <BUILD:gcc:GNULinux-GNAT>`
+* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:gcc:Windows-WinGW-GNAT>`
.. toctree::
:hidden:
- GNULinux-GNAT
- Windows-WinGW
+ GNU/Linux with GCC/GNAT <GNULinux-GNAT>
+ Windows with GCC/GNAT (MinGW) <Windows-MinGW-GNAT>
@@ -35,46 +35,9 @@ GCC Backend
$ make grt-all # Build the GHDL runtime
$ make grt.links # Locally install the GHDL runtime
-GNU/Linux
----------
-
-- First configure GHDL, specify GCC source dir and :samp:`prefix` (replace :samp:`/usr/local` with your desired installation directory)::
-
- ./configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local
-
-- Then, invoke :samp:`make` to copy GHDL sources in the source dir::
-
- make copy-sources
-
-.. HINT:: There are some dependencies for building GCC (:samp:`gmp`, :samp:`mpfr` and :samp:`mpc`). If you have not them installed on your system, you can either build them manually or use the :samp:`download_prerequisite` script provided in the GCC source tree (recommended): :samp:`cd /path/to/gcc/source/dir && ./contrib/download_prerequisites`
-
-- Then, configure GCC. The list of :samp:`--disable` configure options can be adjusted to your needs. GHDL does not require all these optional libraries and disabling them will speed-up the build::
-
- ../gcc-4.9.3/configure --prefix=/usr/local --enable-languages=c,vhdl \
- --disable-bootstrap --disable-lto --disable-multilib --disable-libssp \
- --disable-libgomp --disable-libquadmath ``.
-
-.. HINT:: Note that the prefix directory must be the same as the one used to configure GHDL. If you have manually built :samp:`gmp`/:samp:`mpfr`/:samp:`mpc` (without using the script in :samp:`contrib`) and if you have installed them in a non-standard directory, you may need to add :samp:`--with-gmp=GMP_INSTALL_DIR`.
-
-- Then, build and install GCC::
-
- make -j2 && make install
-
-.. HINT:: If you don't want to install :samp:`makeinfo`, do :samp:`make install MAKEINFO=false` instead.
-
-- Last, build and install GHDL libraries::
-
- cd /path/to/ghdl/source/dir
- make ghdllib
- make install
-
-Windows?
---------
.. TODO:
- Since the content of BUILD.txt is moved to the docs, what shall we do with this line? +gcc version 6.3 [do not modify this line as this is read by scripts].
-
Note for ppc64 (and AIX ?) platform: the object file format contains an identifier for the source language. Because gcc doesn't know about the VHDL, gcc crashes very early. This could be fixed with a very simple change in gcc/config/rs6000/rs6000.c, function rs6000_output_function_epilogue (as of gcc 4.8):
.. CODE:: C
diff --git a/doc/building/llvm/GNULinux-GNAT.rst b/doc/building/llvm/GNULinux-GNAT.rst
index d72de34a2..b0f26b991 100644
--- a/doc/building/llvm/GNULinux-GNAT.rst
+++ b/doc/building/llvm/GNULinux-GNAT.rst
@@ -24,3 +24,15 @@ On Linux, GHDL is configured by ``configure`` and build by ``make``.
../configure --prefix=PREFIX
make
sudo make install
+
+
+.. TODO::
+ You need to install LLVM (usually depends on :samp:`libedit`, see :ghdlsharp`29`). The supported versions are 3.5 till 3.9, but debugging is only supported with LLVM 3.5.
+
+ - First configure GHDL with the proper arg :samp:`./configure --with-llvm-config`. If :samp:`llvm-config` is not in your path, you can specify it: :samp:`./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config`.
+
+ .. HINT::
+ If you want to have stack backtraces on errors (like assert failure or index of out bounds), you need to configure and build :samp:`libbacktrace` from GCC (you don't need to configure GCC). Then add the following arg to configure: :samp:`--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a`
+
+ - Then build with :samp:`make` and install with :samp:`make install`.
+
diff --git a/doc/building/llvm/Windows-MinGW-GNAT.rst b/doc/building/llvm/Windows-MinGW-GNAT.rst
new file mode 100644
index 000000000..1329b80a1
--- /dev/null
+++ b/doc/building/llvm/Windows-MinGW-GNAT.rst
@@ -0,0 +1,26 @@
+.. _BUILD:llvm:Windows-MinGW-GNAT:
+
+GHDL with LLVM backend build on Windows with GCC/GNAT (MinGW)
+#############################################################
+
+On Windows with MinGW, GHDL is configured by ``configure`` and build by ``make``.
+
+* First, GHDL needs to be configured. It is common to specify a ``PREFIX``
+ (installation directory like ``/usr/local`` or ``/opt/ghdl``). Without any
+ other option, ``configure`` select `mcode` as backend.
+
+* Next, ``make`` starts the compilation process.
+
+* Finally, ``make install`` installs GHDL into the installation directory
+ specified by ``PREFIX``.
+
+.. rubric:: Example:
+
+.. code-block:: Bash
+
+ cd <ghdl>
+ mkdir build
+ cd build
+ ../configure --prefix=PREFIX
+ make
+ make install
diff --git a/doc/building/llvm/index.rst b/doc/building/llvm/index.rst
index a2faf9d74..4f60cd083 100644
--- a/doc/building/llvm/index.rst
+++ b/doc/building/llvm/index.rst
@@ -19,32 +19,12 @@ LLVM Backend
.. rubric:: Supported platforms
-* :ref:`GNU/Linux with GCC <BUILD:mcode:GNULinux-GCC>`
-* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:mcode:Windows-WinGW>`
+* :ref:`GNU/Linux with GCC <BUILD:llvm:GNULinux-GNAT>`
+* Mac OS
+* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:llvm:Windows-WinGW-GNAT>`
.. toctree::
:hidden:
- GNULinux-GNAT
- Windows-WinGW
-
-
-
-GNU/Linux
----------
-
-You need to install LLVM (usually depends on :samp:`libedit`, see :ghdlsharp`29`). The supported versions are 3.5 till 3.9, but debugging is only supported with LLVM 3.5.
-
-- First configure GHDL with the proper arg :samp:`./configure --with-llvm-config`. If :samp:`llvm-config` is not in your path, you can specify it: :samp:`./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config`.
-
-.. HINT:: If you want to have stack backtraces on errors (like assert failure or index of out bounds), you need to configure and build :samp:`libbacktrace` from GCC (you don't need to configure GCC). Then add the following arg to configure: :samp:`--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a`
-
-- Then build with :samp:`make` and install with :samp:`make install`.
-
-Mac OS?
--------
-
-Windows MinGW 32/64
--------------------
-
- \ No newline at end of file
+ GNU/Linux with GCC/GNAT <GNULinux-GNAT>
+ Windows with GCC/GNAT (MinGW) <Windows-MinGW-GNAT>