diff options
author | 1138-4EB <1138-4EB@users.noreply.github.com> | 2017-02-22 06:09:26 +0100 |
---|---|---|
committer | tgingold <tgingold@users.noreply.github.com> | 2017-12-10 12:02:05 +0100 |
commit | 1a38eff0e9f9814f5d0615e238544fac62d2f1f3 (patch) | |
tree | 05f1299398efa8ff2d760e4e558e21e87d3421fe | |
parent | 669fd99724492f9c8983f414b43e7dfb7bec0dd0 (diff) | |
download | ghdl-1a38eff0e9f9814f5d0615e238544fac62d2f1f3.tar.gz ghdl-1a38eff0e9f9814f5d0615e238544fac62d2f1f3.tar.bz2 ghdl-1a38eff0e9f9814f5d0615e238544fac62d2f1f3.zip |
Remove scrollbar in small screens
Fix gitter shield link
Fix first example of QuickStartGuide
-rw-r--r-- | doc/_static/theme_overrides.css | 8 | ||||
-rw-r--r-- | doc/changelog/Roadmap.rst | 1 | ||||
-rw-r--r-- | doc/getting/Building.rst | 24 | ||||
-rw-r--r-- | doc/shields.txt | 2 | ||||
-rw-r--r-- | doc/using/QuickStartGuide.rst | 44 |
5 files changed, 25 insertions, 54 deletions
diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css index cb4555384..a1a61eae9 100644 --- a/doc/_static/theme_overrides.css +++ b/doc/_static/theme_overrides.css @@ -22,10 +22,10 @@ footer hr {margin-bottom: 10px} @media screen and (max-width: 768px){ .wy-nav-top i {padding-top:7px} .wy-nav-content-wrap{margin-left:0px} - .wy-nav-content-wrap.shift{margin-left:265px;position: static;} - .wy-nav-side.shift{width:265px;padding-bottom: 40px;} - .rst-versions{width:265px} - .wy-side-scroll{width:260px;} + .wy-nav-content-wrap.shift{margin-left:260px;position: static;} + .wy-nav-side.shift{width:260px;padding-bottom: 40px;} + .rst-versions{width:260px} + .wy-side-scroll{width:280px;} } /*Fix shields in small screens*/ diff --git a/doc/changelog/Roadmap.rst b/doc/changelog/Roadmap.rst index 6138e8ea9..d5b3be9fb 100644 --- a/doc/changelog/Roadmap.rst +++ b/doc/changelog/Roadmap.rst @@ -16,5 +16,6 @@ I have several axes for `GHDL` improvements: .. TODO:: - Convert VendorPrimitives Markdown to RST + - SVG images are not shown in the PDF. That's because LaTeX is used. Can any package be added to allow so? .. todolist::
\ No newline at end of file diff --git a/doc/getting/Building.rst b/doc/getting/Building.rst index c52d3f5da..68f086c56 100644 --- a/doc/getting/Building.rst +++ b/doc/getting/Building.rst @@ -12,15 +12,15 @@ GHDL currently supports three supported different backends (code generators): `m | | - 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) | +| 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` | | +| LLVM | - Same as GCC | Coverage, :samp:`gcov`, is unique to GCC | +| | - Easier to build than 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 :samp:`-r` can be replaced with direct execution of the binary. +.. 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. 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. @@ -73,11 +73,11 @@ LLVM backend GNU/Linux ---------------- -You need to install `LLVM` (usually depends on :samp:`libedit`). The supported versions are 3.5 till 3.9, but debugging is only supported with `LLVM` 3.5. +You need to install LLVM (usually depends on :samp:`libedit`). The supported versions are 3.5 till 3.9, but debugging is only supported with LLVM 3.5. - First configure GHDL with the proper arg :samp:`./configure --with-llvm-config`. If :samp:`llvm-config` is not in your path, you can specify it: :samp:`./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config`. -.. HINT:: If you want to have stack backtraces on errors (like assert failure or index of out bounds), you need to configure and build :samp:`libbacktrace` from `GCC` (you don't need to configure `GCC`). Then add the following arg to configure: :samp:`--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a` +.. HINT:: If you want to have stack backtraces on errors (like assert failure or index of out bounds), you need to configure and build :samp:`libbacktrace` from GCC (you don't need to configure GCC). Then add the following arg to configure: :samp:`--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a` - Then build with :samp:`make` and install with :samp:`make install`. @@ -92,9 +92,9 @@ GCC backend .. TODO:: - - You need to download and untar the sources of `GCC` version 4.9 [do not modify this line as this is read by scripts]. + - You need to download and untar the sources of GCC version 4.9 [do not modify this line as this is read by scripts]. - gcc object dir - - Notes for developpers developping with the GCC backend: 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:: + - Notes for developpers developping with the GCC backend: 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 @@ -105,7 +105,7 @@ GCC backend GNU/Linux ---------------- -- First configure GHDL, specify `GCC` source dir and :samp:`prefix` (replace :samp:`/usr/local` with your desired installation directory):: +- First configure GHDL, specify GCC source dir and :samp:`prefix` (replace :samp:`/usr/local` with your desired installation directory):: ./configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local @@ -113,9 +113,9 @@ GNU/Linux make copy-sources -.. HINT:: There are some dependencies for building `GCC` (:samp:`gmp`, :samp:`mpfr` and :samp:`mpc`). If you have not them installed on your system, you can either build them manually or use the :samp:`download_prerequisite` script provided in the `GCC` source tree (recommended): :samp:`cd /path/to/gcc/source/dir && ./contrib/download_prerequisites` +.. HINT:: There are some dependencies for building GCC (:samp:`gmp`, :samp:`mpfr` and :samp:`mpc`). If you have not them installed on your system, you can either build them manually or use the :samp:`download_prerequisite` script provided in the GCC source tree (recommended): :samp:`cd /path/to/gcc/source/dir && ./contrib/download_prerequisites` -- Then, configure `GCC`. The list of :samp:`--disable` configure options can be adjusted to your needs. GHDL does not require all these optional libraries and disabling them will speed-up the build:: +- Then, configure GCC. The list of :samp:`--disable` configure options can be adjusted to your needs. GHDL does not require all these optional libraries and disabling them will speed-up the build:: ../gcc-4.9.3/configure --prefix=/usr/local --enable-languages=c,vhdl \ --disable-bootstrap --disable-lto --disable-multilib --disable-libssp \ @@ -123,7 +123,7 @@ GNU/Linux .. HINT:: Note that the prefix directory must be the same as the one used to configure GHDL. If you have manually built :samp:`gmp`/:samp:`mpfr`/:samp:`mpc` (without using the script in :samp:`contrib`) and if you have installed them in a non-standard directory, you may need to add :samp:`--with-gmp=GMP_INSTALL_DIR`. -- Then, build and install `GCC`:: +- Then, build and install GCC:: make -j2 && make install diff --git a/doc/shields.txt b/doc/shields.txt index bb521789d..f1fac33b3 100644 --- a/doc/shields.txt +++ b/doc/shields.txt @@ -30,7 +30,7 @@ :target: https://mail.gna.org/listinfo/ghdl-discuss/ .. |SHIELD:gitter| image:: https://img.shields.io/gitter/room/ghdl1/Lobby.svg?colorB=4cb696 - :target: https://gitter.im/ghdl/ghdl1 + :target: https://gitter.im/ghdl1/Lobby :alt: Talk to us on Gitter .. |SHIELD:issues-new| image:: https://img.shields.io/badge/new-issue-yellowgreen.svg?style=flat diff --git a/doc/using/QuickStartGuide.rst b/doc/using/QuickStartGuide.rst index 7fd3c946f..c0117833f 100644 --- a/doc/using/QuickStartGuide.rst +++ b/doc/using/QuickStartGuide.rst @@ -33,33 +33,15 @@ To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` p Suppose this program is contained in a file named :file:`hello.vhdl`. First, you have to compile the file; this is called `analysis` of a design file in `VHDL` terms. Run :samp:`ghdl -a hello.vhdl` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which describes the library :samp:`work`. -.. TIP:: If a `GCC`/`LLVM` variant of `GHDL` is used, this command generates a file :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created on Windows. +.. TIP:: If a GCC/LLVM variant of `GHDL` is used, this command generates a file :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created on Windows. -Then, you have to build an executable file. Again, run :samp:`ghdl -e hello_world` in the `shell`. Option :option:`-e` means :dfn:`elaborate`, which is used to `'build'` a design, with the :samp:`hello_world` entity at the top of the hierarchy. +Then, run :samp:`ghdl -e hello_world` in the `shell`. Option :option:`-e` means :dfn:`elaborate`, which is used to `'build'` a design, with the :samp:`hello_world` entity at the top of the hierarchy. Last, launch the simulation running :samp:`ghdl -r hello_world` in the `shell`. The result of the simulation will be shown on the screen:: Hello world! -.. TIP:: If a `GCC`/`LLVM` variant of `GHDL` is used, an executable program called :file:`hello_world` is generated at this step. which can be run - - -.. code-block:: shell - - $ ghdl -r hello_world - -or directly: - -.. code-block:: shell - - $ ./hello_world - -On Windows or if the GCC backend was not enabled, no file is created. -The simulation is launched using this command: - - - - +.. TIP:: If a GCC/LLVM variant of `GHDL` is used, an executable program called :file:`hello_world` is generated at this step. This can can be run directly: :samp:`./hello_world`. A full adder ============ @@ -92,13 +74,7 @@ You can analyze this design file: $ ghdl -a adder.vhdl -You can try to execute the `adder` design, but this is useless, -since nothing externally visible will happen. In order to -check this full adder, a testbench has to be run. This testbench is -very simple, since the adder is also simple: it checks exhaustively all -inputs. Note that only the behaviour is tested, timing constraints are -not checked. The file :file:`adder_tb.vhdl` contains the testbench for -the adder: +You can try to execute the `adder` design, but this is useless, since nothing externally visible will happen. In order to check this full adder, a testbench has to be run. This testbench is very simple, since the adder is also simple: it checks exhaustively all inputs. Note that only the behaviour is tested, timing constraints are not checked. A file named :file:`adder_tb.vhdl` contains the testbench for the adder: .. code-block:: VHDL @@ -167,26 +143,20 @@ As usual, you should analyze the design: $ ghdl -a adder_tb.vhdl -And build an executable for the testbench: +Then elaborate the testbench: .. code-block:: shell $ ghdl -e adder_tb -You do not need to specify which object files are required: GHDL knows them -and automatically adds them in the executable. Now, it is time to run the -testbench: +You do not need to specify which object files are required: GHDL knows them and automatically adds them. Now, it is time to run the testbench: .. code-block:: shell $ ghdl -r adder_tb adder_tb.vhdl:52:7:(assertion note): end of test - -If your design is rather complex, you'd like to inspect signals. Signals -value can be dumped using the VCD file format. The resulting file can be -read with a wave viewer such as GTKWave. First, you should simulate your -design and dump a waveform file: +If your design is rather complex, you'd like to inspect signals. Signals value can be dumped using multiple formats. The resulting file can be read with a wave viewer such as GTKWave. First, you should simulate your design and dump a waveform file: .. code-block:: shell |