diff options
Diffstat (limited to 'doc/getting')
| -rw-r--r-- | doc/getting/Directories.rst | 50 | ||||
| -rw-r--r-- | doc/getting/GCC.rst | 75 | ||||
| -rw-r--r-- | doc/getting/LLVM.rst | 43 | ||||
| -rw-r--r-- | doc/getting/PrecompileVendorPrimitives.rst | 458 | ||||
| -rw-r--r-- | doc/getting/Releases.rst | 147 | ||||
| -rw-r--r-- | doc/getting/index.rst | 86 | ||||
| -rw-r--r-- | doc/getting/mcode.rst | 74 |
7 files changed, 0 insertions, 933 deletions
diff --git a/doc/getting/Directories.rst b/doc/getting/Directories.rst deleted file mode 100644 index 982dc4813..000000000 --- a/doc/getting/Directories.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _BUILD:dir_structure: - -Directory structure -################### - -* ``src``: sources of GHDL, all of them in Ada. - -* ``libraries``: mostly third party libraries such as, `ieee`, - `std`, `synopsys` and `vital`. Except for a few shell and `Python` scripts, all - the content is written in VHDL. - - * Vendors like Altera, Lattice and Xilinx have their own simulation libraries, - especially for FPGA primitives, soft and hard macros. These libraries cannot - be shipped with GHDL, but we offer prepared compile scripts to - pre-compile the vendor libraries, if the vendor tool is present on the - computer. These are located in ``libraries/vendor``. - See :ref:`GETTING:PrecompVendor` for information on how to - use them. - -* ``dist``: scripts and auxiliary files to build GHDL in different - environments: - - * ``gcc``: header and configuration files to build GHDL with GCC (all - platforms). - * ``linux``: build and test script written in shell, and other auxiliary - files used to i) launch docker containers and ii) automate multiple builds - in `Travis CI <https://travis-ci.org/>`_. - - * ``windows``: - - * ``mcode``: - * ``appveyor``: - -* ``doc``: `Markdown` and `reStructuredText` sources and auxiliary files to - build the documentation with `Sphinx <http://www.sphinx-doc.org>`_. In fact, - `Read the Docs <http://readthedocs.org>`_ (RTD) is used to automatically build - and deploy this site and/or PDF you are reading. - -* ``testsuite``: files used for testing. - -* `.yml` configuration files for CI environments (``readthedocs``, - ``travis``, and ``appveyor``) and `ignore` files for source control - management tools (``git`` and ``.hg``). - -* Files for building GHDL: ``configure`` and ``Makefile.in``. - -* Auxiliary files for development: ``.gdbinit`` and ``ghdl.gpr.in`` - (GNAT project file). - -* Text files: ``COPYING.md``, ``NEWS.md``, and ``README.md``. diff --git a/doc/getting/GCC.rst b/doc/getting/GCC.rst deleted file mode 100644 index 7a8cd9b56..000000000 --- a/doc/getting/GCC.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _BUILD:gcc: - -GCC backend -########### - -.. TODO :: Instructions to build GHDL with GCC backend on Windows are not available yet. - -.. rubric:: Requirements - -* GCC (Gnu Compiler Collection) -* GNAT (Ada compiler for GCC) -* GCC source files. Download and untar the sources of version 4.9.x, 5.x, 6.x, 7.x, 8.x, 9.x or 10.x. - -.. HINT :: There are some dependencies for building GCC (``gmp``, ``mpfr`` and ``mpc``). If you have not installed them on your system, you can either build them manually or use the ``download_prerequisites`` script provided in the GCC source tree (recommended): ``cd /path/to/gcc/source/dir && ./contrib/download_prerequisites``. - -* First configure GHDL, specify GCC source directory and installation prefix (like ``/usr/local`` or ``/opt/ghdl``). -* Next, invoke ``make copy-sources`` to copy GHDL sources in the source directory. -* Then, configure GCC. The list of ``--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. -* Now, build and install GCC with ``make``. -* Last, build and install GHDL libraries. - -.. rubric:: Example: - -.. code-block:: Bash - - $ cd <ghdl> - $ mkdir build - $ cd build - $ ../configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local - $ make copy-sources - $ mkdir gcc-objs; cd gcc-objs - $ /path/to/gcc/source/dir/configure --prefix=/usr/local --enable-languages=c,vhdl \ - --disable-bootstrap --disable-lto --disable-multilib --disable-libssp \ - --disable-libgomp --disable-libquadmath - $ make -j2 && make install - $ cd /path/to/ghdl/source/dir/build - $ make ghdllib - $ make install - -.. HINT :: Note that the prefix directory to configure ``gcc`` must be the same as the one used to configure GHDL. If you have manually built ``gmp``/``mpfr``/``mpc`` (without using the script in ``contrib``), and, if you have installed them in a non-standard directory, you may need to add ``--with-gmp=GMP_INSTALL_DIR``. - -.. HINT :: If your system gcc was configured with ``--enable-default-pie`` (check if that option appears in the output of ``gcc -v``), you should also add it. - -.. HINT :: If you don't want to install ``makeinfo``, do ``make install MAKEINFO=true`` instead. - -.. HINT :: Once GCC (with GHDL) has been built once, it is possible to work on the GHDL source tree without copying it in the GCC tree. Commands are:: - - $ make ghdl1-gcc # Build the compiler - $ make ghdl_gcc # Build the driver - $ make libs.vhdl.local_gcc # Compile the vhdl libraries - $ make grt-all # Build the GHDL runtime - $ make install.vpi.local # Locally install vpi files - - In ``src/ortho/gcc``, create a ``Makefile.conf`` file that sets the following - variables: - - .. CODE:: Bash - - AGCC_GCCSRC_DIR=/path/to/gcc/sources - AGCC_GCCOBJ_DIR=/path/to/gcc/build - - If your system gcc was built with ``--enable-default-pie``, add - ``-no-pie`` option for linking. - -.. HINT :: For ppc64/ppc64le platform, the object file format contains an identifier for the source language. Because gcc doesn't know about VHDL, gcc crashes very early. This could be fixed with a very simple change in ``gcc/config/rs6000/rs6000.c`` (``gcc/config/rs6000/rs6000-logue.c`` since gcc 10), function ``rs6000_output_function_epilogue``: - - .. CODE:: diff - - || ! strcmp (language_string, "GNU GIMPLE") - || ! strcmp (language_string, "GNU Go") - || ! strcmp (language_string, "GNU D") - - || ! strcmp (language_string, "libgccjit")) - + || ! strcmp (language_string, "libgccjit") - + || ! strcmp (language_string, "vhdl")) - i = 0; diff --git a/doc/getting/LLVM.rst b/doc/getting/LLVM.rst deleted file mode 100644 index b8dde9735..000000000 --- a/doc/getting/LLVM.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. _BUILD:llvm: - -LLVM backend -############ - -.. rubric:: Requirements - -* GCC (Gnu Compiler Collection) -* GNAT (Ada compiler for GCC) -* LLVM (Low-Level-Virtual Machine) and CLANG (Compiler front-end for LLVM): 3.5, 3.8, 3.9, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 or 11.0 - -.. _BUILD:llvm:GNAT: - -GCC/GNAT: GNU/Linux or Windows (MinGW/MSYS2) -============================================ - -.. HINT:: You need to install LLVM (usually depends on ``libedit``, see :ghdlsharp:`29`). Debugging is supported with LLVM 3.5 or ``>=6``. - -GHDL is configured by ``configure`` and built by ``make``. - -* First, GHDL needs to be configured. It is common to specify a ``PREFIX`` - (installation directory like ``/usr/local`` or ``/opt/ghdl``). Set the proper - arg, ``./configure --with-llvm-config``, to select LLVM backend. If - ``llvm-config`` is not in your path, you can specify it: - ``./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config``. - -* 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 --with-llvm-config --prefix=PREFIX - $ make - $ make install - -.. HINT:: If you want to have stack backtraces on errors (like assert failure or index of out bounds), you need to configure and build ``libbacktrace`` from GCC (you don't need to configure GCC). Then add the following arg to configure: ``--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a`` diff --git a/doc/getting/PrecompileVendorPrimitives.rst b/doc/getting/PrecompileVendorPrimitives.rst deleted file mode 100644 index aa322d3b7..000000000 --- a/doc/getting/PrecompileVendorPrimitives.rst +++ /dev/null @@ -1,458 +0,0 @@ -.. _GETTING:PrecompVendor: - -Precompile Vendor Primitives -############################ - -Vendors like Lattice, Intel (Altera) and Xilinx have their own simulation libraries, -especially for FPGA primitives, soft and hard macros. These libraries cannot -be shipped with GHDL, but GHDL offers prepared compile scripts to pre-compile -these vendor libraries, if the vendor tool is present in the environment. There -are also popular simulation and verification libraries like OSVVM [#f1]_ or -UVVM [#f2]_, which can be pre-compiled, too. - -The compilation scripts are writen in the shell languages: *PowerShell* for -*Windows™* and *Bash* for *GNU/Linux*, *MacOS*, *MSYS2*/*MinGW*. The -compile scripts can colorize the GHDL warning and error lines with the help -of ``grc/grcat`` [#f4]_. - -Supported Vendors Libraries -=========================== - -* Lattice (3.6 or later): - - * ``ec`` - * ``ecp``, ``ecp2``, ``ecp3``, ``ecp5u`` - * ``lptm``, ``lptm2`` - * ``machxo``, ``machxo2``, ``machxo3l``, ``machxo3d`` - * ``sc``, ``scm`` - * ``xp``, ``xp2`` - * ... - -* Intel (Altera) Quartus (13.0 or later): - - * ``lpm``, ``sgate`` - * ``altera``, ``altera_mf``, ``altera_lnsim`` - * ``arriaii``, ``arriaii_pcie_hip``, ``arriaiigz`` - * ``arriav``, ``arriavgz``, ``arriavgz_pcie_hip`` - * ``cycloneiv``, ``cycloneiv_pcie_hip``, ``cycloneive`` - * ``cyclonev`` - * ``max``, ``maxii``, ``maxv`` - * ``stratixiv``, ``stratixiv_pcie_hip`` - * ``stratixv``, ``stratixv_pcie_hip`` - * ``fiftyfivenm``, ``twentynm`` - * ... - -* Xilinx ISE (14.0 or later): - - * ``unisim`` (incl. ``secureip``) - * ``unimacro`` - * ``simprim`` (incl. ``secureip``) - * ``xilinxcorelib`` - -* Xilinx Vivado (2014.1 or later): - - * ``unisim`` (incl. ``secureip``) - * ``unimacro`` - -Supported Simulation and Verification Libraries -=============================================== - -* OSVVM [#f1]_ (for VHDL-2008) -* UVVM [#f2]_ (for VHDL-2008) - - ---------------------------------------------------------------------- - -Script Configuration -==================== - -The vendor library compile scripts need to know where the used / latest vendor -tool chain is installed. Therefore, the scripts implement a default installation -directory search as well as environment variable checks. If a vendor tool cannot -be detected or the script chooses the wrong vendor library source directory, -then it's possible to provide the path via ``--source`` (Bash) or ``-Source`` -(PoSh). - -The generated output is stored relative to the current working directory. The -scripts create a sub-directory for each vendor. The default output directory can -be overwritten by the parameter ``--output`` (Bash) or ``-Output`` (PoSh). - -To compile all source files with GHDL, the simulator executable is searched in -``PATH``. The found default GHDL executable can be overwritten by setting the -environment variable ``GHDL`` or by passing the parameter ``--ghdl`` (Bash) or -``-GHDL`` (PoSh) to the scripts. - -If the vendor library compilation is used very often, it's recommend to configure -these parameters in ``config.sh`` (Bash) or ``config.psm1`` (PoSh), so the command -line can be shortened to the essential parts. - ---------------------------------------------------------------------- - -Compiling in Bash -================= - -The provided Bash scripts support these environments: - -* Linux -* MacOS -* MSYS2 / MinGW -* WSL (Windows Subsystem for Linux) - - -Follow these steps: - -* **Step 0 - Configure the scripts (optional)** - - See the next section for how to configure ``config.sh``. - -* **Step 1 - Browse to your simulation working directory** - - .. code-block:: Bash - - $ cd <MySimulationFolder> - - -* **Step 2 - Start the compilation script(s)** - - Choose one or multiple of the following scripts to run the pre-compilation - process. - - .. code-block:: Bash - - $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all - $ /usr/local/lib/ghdl/vendors/compile-intel.sh --all - $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all - $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all - $ /usr/local/lib/ghdl/vendors/compile-uvvm.sh --all - $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all - $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all - - - In most cases GHDL is installed into ``/usr/local/``. The scripts are - installed into the ``lib\ghdl\vendors`` directory. - -* **Step 3 - Viewing the result** - - This creates vendor directories in your current working directory and - compiles the vendor files into them. - - - .. code-block:: Bash - - $ ls -ahl - ... - drwxr-xr-x 2 <user> <group> 56K Mar 09 17:41 altera - drwxr-xr-x 2 <user> <group> 56K Mar 09 17:42 intel - drwxr-xr-x 2 <user> <group> 56K Mar 09 17:42 lattice - drwxr-xr-x 2 <user> <group> 56K Mar 09 17:48 osvvm - drwxr-xr-x 2 <user> <group> 56K Mar 09 17:58 uvvm - drwxr-xr-x 2 <user> <group> 56K Mar 09 17:58 xilinx-ise - drwxr-xr-x 2 <user> <group> 56K Mar 09 17:48 xilinx-vivado - - - ---------------------------------------------------------------------- - -Compiling in PowerShell -======================= - -The provided PowerShell scripts support these environments: - -* Windows™ 10 (PowerShell 5 and PowerShell 6) - - -Follow these steps: - -* **Step 0 - Configure the scripts (optional)** - - See the next section for how to configure ``config.psm1``. - -* **Step 1 - Browse to your simulation working directory** - - .. code-block:: PowerShell - - PS> cd <MySimulationFolder> - -* **Step 2 - Start the compilation script(s)** - - Choose one or multiple of the following scripts to run the pre-compilation - process. - - .. code-block:: PowerShell - - PS> <GHDL>\lib\ghdl\vendors\compile-altera.ps1 -All - PS> <GHDL>\lib\ghdl\vendors\compile-intel.ps1 -All - PS> <GHDL>\lib\ghdl\vendors\compile-lattice.ps1 -All - PS> <GHDL>\lib\ghdl\vendors\compile-osvvm.ps1 -All - PS> <GHDL>\lib\ghdl\vendors\compile-uvvm.ps1 -All - PS> <GHDL>\lib\ghdl\vendors\compile-xilinx-ise.ps1 -All - PS> <GHDL>\lib\ghdl\vendors\compile-xilinx-vivado.ps1 -All - - .. # In most cases GHDL is installed into ``/usr/local/``. - - The scripts are installed into the ``lib\ghdl\vendors`` directory. - -* **Step 3 - Viewing the result** - - This creates vendor directories in your current working directory and - compiles the vendor files into them. - - .. code-block:: - - PS> dir - Directory: D:\temp\ghdl - - Mode LastWriteTime Length Name - ---- ------------- ------ ---- - d---- 09.03.2018 19:33 <DIR> altera - d---- 09.03.2018 19:38 <DIR> intel - d---- 09.03.2018 19:38 <DIR> lattice - d---- 09.03.2018 19:38 <DIR> osvvm - d---- 09.03.2018 19:45 <DIR> uvvm - d---- 09.03.2018 19:06 <DIR> xilinx-ise - d---- 09.03.2018 19:40 <DIR> xilinx-vivado - - ---------------------------------------------------------------------- - -Configuration Files -=================== - -For Bash: `config.sh` ---------------------- - -Please open the ``config.sh`` file and set the dictionary entries for the -installed vendor tools to your tool's installation directories. Use an empty -string ``""`` for not installed tools. - -``config.sh``: - -.. code-block:: Bash - - declare -A InstallationDirectory - InstallationDirectory[AlteraQuartus]="/opt/Altera/16.0" - InstallationDirectory[IntelQuartus]="/opt/intelFPGA/20.1" - InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.10_x64" - InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/OSVVM" - InstallationDirectory[UVVM]="/home/<user>/git/GitHub/UVVM" - InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7" - InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2020.2" - - -For PowerShell: `config.psm1` ------------------------------ - -Please open the ``config.psm1`` file and set the dictionary entries for the -installed vendor tools to your tool's installation -folder. Use an empty string ``""`` for not installed tools. - -``config.psm1``: - -.. code-block:: PowerShell - - $InstallationDirectory = @{ - "AlteraQuartus" = "C:\Altera\16.0"; - "IntelQuartus" = "C:\Altera\20.1"; - "LatticeDiamond" = "C:\Lattice\Diamond\3.10_x64"; - "XilinxISE" = "C:\Xilinx\14.7\ISE_DS"; - "XilinxVivado" = "C:\Xilinx\Vivado\2020.2"; - "OSVVM" = "C:\git\GitHub\OSVVM"; - "UVVM" = "C:\git\GitHub\UVVM" - } - - -Additional Script Parameters -============================ - -Each script supports partial compilations e.g. of shared packages and -individual parts. In addition, the amount of printout to the console can be -controlled. Some scripts may offer vendor specific options. - - -For Bash Scripts: ------------------ - -* Common parameters to most scripts: - - .. code-block:: none - - --help, -h Print the embedded help page(s). - --clean, -c Cleanup directory before analyzing. - --no-warnings, -n Don't show warnings. Report errors only. - --skip-existing, -s Skip already compiled files (an *.o file exists). - --skip-largefiles, -S Don't compile large entities like DSP and PCIe primitives. - --halt-on-error, -H Stop compiling if an error occurred. - -* ``compile-altera.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a 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: - - .. code-block:: none - - --vhdl93 Compile selected libraries with VHDL-93 (default). - --vhdl2008 Compile selected libraries with VHDL-2008. - -* ``compile-xilinx-ise.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a 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:: none - - --vhdl93 Compile selected libraries with VHDL-93 (default). - --vhdl2008 Compile selected libraries with VHDL-2008. - -* ``compile-xilinx-vivado.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a 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: - - .. code-block:: none - - --vhdl93 Compile selected libraries with VHDL-93 (default). - --vhdl2008 Compile selected libraries with VHDL-2008. - -* ``compile-osvvm.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a Compile all. - --osvvm Compile the OSVVM library. - -* ``compile-uvvm.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a Compile all. - --uvvm Compile the UVVM libraries. - - -For PowerShell Scripts: ------------------------ - -* Common parameters to all scripts: - - .. code-block:: none - - -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: - - .. code-block:: none - - -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: - - .. code-block:: none - - -VHDL93 Compile selected libraries with VHDL-93 (default). - -VHDL2008 Compile selected libraries with VHDL-2008. - -* ``compile-xilinx-ise.ps1`` - - Selectable libraries: - - .. code-block:: none - - -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:: none - - -VHDL93 Compile selected libraries with VHDL-93 (default). - -VHDL2008 Compile selected libraries with VHDL-2008. - -* ``compile-xilinx-vivado.ps1`` - - Selectable libraries: - - .. code-block:: none - - -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: - - .. code-block:: none - - -VHDL93 Compile selected libraries with VHDL-93 (default). - -VHDL2008 Compile selected libraries with VHDL-2008. - -* ``compile-osvvm.ps1`` - - Selectable libraries: - - .. code-block:: none - - -All Compile all. - -OSVVM Compile the OSVVM library. - -* ``compile-uvvm.ps1`` - - Selectable libraries: - - .. code-block:: none - - -All Compile all. - -UVVM Compile the UVVM libraries. - --------------------------------------------------------------------------------- - -.. container:: footnotes - - .. rubric:: Footnotes - - .. [#f1] OSVVM http://github.com/OSVVM/OSVVM - .. [#f2] UVVM https://github.com/UVVM/UVVM_All - .. [#f4] Generic Colourizer http://kassiopeia.juls.savba.sk/~garabik/software/grc.html diff --git a/doc/getting/Releases.rst b/doc/getting/Releases.rst deleted file mode 100644 index 2a80d8591..000000000 --- a/doc/getting/Releases.rst +++ /dev/null @@ -1,147 +0,0 @@ -.. _RELEASE: - -Releases and sources -#################### - -.. contents:: Contents of this Page - :local: - -Using package managers -********************** - -Package managers of many popular distributions provide pre-built packages of GHDL. This is the case for `apt` -(Debian/Ubuntu), `dnf` (Fedora/CentOS) or `pacman` (Arch Linux). Since GHDL supports three different backends and two -library sets (_regular_ or GPL-compatible), at least six packages with different features might be available in each package -manager. See differences between backends in :ref:`BUILD`. - -.. _RELEASE:packages: - -Downloading pre-built packages -****************************** - -Assets from nightly GHDL builds are available at `github.com/ghdl/ghdl/releases/nightly <https://github.com/ghdl/ghdl/releases/nightly>`__. -These are mostly meant to be used in Continuous Integration (CI) workflows. Precisely, `setup-ghdl-ci <https://github.com/ghdl/setup-ghdl-ci>`__ -allows to easily setup nightly assets in GitHub Actions workflows. - -Furthermore, assets from stable builds are available for a larger set of platforms: - -.. TODO How to extend this directive to use `.. only:: html` and `.. only:: html` in the python code passed to it? - -.. exec:: - from helpers import createReleasesShields, printReleaseTab, printReleasesList - - # Optionally, provide a <tag> name to get the assets table of a specific release. By default, the table of 'latest' is returned. - data = createReleasesShields() - -.. only:: html - - .. exec:: - from helpers import printReleaseTab - printReleaseTab('data') - -.. only:: latex - - .. exec:: - from helpers import printReleaseTab - printReleaseTab('data', latex=True) - -.. rubric :: Pre-built packages of older releases - -.. only:: html - - .. exec:: - from helpers import printReleasesList - printReleasesList('data') - -.. only:: latex - - .. exec:: - from helpers import printReleasesList - printReleasesList('data', latex=True) - -.. _RELEASE:Sources: - -Downloading Source Files -************************ - -.. HINT:: - - All the following procedures will retrieve the latest development version of GHDL, i.e., the `master` branch at - `github.com/ghdl/ghdl <https://github.com/ghdl/ghdl>`_. We do our best to keep it stable, but bugs can seldom be - published. See `HINT` boxes below for instructions to get older releases. - -.. _RELEASE:Sources:Zip: - -.. rubric :: Tarball/zip-file - -GHDL can be downloaded as a zip-file or tarball from GitHub. See the following table, to -choose your desired format/version: - -.. only:: html - - .. |zip-master| image:: https://img.shields.io/badge/ZIP-archive/master-323131.svg?longCache=true&style=flat-square&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAACE1BMVEUAAAAAAABcXFwAAACpqakAAABXV1cAAAAAAADAwMBYWFgAAACcnJxzc3MiIiKPj4%2FExMRaWlohISHo6OgbGxs5OTnMzMw9PT3AwMBWVlZkZGSGhoanp6eLi4vMzMyAgIC3t7eUlJSysrKNjY2Wlparq6uysrKlpaW1tbV6enqzs7PR0dGrq6uEhISwsLDFxcW9vb3Kysrg4OC8vLy3t7fPz8%2FDw8Ojo6OsrKzS0tLQ0NC9vb3ExMTm5ua9vb3Q0NChoaGsrKyurq7e3t7U1NSWlpaJiYmNjY3R0dG0tLSVlZXCwsK8vLzDw8Ph4eHk5OTW1tbW1tbm5ube3t7g4ODKysq3t7fOzs7f39%2FW1tbR0dHOzs7CwsLe3t7c3Nzn5%2BfW1tbq6urIyMjb29vW1tbe3t7X19fa2trb29vt7e3q6urHx8ft7e3k5OTh4eHPz8%2FV1dXT09Pm5ubh4eHg4ODm5ub9%2Ff3%2F%2F%2F%2F%2F%2F%2F%2Fk5OTp6enY2Njo6OjZ2dnn5%2Bfp6enc3Nzu7u76%2Bvr09PTk5OTw8PDn5%2Bf5%2Bfnf39%2Fq6urg4ODo6Ojk5OT4%2BPjm5ubm5ubs7Ozu7u76%2Bvrk5OTu7u739%2Ffq6urr6%2Bvx8fH6%2Bvrt7e34%2BPj6%2Bvr%2B%2Fv7s7Oz5%2Bfn%2B%2Fv7%2F%2F%2F%2Fp6enr6%2Bvt7e3v7%2B%2Fx8fHy8vLz8%2FP09PT29vb39%2Ff5%2Bfn8%2FPz9%2Ff3%2B%2Fv7%2F%2F%2F9qYR%2FuAAAAonRSTlMAAQECAgMDBAYGBwgKCwwMDQ4SEhQUGhwdHiIjIyQkJygpMDIzMzQ1NTY3OTo8PDw%2FP0ZITk9RUlNTVldXV1hYWlpaWltdYGBiY2ZpbHB1dXZ3d3t8fX5%2Ff4aHiIqKj5WXn6KjpKmssrK0t7u8vb7BwsPEyszNzc3O0dLT09fY2tvf4OXm5ufn6ers7O3w8fLy8vL09fX29%2Ff4%2Bvv7%2FP39%2Ff5qibsTAAABrElEQVR4AX2LhfcSURCFBxHBbkWxuwW7Q7AbQ7AbuwMMRQxRVAwMxRBWBRSX%2BRN%2F97y3y9ldlv3OmfPu3PkemfBsVbaQAwsrzPxnLrVh4huc65h3I8iGno9walyj6wzu9CIrVxk86YvU%2BxVS6SKZOP4D5ccxJJnxHtvnvdRk10sUlUVEJy4NFIV33d8S89P1JJj3GOfaDqQlG4%2BcX7tdlL6DKtr7UwgwuOwRdY85h08vuD1A5MFnGEgB7OlGkg0XZj5bPFXEcW91oQHj37Iu0uh%2BYNqXlZtFvKkLN%2FZ9g%2FJ7Qiep9JutjD25AiGpC0nqehZG4%2BEQaXQe%2BX3oUbNA1P8uFPWWTyqzPo2yCGDSAyj%2FT4ncZ%2F%2FzFgEs%2FwClQmDptvk2AtjJsht275C9QJqwevIxZ2ETf3UWrjBPdxR%2B7V6zykkYfY5ek0HIWIXx%2FGIQnowucC1mFmg4JlbTlngRoRw2CiBcRizGSZCoY8mHDEIoj1BPUJOUiiLr1wR%2FFo%2BaIiPeHIO0ENIMcl6yECig%2FqlNIUCtuIMKS5Sgm2xxRao4VyMuaos7qkQtvzsAWpTtdh6JoYQAAAAASUVORK5CYII%3D - :target: https://github.com/ghdl/ghdl/archive/master.zip - :alt: Source Code from GitHub - 'master' branch. - - .. |tgz-master| image:: https://img.shields.io/badge/TGZ-archive/master-323131.svg?longCache=true&style=flat-square&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAACE1BMVEUAAAAAAABcXFwAAACpqakAAABXV1cAAAAAAADAwMBYWFgAAACcnJxzc3MiIiKPj4%2FExMRaWlohISHo6OgbGxs5OTnMzMw9PT3AwMBWVlZkZGSGhoanp6eLi4vMzMyAgIC3t7eUlJSysrKNjY2Wlparq6uysrKlpaW1tbV6enqzs7PR0dGrq6uEhISwsLDFxcW9vb3Kysrg4OC8vLy3t7fPz8%2FDw8Ojo6OsrKzS0tLQ0NC9vb3ExMTm5ua9vb3Q0NChoaGsrKyurq7e3t7U1NSWlpaJiYmNjY3R0dG0tLSVlZXCwsK8vLzDw8Ph4eHk5OTW1tbW1tbm5ube3t7g4ODKysq3t7fOzs7f39%2FW1tbR0dHOzs7CwsLe3t7c3Nzn5%2BfW1tbq6urIyMjb29vW1tbe3t7X19fa2trb29vt7e3q6urHx8ft7e3k5OTh4eHPz8%2FV1dXT09Pm5ubh4eHg4ODm5ub9%2Ff3%2F%2F%2F%2F%2F%2F%2F%2Fk5OTp6enY2Njo6OjZ2dnn5%2Bfp6enc3Nzu7u76%2Bvr09PTk5OTw8PDn5%2Bf5%2Bfnf39%2Fq6urg4ODo6Ojk5OT4%2BPjm5ubm5ubs7Ozu7u76%2Bvrk5OTu7u739%2Ffq6urr6%2Bvx8fH6%2Bvrt7e34%2BPj6%2Bvr%2B%2Fv7s7Oz5%2Bfn%2B%2Fv7%2F%2F%2F%2Fp6enr6%2Bvt7e3v7%2B%2Fx8fHy8vLz8%2FP09PT29vb39%2Ff5%2Bfn8%2FPz9%2Ff3%2B%2Fv7%2F%2F%2F9qYR%2FuAAAAonRSTlMAAQECAgMDBAYGBwgKCwwMDQ4SEhQUGhwdHiIjIyQkJygpMDIzMzQ1NTY3OTo8PDw%2FP0ZITk9RUlNTVldXV1hYWlpaWltdYGBiY2ZpbHB1dXZ3d3t8fX5%2Ff4aHiIqKj5WXn6KjpKmssrK0t7u8vb7BwsPEyszNzc3O0dLT09fY2tvf4OXm5ufn6ers7O3w8fLy8vL09fX29%2Ff4%2Bvv7%2FP39%2Ff5qibsTAAABrElEQVR4AX2LhfcSURCFBxHBbkWxuwW7Q7AbQ7AbuwMMRQxRVAwMxRBWBRSX%2BRN%2F97y3y9ldlv3OmfPu3PkemfBsVbaQAwsrzPxnLrVh4huc65h3I8iGno9walyj6wzu9CIrVxk86YvU%2BxVS6SKZOP4D5ccxJJnxHtvnvdRk10sUlUVEJy4NFIV33d8S89P1JJj3GOfaDqQlG4%2BcX7tdlL6DKtr7UwgwuOwRdY85h08vuD1A5MFnGEgB7OlGkg0XZj5bPFXEcW91oQHj37Iu0uh%2BYNqXlZtFvKkLN%2FZ9g%2FJ7Qiep9JutjD25AiGpC0nqehZG4%2BEQaXQe%2BX3oUbNA1P8uFPWWTyqzPo2yCGDSAyj%2FT4ncZ%2F%2FzFgEs%2FwClQmDptvk2AtjJsht275C9QJqwevIxZ2ETf3UWrjBPdxR%2B7V6zykkYfY5ek0HIWIXx%2FGIQnowucC1mFmg4JlbTlngRoRw2CiBcRizGSZCoY8mHDEIoj1BPUJOUiiLr1wR%2FFo%2BaIiPeHIO0ENIMcl6yECig%2FqlNIUCtuIMKS5Sgm2xxRao4VyMuaos7qkQtvzsAWpTtdh6JoYQAAAAASUVORK5CYII%3D - :target: https://github.com/ghdl/ghdl/archive/master.tar.gz - :alt: Source Code from GitHub - 'master' branch. - - +----------+------------------------+ - | Branch | Download Link | - +==========+========================+ - | master | |zip-master| | - +----------+------------------------+ - | master | |tgz-master| | - +----------+------------------------+ - -.. HINT:: - - To download a specific version of GHDL, use this alternative URL, where ``<format>`` is ``tar.gz`` or ``zip``: - ``https://codeload.github.com/ghdl/ghdl/<format>/<tag>``. - -.. _RELEASE:Sources:GitClone: - -.. rubric :: git clone - -GHDL can be downloaded (cloned) with ``git clone`` from GitHub. GitHub offers -the transfer protocols HTTPS and SSH. You should use SSH if you have a GitHub -account and have already uploaded an OpenSSH public key to GitHub, otherwise -use HTTPS if you have no account or you want to use login credentials. - -+----------+----------------------------------------+ -| Protocol | GitHub Repository URL | -+==========+========================================+ -| HTTPS | https://github.com/ghdl/ghdl.git | -+----------+----------------------------------------+ -| SSH | ssh://git@github.com:ghdl/ghdl.git | -+----------+----------------------------------------+ - -.. HINT:: - - Execute ``git checkout -b stable <tag>`` after ``git clone``, to checkout a specific version of GHDL. - -Command line instructions to clone GHDL with HTTPS protocol: - -.. code-block:: Bash - - cd GitRoot - git clone "https://github.com/ghdl/ghdl.git" ghdl - cd ghdl - git remote rename origin github - -Command line instructions to clone GHDL with SSH protocol: - -.. code-block:: Bash - - cd GitRoot - git clone "ssh://git@github.com:ghdl/ghdl.git" ghdl - cd ghdl - git remote rename origin github - -.. NOTE:: - - Executing the following instructions in Windows Command Prompt (:program:`cmd.exe`) - won't function or will result in errors! All Windows command line instructions are - intended for :program:`Windows PowerShell`, if not marked otherwise. :program:`Windows PowerShell` - can be installed or upgraded to v5.1 by installing the `Windows Management Framework <https://docs.microsoft.com/en-us/powershell/wmf/5.1/install-configure>`_. diff --git a/doc/getting/index.rst b/doc/getting/index.rst deleted file mode 100644 index b256472b2..000000000 --- a/doc/getting/index.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. _BUILD: - -Building GHDL from Sources -########################## - -.. rubric :: Download - -GHDL can be downloaded as a `zip-file <https://github.com/ghdl/ghdl/archive/master.zip>`_/`tar-file <https://github.com/ghdl/ghdl/archive/master.tar.gz>`_ -(latest 'master' branch) or cloned with ``git clone`` from GitHub. GitHub -offers HTTPS and SSH as transfer protocols. See the :ref:`RELEASE:Sources` -page for further details. - -.. IMPORTANT:: - Since GHDL is written in `Ada`, independently of the code generator you use, - the a compiler is required. Most GNU/Linux package managers provide a package - named ``gcc-ada`` or ``gcc-gnat``. Alternatively, `GNU Ada compiler`, `GNAT GPL`, - can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_ (2014, or later; for x86, 32 or 64 bits). - Then, untar and run the doinstall script. - -.. ATTENTION:: - Since ``v0.37``, GHDL's synthesis features require GCC >=8.1, due to some new GNAT features which - are not available in previous releases. Users with older versions (who don't need synthesis) - can configure GHDL with option ``--disable-synth``. - -.. rubric :: Available back-ends - -GHDL currently supports three different back-ends (code generators): - -* mcode - built-in x86 (or x86_64) code generator -* GCC - Gnu Compiler Collection (`gcc.gnu.org <http://gcc.gnu.org/>`_) -* LLVM - Low-Level Virtual Machine (`llvm.org <http://llvm.org/>`_) - -Here is a short comparison, so that you can choose the one you want to use: - -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -| Back-end | Pros | Cons | -+============================+============================================================================+=========================================================+ -| :ref:`mcode <BUILD:mcode>` | * Very easy to build | * Simulation is slower | -| | * Very quick analysis | * x86_64/i386 only | -| | * Can handle very large designs | | -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -| :ref:`LLVM <BUILD:llvm>` | * Generated code is faster | * Build is more complex than mcode | -| | * Generated code can be debugged (with ``-g``) | | -| | * Easier to build than GCC | | -| | * Ported to many platforms (x86, x86_64, armv7/aarch64) | | -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -| :ref:`GCC <BUILD:gcc>` | * Generated code is faster (particularly with ``-O`` or ``-O2``) | * Build is even more complex | -| | * Generated code can be debugged (with ``-g``) | * Analysis can take time (particularly for large units) | -| | * Ported to many platforms (x86, x86_64, PowerPC, SPARC) | * Code coverage collection (``gcov``) is unique to GCC | -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ - -.. toctree:: - :hidden: - - Directories - mcode - LLVM - GCC - -.. HINT :: - The output of both GCC and LLVM is an executable file, but `mcode` does not - generate any. Therefore, if using GCC/LLVM, the call with argument ``-r`` can - be replaced with direct execution of the binary. See section :ref:`USING:QuickStart`. - -After making your choice, you can jump to the corresponding section. -However, we suggest you to read :ref:`BUILD:dir_structure` first, so that you -know where the content will be placed and which files are expected to be -created. - -.. HINT :: - In these instructions, the configure script is executed in the source directory; but you can execute in a different - directory too, like this: - - .. CODE:: Bash - - $ mkdir ghdl-objs - $ cd ghdl-objs - $ ../path/to/ghdl/configure ... - -.. HINT :: On Windows, building GHDL with mcode backend and GNAT GPL 32 bit seems to be the only way to get a standalone native executable. - - * MINGW/MSYS2 builds depend on the environment/runtime. - -.. HINT :: - For MacOS 10.15 (Catalina), see `https://github.com/ghdl/ghdl/issues/1368` for - workarounds to link failures. diff --git a/doc/getting/mcode.rst b/doc/getting/mcode.rst deleted file mode 100644 index 9e46a29b6..000000000 --- a/doc/getting/mcode.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. _BUILD:mcode: - -mcode backend -############# - -The mcode backend is available for all supported platforms and is also the -simplest procedure, because it requires the fewest dependencies and configuration -options. - -.. _BUILD:mcode:GNAT: - -GCC/GNAT: GNU/Linux or Windows (MinGW/MSYS2) -============================================ - -.. rubric:: Requirements - -* GCC (Gnu Compiler Collection) -* GNAT (Ada compiler for GCC) - -GHDL is configured by ``configure`` and built 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`` selects `mcode` as the backend. - -* Next, ``make`` starts the compilation process. - -* Finally, ``make install`` installs GHDL into the installation directory - specified by ``PREFIX``. - -.. HINT :: ON GNU/Linux, you may need super user privileges (``sudo ...``). - - -.. rubric:: Example: - -.. code-block:: Bash - - $ cd <ghdl> - $ mkdir build - $ cd build - $ ../configure --prefix=PREFIX - $ make - $ make install - -.. _BUILD:mcode:GNATGPL-Windows: - -GNAT GPL: Windows -================= - -.. rubric:: Requirements - -* GNAT GPL from http://libre.adacore.com -* PowerShell 4 -* PowerShell Community Extensions (PSCX) - -.. rubric:: `compile.ps1` - -.. code-block:: - - Commands Description - -------------------------------------------------------------------- - -Help Display the integrated help pages - -Clean Clean up all files and directories - -Compile Compile GHDL - -Install Install all files into a directory (xcopy deployment) - -Uninstall Uninstall all files from a directory - -Update Update files in the installation directory - -CreatePackage create an installer package - - Install options: - -InstallPath Installation directory - - CreatePackage options: - -Zip Create a zip-file for xcopy deployment |