From b124c3926b05d7d0770989330039518c391f73cf Mon Sep 17 00:00:00 2001 From: 1138-4EB <1138-4EB@users.noreply.github.com> Date: Sat, 31 Aug 2019 17:32:35 +0200 Subject: [doc] Update section 'Getting GHDL' (#906) * doc: fix version extraction from 'configure' * doc: update section 'Getting GHDL' * readme: update --- README.md | 47 ++-- doc/_extensions/.gitempty | 0 doc/building/Building.rst | 72 ----- doc/building/Directories.rst | 50 ---- doc/building/PrecompileVendorPrimitives.rst | 422 ---------------------------- doc/building/gcc/GNULinux-GNAT.rst | 36 --- doc/building/gcc/Windows-MinGW-GNAT.rst | 30 -- doc/building/gcc/index.rst | 54 ---- doc/building/llvm/GNULinux-GNAT.rst | 23 -- doc/building/llvm/Windows-MinGW-GNAT.rst | 26 -- doc/building/llvm/index.rst | 22 -- doc/building/mcode/GNULinux-GNAT.rst | 27 -- doc/building/mcode/Windows-GNATGPL.rst | 36 --- doc/building/mcode/Windows-MinGW-GNAT.rst | 26 -- doc/building/mcode/index.rst | 28 -- doc/conf.py | 30 +- doc/getting/Directories.rst | 50 ++++ doc/getting/GCC.rst | 75 +++++ doc/getting/LLVM.rst | 43 +++ doc/getting/PrecompileVendorPrimitives.rst | 422 ++++++++++++++++++++++++++++ doc/getting/Releases.rst | 65 +---- doc/getting/index.rst | 79 ++++++ doc/getting/mcode.rst | 74 +++++ doc/index.rst | 4 +- 24 files changed, 792 insertions(+), 949 deletions(-) delete mode 100644 doc/_extensions/.gitempty delete mode 100644 doc/building/Building.rst delete mode 100644 doc/building/Directories.rst delete mode 100644 doc/building/PrecompileVendorPrimitives.rst delete mode 100644 doc/building/gcc/GNULinux-GNAT.rst delete mode 100644 doc/building/gcc/Windows-MinGW-GNAT.rst delete mode 100644 doc/building/gcc/index.rst delete mode 100644 doc/building/llvm/GNULinux-GNAT.rst delete mode 100644 doc/building/llvm/Windows-MinGW-GNAT.rst delete mode 100644 doc/building/llvm/index.rst delete mode 100644 doc/building/mcode/GNULinux-GNAT.rst delete mode 100644 doc/building/mcode/Windows-GNATGPL.rst delete mode 100644 doc/building/mcode/Windows-MinGW-GNAT.rst delete mode 100644 doc/building/mcode/index.rst create mode 100644 doc/getting/Directories.rst create mode 100644 doc/getting/GCC.rst create mode 100644 doc/getting/LLVM.rst create mode 100644 doc/getting/PrecompileVendorPrimitives.rst create mode 100644 doc/getting/index.rst create mode 100644 doc/getting/mcode.rst diff --git a/README.md b/README.md index 5204e9131..5ab462a19 100644 --- a/README.md +++ b/README.md @@ -50,11 +50,28 @@ Periodically (not regularly), several binary distributions are made available th ## Building GHDL -In order to follow the traditional way to `configure` and `make`, you need the GNU Ada compiler, GNAT GPL (2014, or later; for x86, 32 or 64 bits). GNAT GPL can be downloaded anonymously from [libre.adacore.com](http://libre.adacore.com/tools/gnat-gpl-edition/). Then, untar and run the *doinstall* script. +GHDL currently supports three different back-ends (code generators). Each has its pros and cons. Here is a short comparison: + +| | pros | cons | observations | +|---|---|---|---| +|mcode | very easy to build | x86_64/i386 only | no executable created from your design | +| | very quick analysis time and can analyze very big designs | simulation is slower | | +| GCC | generated code is faster | analyze can take time (particularly for big units) | the output is an executable | +| | generated code can be debugged | build is more complex | +| | many platforms (x86, x86_64, powerpc, sparc) | | + +LLVM has the same pros/cons as GCC, but it is easier to build. However, coverage (`gcov`) is unique to GCC. + +You can find specific instructions for each of the options in '[Building](http://ghdl.readthedocs.io/en/latest/building/Building.html)'. + +### TL;DR + +In order to follow the traditional way to `configure` and `make`, you need the an Ada compiler. Most GNU/Linux package managers provide a package named `gcc-ada` or `gcc-gnat`. Alternatively, 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. > Depending on the OS and distribution you are using, you will also need to install some toolchain dependencies, such as `zlib`. See '[Building](http://ghdl.readthedocs.io/en/latest/building/Building.html)' for specific package names. -In the GHDL base directory, configure and build: +To use mcode backend (easiest to build), in the GHDL base directory, configure and build: + ```sh $ ./configure --prefix=/usr/local $ make @@ -70,22 +87,6 @@ That's all! > The executable is installed as 'ghdl' in `/usr/local`. To install it to a different path, change the `--prefix` in the call to `configure`. For example, on Windows, you may want to set it to `--prefix=/c/Program Files (x86)/GHDL`. ---- - -Furthermore, each supported compiler has its pros and cons. Here is a short comparison: - -| | pros | cons | observations | -|---|---|---|---| -|mcode | very easy to build | x86_64/i386 only | no executable created from your design | -| | very quick analysis time and can analyze very big designs | simulation is slower | | -| GCC | generated code is faster | analyze can take time (particularly for big units) | the output is an executable | -| | generated code can be debugged | build is more complex | -| | many platforms (x86, x86_64, powerpc, sparc) | | - -LLVM has the same pros/cons as GCC, but it is easier to build. However, coverage (`gcov`) is unique to GCC. - -You can find specific instructions for each of the options in '[Building](http://ghdl.readthedocs.io/en/latest/building/Building.html)'. - # Project structure ## Regular users @@ -99,14 +100,12 @@ You can find specific instructions for each of the options in '[Building](http:/ ## Advanced users -- `libghdl` is a shared library that includes a subset of the regular features plus some features to be used by extension tools (i.e. `libghdl-py`). This is built along with the regular GHDL and it supports both non-synthesisable and synthesisable code. Nonetheless, this is not for users, but for tools built on top of the core. +- `libghdl` is a shared library that includes a subset of the regular features plus some features to be used by extension tools (i.e. `libghdl-py`). This is built along with the regular GHDL and it supports both non-synthesisable and synthesisable code. Nonetheless, this is not for users, but for tools built on top of the core. When configured along with `--enable-synth`, this shared library includes **[experimental]** synthesis features too. - [libghdl-py](python/libghdl) is a Python interface to `libghdl`. Currently, it is only used by `ghdl-ls`; however, it can be useful for advanced users which are willing to build Python utilities based on GHDL. -## Experimental - -- `libghdlsynth` is a shared library that includes the analysis and synthesis features of the core GHDL, but not the pieces for compilation/simulation. +- **[experimental]** [ghdlsynth-beta](https://github.com/tgingold/ghdlsynth-beta) is the integration of GHDL as a frontend plugin module for [Yosys Open SYnthesis Suite](http://www.clifford.at/yosys/), which uses the `libghdlsynth` library. -- [ghdlsynth-beta](https://github.com/tgingold/ghdlsynth-beta) is the integration of GHDL as a frontend plugin module for [Yosys Open SYnthesis Suite](http://www.clifford.at/yosys/), which uses the `libghdlsynth` library. +- **[deprecated]** `libghdlsynth` is a shared library that includes the analysis and synthesis features of the core GHDL, but not the pieces for compilation/simulation. -- `ghdl_simul`, which supports interpreted simulation, is available for historical reasons and for development/debugging only. It is very slow compared to the 'regular' compiled simulation and not all the features are supported. +- **[deprecated]** `ghdl_simul`, which supports interpreted simulation, is available for historical reasons and for development/debugging only. It is very slow compared to the 'regular' compiled simulation and not all the features are supported. diff --git a/doc/_extensions/.gitempty b/doc/_extensions/.gitempty deleted file mode 100644 index e69de29bb..000000000 diff --git a/doc/building/Building.rst b/doc/building/Building.rst deleted file mode 100644 index 9bdecd147..000000000 --- a/doc/building/Building.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. _BUILD: - -Building GHDL from Sources -########################## - -.. rubric:: Download - -GHDL can be downloaded as a `zip-file `_/`tar-file `_ -(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. The installation directory is referred to as ``GHDLRoot``. - -.. 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 `_, and -* `LLVM - Low-Level Virtual Machine `_ . - -Here is a short comparison, so that you can choose the one you want to use: - -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -| Back-end | Pros | Cons | -+============================+============================================================================+=========================================================+ -| :ref:`mcode ` | * Very easy to build | * Simulation is slower | -| | * Very quick analysis | * x86_64/i386 only | -| | * Can handle very large designs | | -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -| :ref:`LLVM ` | * Generated code is faster | * Build is more complex | -| | * Generated code can be debugged (with ``-g``) | | -| | * Easier to build than GCC | | -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -| :ref:`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 - With mcode Backend - With LLVM Backend - With GCC Backend - -.. 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:: - Since GHDL is written in `Ada`, independently of the code generator you use, - the `GNU Ada compiler`, `GNAT GPL`, is required, 2014 (or later) for ``x86`` - (32 or 64 bit). `GNAT GPL` can be downloaded anonymously from `libre.adacore.com `_. - Then, untar and run the doinstall script. Alternatively, most GNU/Linux - provide a package named ``gcc-ada`` or ``gcc-gnat``. - -.. 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 ... diff --git a/doc/building/Directories.rst b/doc/building/Directories.rst deleted file mode 100644 index 6b3c105f0..000000000 --- a/doc/building/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`, `mentor`, - `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 `_. - - * ``windows``: - - * ``mcode``: - * ``appveyor``: - -* ``doc``: `Markdown` and `reStructuredText` sources and auxiliary files to - build the documentation with `Sphinx `_. In fact, - `Read the Docs `_ (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/building/PrecompileVendorPrimitives.rst b/doc/building/PrecompileVendorPrimitives.rst deleted file mode 100644 index 714dc053d..000000000 --- a/doc/building/PrecompileVendorPrimitives.rst +++ /dev/null @@ -1,422 +0,0 @@ -.. _GETTING:PrecompVendor: - -Precompile Vendor Primitives -############################ - -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. There are -also popular simulation and verification libraries like OSVVM [#f1]_ or -UVVM [#f3]_, which can be pre-compiled, too. - -The compilation scripts are writen in the shell languages: *PowerShell* for -*Windows* |trade| and *Bash* for *GNU/Linux*. The compile scripts can colorize -the GHDL warning and error lines with the help of `grc/grcat` [#f4]_. - -Supported Vendors Libraries -=========================== - -* Altera/Intel 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` - -* Lattice (3.6 or later): - - * `ec` - * `ecp`, `ecp2`, `ecp3`, `ecp5u` - * `lptm`, `lptm2` - * `machxo`, `machxo2`, `machxo3l` - * `sc`, `scm` - * `xp`, `xp2` - -* 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 (for VHDL-2008) - - * osvvm - -* UVVM (for VHDL-2008) - - * uvvm-utilities - * uvvm-vvc-framework - * uvvm-vip-avalon_mm - * uvvm-vip-axi_lite - * uvvm-vip-axi_stream - * uvvm-vip-gpio - * uvvm-vip-i2c - * uvvm-vip-sbi - * uvvm-vip-spi - * uvvm-vip-uart - ---------------------------------------------------------------------- - -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` or `-Source`. - -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` or `-Output`. - -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` or `-GHDL` to -the scripts. - -If the vendor library compilation is used very often, we recommend configuring -these parameters in `config.sh` or `config.psm1`, so the command line can be -shortened to the essential parts. - ---------------------------------------------------------------------- - -Compiling on Linux -================== - -* **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 - ``` - -* **Step 2 - Start the compilation script(s)** - - .. code-block:: Bash - - $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all - $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all - $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all - $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all - $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all - $ /usr/local/lib/ghdl/vendors/compile-uvvm.sh --all - ``` - - In most cases GHDL is installed into `/usr/local/`. The scripts are - installed into the `lib` 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 56K Mar 09 17:41 altera - drwxr-xr-x 2 56K Mar 09 17:42 lattice - drwxr-xr-x 2 56K Mar 09 17:48 osvvm - drwxr-xr-x 2 56K Mar 09 17:58 uvvm - drwxr-xr-x 2 56K Mar 09 17:58 xilinx-ise - drwxr-xr-x 2 56K Mar 09 17:48 xilinx-vivado - ``` - - ---------------------------------------------------------------------- - -Compiling on Windows -==================== - -* **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 - -* **Step 2 - Start the compilation script(s)** - - .. code-block:: PowerShell - - PS> \libraries\vendors\compile-altera.ps1 -All - PS> \libraries\vendors\compile-lattice.ps1 -All - PS> \libraries\vendors\compile-xilinx-ise.ps1 -All - PS> \libraries\vendors\compile-xilinx-vivado.ps1 -All - PS> \libraries\vendors\compile-osvvm.ps1 -All - PS> \libraries\vendors\compile-uvvm.ps1 -All - -* **Step 3 - Viewing the result** - This creates vendor directories in your current working directory and - compiles the vendor files into them. - - .. code-block:: PowerShell - - PS> dir - Directory: D:\temp\ghdl - - Mode LastWriteTime Length Name - ---- ------------- ------ ---- - d---- 09.03.2018 19:33 altera - d---- 09.03.2018 19:38 lattice - d---- 09.03.2018 19:38 osvvm - d---- 09.03.2018 19:45 uvvm - d---- 09.03.2018 19:06 xilinx-ise - d---- 09.03.2018 19:40 xilinx-vivado - - ---------------------------------------------------------------------- - -Configuration Files -====================== - -For Linux: `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/17.1" - InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.9_x64" - InstallationDirectory[OSVVM]="/home//git/GitHub/osvvm" - InstallationDirectory[UVVM]="/home//git/GitHub/uvvm_all" - InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7" - InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2017.4" - - -For Windows: `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\17.1"; - "LatticeDiamond" = "C:\Lattice\Diamond\3.9_x64"; - "XilinxISE" = "C:\Xilinx\14.7\ISE_DS"; - "XilinxVivado" = "C:\Xilinx\Vivado\2017.4"; - "OSVVM" = "D:\git\GitHub\osvvm"; - "UVVM" = "D:\git\GitHub\uvvm_all" - } - - -Selectable Options for the 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. - - -Selectable Options for the 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 - .. [#f3] UVVM https://github.com/UVVM/UVVM_All - .. [#f4] Generic Colourizer http://kassiopeia.juls.savba.sk/~garabik/software/grc.html diff --git a/doc/building/gcc/GNULinux-GNAT.rst b/doc/building/gcc/GNULinux-GNAT.rst deleted file mode 100644 index e6c7f61b4..000000000 --- a/doc/building/gcc/GNULinux-GNAT.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _BUILD:gcc:GNULinux-GNAT: - -GCC Backend on GNU/Linux with GCC/GNAT -###################################### - -.. 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 - $ 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. diff --git a/doc/building/gcc/Windows-MinGW-GNAT.rst b/doc/building/gcc/Windows-MinGW-GNAT.rst deleted file mode 100644 index 09274a534..000000000 --- a/doc/building/gcc/Windows-MinGW-GNAT.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _BUILD:gcc:Windows-MinGW-GNAT: - -GCC Backend 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 - $ mkdir build - $ cd build - $ ../configure --prefix=PREFIX - $ make - $ make install diff --git a/doc/building/gcc/index.rst b/doc/building/gcc/index.rst deleted file mode 100644 index 23b6ebfa2..000000000 --- a/doc/building/gcc/index.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _BUILD:gcc: - -GCC Backend -########### - -.. 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 or 7.x - -.. rubric:: Supported platforms - -* :doc:`GNULinux-GNAT` -* :doc:`Windows-MinGW-GNAT` - - -.. 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 (and AIX ?) 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``, ``function rs6000_output_function_epilogue`` (as of gcc 4.8): - - .. CODE:: C - - else if (! strcmp (language_string, "GNU Objective-C")) - i = 14; - else - - gcc_unreachable (); - + i = 0; - fprintf (file, "%d,", i); - - /* 8 single bit fields: global linkage (not set for C extern linkage), - -.. toctree:: - :hidden: - - GNU/Linux with GCC/GNAT - Windows with GCC/GNAT (MinGW) diff --git a/doc/building/llvm/GNULinux-GNAT.rst b/doc/building/llvm/GNULinux-GNAT.rst deleted file mode 100644 index 5bb1fcad7..000000000 --- a/doc/building/llvm/GNULinux-GNAT.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _BUILD:llvm:GNULinux-GNAT: - -LLVM Backend on GNU/Linux with GCC/GNAT -####################################### - -.. HINT:: You need to install LLVM (usually depends on ``libedit``, see :ghdlsharp:`29`). Debugging is only supported with LLVM 3.5. - -* First configure GHDL with the proper arg ``./configure --with-llvm-config``. If ``llvm-config`` is not in your path, you can specify it: ``./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config``. - -* Then, build with ``make`` and install with ``make install``. - -.. rubric:: Example: - -.. code-block:: Bash - - $ cd - $ 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/building/llvm/Windows-MinGW-GNAT.rst b/doc/building/llvm/Windows-MinGW-GNAT.rst deleted file mode 100644 index 59d70023f..000000000 --- a/doc/building/llvm/Windows-MinGW-GNAT.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _BUILD:llvm:Windows-MinGW-GNAT: - -LLVM Backend on Windows with GCC/GNAT (MinGW) -############################################# - -On Windows with MinGW, 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``. - -.. rubric:: Example: - -.. code-block:: Bash - - $ cd - $ mkdir build - $ cd build - $ ../configure --prefix=PREFIX - $ make - $ make install diff --git a/doc/building/llvm/index.rst b/doc/building/llvm/index.rst deleted file mode 100644 index 72c2c50c1..000000000 --- a/doc/building/llvm/index.rst +++ /dev/null @@ -1,22 +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 or 8.0 - -.. rubric:: Supported platforms - -* :doc:`GNULinux-GNAT` -* :doc:`Windows-MinGW-GNAT` -* Mac OS - -.. toctree:: - :hidden: - - GNU/Linux with GCC/GNAT - Windows with GCC/GNAT (MinGW) diff --git a/doc/building/mcode/GNULinux-GNAT.rst b/doc/building/mcode/GNULinux-GNAT.rst deleted file mode 100644 index 2d7598599..000000000 --- a/doc/building/mcode/GNULinux-GNAT.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _BUILD:mcode:GNULinux-GNAT: - -mcode Backend on GNU/Linux with GCC/GNAT -######################################## - -On Linux, 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``. You may need super user privileges (``sudo ...``). - - -.. rubric:: Example: - -.. code-block:: Bash - - $ cd - $ mkdir build - $ cd build - $ ../configure --prefix=PREFIX - $ make - $ make install diff --git a/doc/building/mcode/Windows-GNATGPL.rst b/doc/building/mcode/Windows-GNATGPL.rst deleted file mode 100644 index c767343be..000000000 --- a/doc/building/mcode/Windows-GNATGPL.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _BUILD:mcode:Windows-GNATGPL: - -mcode Backend on Windows with GNAT GPL -###################################### - -Requirements -============ - -* GNAT GPL from http://libre.adacore.com -* PowerShell 4 -* PowerShell Community Extensions (PSCX) - - -Scripts and Parameters -====================== - -`compile.ps1` -------------- - -.. code-block:: plain - - 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 diff --git a/doc/building/mcode/Windows-MinGW-GNAT.rst b/doc/building/mcode/Windows-MinGW-GNAT.rst deleted file mode 100644 index f1482ccb8..000000000 --- a/doc/building/mcode/Windows-MinGW-GNAT.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _BUILD:mcode:Windows-MinGW-GNAT: - -mcode Backend on Windows with GCC/GNAT (MinGW) -############################################## - -On Windows with MinGW, 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``. - -.. rubric:: Example: - -.. code-block:: Bash - - $ cd - $ mkdir build - $ cd build - $ ../configure --prefix=PREFIX - $ make - $ make install diff --git a/doc/building/mcode/index.rst b/doc/building/mcode/index.rst deleted file mode 100644 index 92eeaabd4..000000000 --- a/doc/building/mcode/index.rst +++ /dev/null @@ -1,28 +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. - - -.. rubric:: Requirements - -* GCC (Gnu Compiler Collection) -* GNAT (Ada compiler for GCC) - - -.. rubric:: Supported platforms - -* :doc:`GNULinux-GNAT` -* :doc:`Windows-GNATGPL` -* :doc:`Windows-MinGW-GNAT` - -.. toctree:: - :hidden: - - GNU/Linux with GCC/GNAT - Windows with GNAT GPL - Windows with GCC/GNAT (MinGW) diff --git a/doc/conf.py b/doc/conf.py index efa30f23e..014cbd13b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -14,17 +14,10 @@ import sys, os, shlex, re, subprocess -# http://docs.readthedocs.io/en/latest/getting_started.html#in-markdown -from recommonmark.parser import CommonMarkParser -source_parsers = { '.md': CommonMarkParser, } - # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('.')) -# sys.path.insert(0, os.path.abspath('../py')) -sys.path.insert(0, os.path.abspath('_extensions')) -# sys.path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme')) # -- General configuration ------------------------------------------------ @@ -36,6 +29,7 @@ needs_sphinx = '1.5' # ones. extensions = [ # Standard Sphinx extensions + 'recommonmark', 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', @@ -55,9 +49,11 @@ extensions = [ templates_path = ['_templates', '_themes'] # The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] -source_suffix = ['.rst', '.md'] +source_suffix = { + '.rst': 'restructuredtext', + #'.txt': 'markdown', + '.md': 'markdown', +} # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -67,21 +63,22 @@ master_doc = 'index' # General information about the project. project = u'GHDL' -copyright = u'2015-2017, Tristan Gingold and contributors' +copyright = u'2002-2019, Tristan Gingold and contributors' author = u'Tristan Gingold and contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -# + try: with open('../configure') as verin: for line in verin: - line = re.findall(r'ghdl_version=\"(.+)\"', line) + line = re.findall(r'ghdl_version=\"([0-9].+)\"', line) if line: version=line[0] -except Exception, e: - print "cannot extract version: %s" % e + break +except Exception as e: + print('cannot extract version: %s' % e) version = "latest" pass @@ -89,7 +86,6 @@ release = version # The full version, including alpha/beta/rc tags. # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -# # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = None @@ -334,7 +330,7 @@ texinfo_documents = [ # ============================================================================== intersphinx_mapping = { 'python': ('https://docs.python.org/3.6/', None), - 'poc': ('http://poc-library.readthedocs.io/en/release', None), + 'poc': ('https://poc-library.readthedocs.io/en/release', None), # 'ghdl': ('http://ghdl.readthedocs.io/en/latest', None) } diff --git a/doc/getting/Directories.rst b/doc/getting/Directories.rst new file mode 100644 index 000000000..2d5b575d8 --- /dev/null +++ b/doc/getting/Directories.rst @@ -0,0 +1,50 @@ +.. _BUILD:dir_structure: + +Directory structure +################### + +* ``src``: sources of GHDL, all of them in Ada. + +* ``libraries``: mostly third party libraries such as, `ieee`, `mentor`, + `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 `_. + + * ``windows``: + + * ``mcode``: + * ``appveyor``: + +* ``doc``: `Markdown` and `reStructuredText` sources and auxiliary files to + build the documentation with `Sphinx `_. In fact, + `Read the Docs `_ (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 new file mode 100644 index 000000000..b8c46f63f --- /dev/null +++ b/doc/getting/GCC.rst @@ -0,0 +1,75 @@ +.. _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 or 7.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 + $ 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 (and AIX ?) 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``, ``function rs6000_output_function_epilogue`` (as of gcc 4.8): + + .. 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 new file mode 100644 index 000000000..9190549d2 --- /dev/null +++ b/doc/getting/LLVM.rst @@ -0,0 +1,43 @@ +.. _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 or 8.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 only supported with LLVM 3.5. + +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 + $ 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 new file mode 100644 index 000000000..714dc053d --- /dev/null +++ b/doc/getting/PrecompileVendorPrimitives.rst @@ -0,0 +1,422 @@ +.. _GETTING:PrecompVendor: + +Precompile Vendor Primitives +############################ + +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. There are +also popular simulation and verification libraries like OSVVM [#f1]_ or +UVVM [#f3]_, which can be pre-compiled, too. + +The compilation scripts are writen in the shell languages: *PowerShell* for +*Windows* |trade| and *Bash* for *GNU/Linux*. The compile scripts can colorize +the GHDL warning and error lines with the help of `grc/grcat` [#f4]_. + +Supported Vendors Libraries +=========================== + +* Altera/Intel 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` + +* Lattice (3.6 or later): + + * `ec` + * `ecp`, `ecp2`, `ecp3`, `ecp5u` + * `lptm`, `lptm2` + * `machxo`, `machxo2`, `machxo3l` + * `sc`, `scm` + * `xp`, `xp2` + +* 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 (for VHDL-2008) + + * osvvm + +* UVVM (for VHDL-2008) + + * uvvm-utilities + * uvvm-vvc-framework + * uvvm-vip-avalon_mm + * uvvm-vip-axi_lite + * uvvm-vip-axi_stream + * uvvm-vip-gpio + * uvvm-vip-i2c + * uvvm-vip-sbi + * uvvm-vip-spi + * uvvm-vip-uart + +--------------------------------------------------------------------- + +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` or `-Source`. + +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` or `-Output`. + +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` or `-GHDL` to +the scripts. + +If the vendor library compilation is used very often, we recommend configuring +these parameters in `config.sh` or `config.psm1`, so the command line can be +shortened to the essential parts. + +--------------------------------------------------------------------- + +Compiling on Linux +================== + +* **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 + ``` + +* **Step 2 - Start the compilation script(s)** + + .. code-block:: Bash + + $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all + $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all + $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all + $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all + $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all + $ /usr/local/lib/ghdl/vendors/compile-uvvm.sh --all + ``` + + In most cases GHDL is installed into `/usr/local/`. The scripts are + installed into the `lib` 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 56K Mar 09 17:41 altera + drwxr-xr-x 2 56K Mar 09 17:42 lattice + drwxr-xr-x 2 56K Mar 09 17:48 osvvm + drwxr-xr-x 2 56K Mar 09 17:58 uvvm + drwxr-xr-x 2 56K Mar 09 17:58 xilinx-ise + drwxr-xr-x 2 56K Mar 09 17:48 xilinx-vivado + ``` + + +--------------------------------------------------------------------- + +Compiling on Windows +==================== + +* **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 + +* **Step 2 - Start the compilation script(s)** + + .. code-block:: PowerShell + + PS> \libraries\vendors\compile-altera.ps1 -All + PS> \libraries\vendors\compile-lattice.ps1 -All + PS> \libraries\vendors\compile-xilinx-ise.ps1 -All + PS> \libraries\vendors\compile-xilinx-vivado.ps1 -All + PS> \libraries\vendors\compile-osvvm.ps1 -All + PS> \libraries\vendors\compile-uvvm.ps1 -All + +* **Step 3 - Viewing the result** + This creates vendor directories in your current working directory and + compiles the vendor files into them. + + .. code-block:: PowerShell + + PS> dir + Directory: D:\temp\ghdl + + Mode LastWriteTime Length Name + ---- ------------- ------ ---- + d---- 09.03.2018 19:33 altera + d---- 09.03.2018 19:38 lattice + d---- 09.03.2018 19:38 osvvm + d---- 09.03.2018 19:45 uvvm + d---- 09.03.2018 19:06 xilinx-ise + d---- 09.03.2018 19:40 xilinx-vivado + + +--------------------------------------------------------------------- + +Configuration Files +====================== + +For Linux: `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/17.1" + InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.9_x64" + InstallationDirectory[OSVVM]="/home//git/GitHub/osvvm" + InstallationDirectory[UVVM]="/home//git/GitHub/uvvm_all" + InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7" + InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2017.4" + + +For Windows: `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\17.1"; + "LatticeDiamond" = "C:\Lattice\Diamond\3.9_x64"; + "XilinxISE" = "C:\Xilinx\14.7\ISE_DS"; + "XilinxVivado" = "C:\Xilinx\Vivado\2017.4"; + "OSVVM" = "D:\git\GitHub\osvvm"; + "UVVM" = "D:\git\GitHub\uvvm_all" + } + + +Selectable Options for the 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. + + +Selectable Options for the 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 + .. [#f3] 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 index 81286a14a..676ffd421 100644 --- a/doc/getting/Releases.rst +++ b/doc/getting/Releases.rst @@ -31,8 +31,7 @@ Downloading pre-built packages from helpers import printReleaseTab printReleaseTab('data', latex=True) -Pre-built packages of older releases -==================================== +.. rubric :: Pre-built packages of older releases .. only:: html @@ -58,10 +57,9 @@ Downloading Source Files .. _RELEASE:Sources:Zip: -Downloading from GitHub -======================= +.. rubric :: Tarball/zip-file -GHDL can be downloaded as a zip-file from GitHub. See the following table, to +GHDL can be downloaded as a zip-file or tarball from GitHub. See the following table, to choose your desired format/version: .. only:: html @@ -84,21 +82,17 @@ choose your desired format/version: .. HINT:: - To download a specific version of GHDL, use these alternative URL, where ```` is ``tar`` or ``zip``: ``https://api.github.com/repos/ghdl/ghdl/ball/``. + To download a specific version of GHDL, use this alternative URL, where ```` is ``tar.gz`` or ``zip``: ``https://codeload.github.com/ghdl/ghdl//``. .. _RELEASE:Sources:GitClone: -Downloading via ``git clone`` -============================= +.. 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. -The created folder :file:`\\ghdl` is used as :file:`` in -later instructions or on other pages in this documentation. - +----------+----------------------------------------+ | Protocol | GitHub Repository URL | +==========+========================================+ @@ -111,12 +105,7 @@ later instructions or on other pages in this documentation. Execute ``git checkout -b stable `` after ``git clone``, to checkout a specific version of GHDL. - -On Linux --------- - -Command line instructions to clone GHDL onto a Linux machine with HTTPS -protocol: +Command line instructions to clone GHDL with HTTPS protocol: .. code-block:: Bash @@ -125,8 +114,7 @@ protocol: cd ghdl git remote rename origin github -Command line instructions to clone GHDL onto a Linux machine machine with SSH -protocol: +Command line instructions to clone GHDL with SSH protocol: .. code-block:: Bash @@ -135,40 +123,9 @@ protocol: cd ghdl git remote rename origin github - -On OS X -------- - -Please see the Linux instructions. - - -On Windows ----------- - .. NOTE:: - All Windows command line instructions are intended for :program:`Windows PowerShell`, - if not marked otherwise. So executing the following instructions in Windows - Command Prompt (:program:`cmd.exe`) won't function or will result in errors! - :program:`Windows PowerShell` can be installed or upgraded to v5.1 by installing the - `Windows Management Framework `_. - -Command line instructions to clone GHDL onto a Windows machine with HTTPS -protocol: - -.. code-block:: PowerShell - - cd GitRoot - git clone "https://github.com/ghdl/ghdl.git" ghdl - cd ghdl - git remote rename origin github - -Command line instructions to clone GHDL onto a Windows machine with SSH -protocol: - -.. code-block:: PowerShell - - cd GitRoot - git clone "ssh://git@github.com:ghdl/ghdl.git" ghdl - cd ghdl - git remote rename origin github + 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 `_. diff --git a/doc/getting/index.rst b/doc/getting/index.rst new file mode 100644 index 000000000..f64e44caf --- /dev/null +++ b/doc/getting/index.rst @@ -0,0 +1,79 @@ +.. _BUILD: + +Building GHDL from Sources +########################## + +.. rubric :: Download + +GHDL can be downloaded as a `zip-file `_/`tar-file `_ +(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 `_ (2014, or later; for x86, 32 or 64 bits). + Then, untar and run the doinstall script. + +.. 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 `_) +* LLVM - Low-Level Virtual Machine (`llvm.org `_) + +Here is a short comparison, so that you can choose the one you want to use: + ++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ +| Back-end | Pros | Cons | ++============================+============================================================================+=========================================================+ +| :ref:`mcode ` | * Very easy to build | * Simulation is slower | +| | * Very quick analysis | * x86_64/i386 only | +| | * Can handle very large designs | | ++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ +| :ref:`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 ` | * 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. + * For 64 bit, no native compiler exists from AdaCore. + * That Ada to .NET compiler, which might work for 32 or 64 bit. is not up-to-date. diff --git a/doc/getting/mcode.rst b/doc/getting/mcode.rst new file mode 100644 index 000000000..5e6fbbf68 --- /dev/null +++ b/doc/getting/mcode.rst @@ -0,0 +1,74 @@ +.. _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 + $ 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:: plain + + 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 diff --git a/doc/index.rst b/doc/index.rst index 2df9c2c9f..b1bd73c23 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -103,8 +103,8 @@ LRM) is a plus. :hidden: getting/Releases - Building GHDL - building/PrecompileVendorPrimitives + Building GHDL + getting/PrecompileVendorPrimitives .. raw:: latex -- cgit v1.2.3