From ba8efb1df06cbdac73c8e1b3baa9486b6a29e804 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sat, 4 Mar 2017 21:52:39 +0100 Subject: Fixed encoding problem. Replaced :samp: by ``. --- doc/building/Building.rst | 98 ++++++++++++++++++++++++++++++----------------- doc/conf.py | 3 +- doc/index.rst | 28 +++++++------- doc/prolog.inc | 2 +- 4 files changed, 78 insertions(+), 53 deletions(-) diff --git a/doc/building/Building.rst b/doc/building/Building.rst index e46b9c0b7..16d087342 100644 --- a/doc/building/Building.rst +++ b/doc/building/Building.rst @@ -1,49 +1,47 @@ .. _BUILD: -Building GHDL -############# +Building GHDL from Sources +########################## -GHDL currently supports three supported different backends (code generators): `mcode` (built-in), `GCC `_ and `LLVM `_ . Here is a short comparison, so that you can choose the one you want to use: +.. rubric:: Download -+------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+ -| | pros | cons | -+========================+==========================================================================================+=========================================================+ -| `mcode` | - very easy to build | - :samp:`x86_64`/:samp:`i386` only | -| | - very quick analysis | - simulation is slower | -| | - can handle very large designs | | -+------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+ -| GCC | - generated code is faster (particularly with :samp:`-O` or :samp:`-O2`) | - analysis can take time (particularly for large units) | -| | - generated code can be debugged (with :samp:`-g`) | - build is more complex | -| | - ported to many platforms (:samp:`x86`, :samp:`x86_64`, :samp:`powerpc`, :samp:`sparc`) | | -+------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+ -| LLVM | - Same as GCC | Coverage, :samp:`gcov`, is unique to GCC | -| | - Easier to build than GCC | | -+------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+ +GHDL can be downloaded as a `zip-file `_ +(latest 'master' branch) or cloned with ``git clone`` from GitHub. GitHub +offers HTTPS and SSH as transfer protocols. See the :ref:`Download ` +page for further details. The installation directory is referred to as ``GHDLRoot``. -.. 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 :samp:`-r` can be replaced with direct execution of the binary. See section :ref:`USING:QuickStart`. ++----------+-----------------------------------------------------------+ +| Protocol | Git Clone Command | ++==========+===========================================================+ +| HTTPS | ``git clone https://github.com/tgingold/ghdl.git ghdl`` | ++----------+-----------------------------------------------------------+ +| SSH | ``git clone ssh://git@github.com:tgingold/ghdl.git ghdl`` | ++----------+-----------------------------------------------------------+ -After making your choice, you can jump to the corresponding section below. However, we suggest you to read :ref:`BUILD:dir_structure` before, so that you know where the content is placed and which temporal files are expected to be created. +.. rubric:: Available back-ends -.. 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 :samp:`x86` (32 or 64 bits). `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 :samp:`gcc-ada` or :samp:`gcc-gnat`. +GHDL currently supports three supported different back-ends (code generators): +* `mcode` (built-in), +* `GCC `_, and +* `LLVM `_ . -.. TODO:: +Here is a short comparison, so that you can choose the one you want to use: - * @1138 Backtraces optional -patchable- - * Very briefly, why is mcode faster for analysis and GCC/LLVM for simulation? - * The only other dependency is zlib (On ubuntu/debian, install zlib1g-dev). - * From :ghdlsharp:`279`: - * GCC: GHDL generates an intermediate representation for GCC, which creates an executable. So GHDL acts a a new language frontend like C for the GCC and uses the existing backend to generated e.g. x86(-64) binary code. - * LLVM: GHDL generates instructions for the LLVM abstract register machine, which then generates x86(-64) instructions for the host system. - * mcode: GHDL generates the x86(-64) instructions in memory and executes the model. - * gcc is currently only supported on Linux, because you need to compile a complete GCC from zero and add GHDL as a frontend into the GCC. Compiling the complete GCC suite plus GHDL takes a lot of time. I think it's not possible to finish the compile task in the bounds of a Travis-CI run. ++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ +| Back-end | Pros | Cons | ++============================+============================================================================+=========================================================+ +| :ref:`mcode ` | * Very easy to build | * ``x86_64``/``i386`` only | +| | * Very quick analysis | * Simulation is slower | +| | * Can handle very large designs | | ++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ +| :ref:`GCC ` | * Generated code is faster (particularly with ``-O`` or ``-O2``) | * Analysis can take time (particularly for large units) | +| | * Generated code can be debugged (with ``-g``) | * Build is more complex | +| | * Ported to many platforms (``x86``, ``x86_64``, ``powerpc``, ``sparc``) | * Code coverage collection (``gcov``) is unique to GCC | ++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ +| :ref:`LLVM ` | * Same as GCC | | +| | * Easier to build than GCC | | ++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ - -GHDL can be build with three different back-ends: mcode, LLVM or GCC. - -* :ref:`mcode ` -* :ref:`LLVM ` -* :ref:`GCC ` - .. toctree:: :hidden: @@ -52,3 +50,31 @@ GHDL can be build with three different back-ends: mcode, LLVM or GCC. With LLVM Backend With GCC Backend TestSuites + +.. 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` before, so that you +know where the content is placed and which temporal 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 bits). `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``. + +.. TODO:: + + * @1138 Backtraces optional -patchable- + * Very briefly, why is mcode faster for analysis and GCC/LLVM for simulation? + * The only other dependency is zlib (On ubuntu/debian, install zlib1g-dev). + * From :ghdlsharp:`279`: + * GCC: GHDL generates an intermediate representation for GCC, which creates an executable. So GHDL acts a a new language frontend like C for the GCC and uses the existing backend to generated e.g. x86(-64) binary code. + * LLVM: GHDL generates instructions for the LLVM abstract register machine, which then generates x86(-64) instructions for the host system. + * mcode: GHDL generates the x86(-64) instructions in memory and executes the model. + * gcc is currently only supported on Linux, because you need to compile a complete GCC from zero and add GHDL as a frontend into the GCC. Compiling the complete GCC suite plus GHDL takes a lot of time. I think it's not possible to finish the compile task in the bounds of a Travis-CI run. diff --git a/doc/conf.py b/doc/conf.py index a42f29e6e..c04bb5b4e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -153,8 +153,7 @@ try: with open(prologPath, "r") as prologFile: rst_prolog = prologFile.read() except Exception as ex: - print("CWD: " + str(os.getcwd())) - print("[ERROR:] File '{0!s}' not found.".format(prologPath)) + print("[ERROR:] While reading '{0!s}'.".format(prologPath)) print(ex) rst_prolog = "" diff --git a/doc/index.rst b/doc/index.rst index 6d86f79b1..17b95dc2e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -36,10 +36,10 @@ Lorem ipsum dolor sit amet... :caption: Introduction :hidden: - 0_Intro/WhatIsVHDL - 0_Intro/WhatIsGHDL - 0_Intro/Contributing - 0_Intro/Copyrights + intro/WhatIsVHDL + intro/WhatIsGHDL + intro/Contributing + intro/Copyrights License/gpl-2.0 .. raw:: latex @@ -50,9 +50,9 @@ Lorem ipsum dolor sit amet... :caption: GHDL usage :hidden: - 1_Using/QuickStartGuide - 1_Using/InvokingGHDL - 1_Using/Simulation + using/QuickStartGuide + using/InvokingGHDL + using/Simulation .. raw:: latex @@ -62,9 +62,9 @@ Lorem ipsum dolor sit amet... :caption: Getting GHDL :hidden: - 2_Getting/Releases - 3_Building/Building - 3_Building/VendorPrimitives + getting/Releases + Building GHDL building/building> + building/PrecompileVendorPrimitives .. raw:: latex @@ -74,10 +74,10 @@ Lorem ipsum dolor sit amet... :caption: Implementation References :hidden: - 4_References/CommandReference - 4_References/CodingStyle - 4_References/ImplementationOfVHDL - 4_References/ImplementationOfVITAL + references/CommandReference + references/CodingStyle + references/ImplementationOfVHDL + references/ImplementationOfVITAL .. raw:: latex diff --git a/doc/prolog.inc b/doc/prolog.inc index 94490f67c..a0c1f3bf8 100644 --- a/doc/prolog.inc +++ b/doc/prolog.inc @@ -1,4 +1,4 @@ -.. # preload commonly known graphical characters like © +.. # preload commonly known graphical characters like © .. include:: .. # define a hard kine break for HTML -- cgit v1.2.3