Merge remote-tracking branch 'origin/master'

.appveyor.yml

@@ -38,8 +38,8 @@ install:
   - "git submodule update --init --recursive"
   - "%PYTHON%\\python.exe -m pip install tox"
   - "curl -fsSL -o ghdl.zip https://github.com/tgingold/ghdl/releases/download/v0.35/ghdl-0.35-mingw32-mcode.zip"
-  - "7z x ghdl.zip -oghdl -y"
-  - "set PATH=%PATH%;ghdl/GHDL/v0.35-mingw32-mcode/bin"
+  - "7z x ghdl.zip -o../ghdl -y"
+  - "set PATH=%PATH%;../ghdl/GHDL/v0.35-mingw32-mcode/bin"
 
 build: off
 

LICENSE.txt

@@ -4,7 +4,7 @@ VUnit
 VUnit except for OSVVM (see below) is released under the terms of
 Mozilla Public License, v. 2.0.
 
-Copyright (c) 2014-2017, Lars Asplund [email protected]
+Copyright (c) 2014-2018, Lars Asplund [email protected]
 
 OSVVM
 -----

README.rst

@@ -10,6 +10,12 @@ often" approach through automation.
 
 **Read more on our** `Website <https://vunit.github.io>`__
 
+Contributing
+============
+Contributing in the form of code, feedback, ideas or bug reports are
+welcome. Read our `contribution guide
+<https://vunit.github.io/contributing.html>`__ to get started.
+
 License
 =======
 VUnit

docs/build.py

@@ -6,7 +6,7 @@
 def main():
     create_release_notes()
     check_call([sys.executable, "-m", "sphinx",
-                "-T", "-E", "-a", "-n", "-b", "html",
+                "-T", "-E", "-W", "-a", "-n", "-b", "html",
                 dirname(__file__), sys.argv[1]])
 
 if __name__ == "__main__":

docs/cli.rst

@@ -149,25 +149,6 @@ and then a test name.
    When using the ``run_all_in_same_sim`` pragma all tests within the
    test bench share the same output folder named after the test bench.
 
-.. _continuous_integration:
-
-Continuous Integration Environment
-----------------------------------
-VUnit is easily utilized with continuous integration environments such as
-`Jenkins`_. Once a project ``run.py`` has been setup, tests can be run in a
-headless environment with standardized xUnit style output to a file.
-
-.. code-block:: console
-   :caption: Execute VUnit tests on CI server with XML output
-
-    python run.py --xunit-xml test_output.xml
-
-After tests have finished running, the ``test_output.xml`` file can be parsed
-using standard xUnit test parsers such as `Jenkins xUnit Plugin`_.
-
-.. _Jenkins: http://jenkins-ci.org/
-.. _Jenkins xUnit Plugin: http://wiki.jenkins-ci.org/display/JENKINS/xUnit+Plugin
-
 .. _simulator_selection:
 
 Simulator Selection
@@ -196,7 +177,6 @@ Simulator Specific Environment Variables
   environment variable selects another *modelsim.ini* file as the
   starting point allowing the user to customize it.
 
-
 .. _test_output_envs:
 
 Test Output Path Length Environment Variables
@@ -213,3 +193,83 @@ Test Output Path Length Environment Variables
 - ``VUNIT_TEST_OUTPUT_PATH_MARGIN`` Can be used to change the test
   output path margin on Windows. By default the test output path is
   shortened to allow a 100 character margin.
+
+.. _continuous_integration:
+
+Continuous Integration (CI) Environment
+---------------------------------------
+
+Because VUnit features the functionality needed to realize continuous and automated testing of HDL code, it is a very valuable resource in continuous integration environments. Once a project ``run.py`` has been setup, tests can be run in a headless environment with standardized `Xunit <https://en.wikipedia.org/wiki/List_of_unit_testing_frameworks>`_ style output to a file; which allows dynamic interpretation of results avoiding custom (and error-prone) parsing of the logs.
+
+.. code-block:: console
+   :caption: Execute VUnit tests on CI server with XML output
+
+    python run.py --xunit-xml test_output.xml
+
+After tests have finished running, the ``test_output.xml`` file can be parsed
+using standard xUnit test parsers such as `Jenkins xUnit Plugin <http://wiki.jenkins-ci.org/display/JENKINS/xUnit+Plugin>`_.
+
+Furthermore, VUnit can be easily executed in many different platforms (either operating systems or architectures), because it is written in Python, which is an interpreted language. However, besides the sources and VUnit, a `HDL compiler/simulator <https://en.wikipedia.org/wiki/List_of_HDL_simulators>`_ is required in order to run the tests. Due to performance, all the HDL simulators are written in compiled languages, which makes the releases platform specific. I.e., each simulator needs to be specifically compiled for a given architecture and operating system. This might represent a burden for the adoption of continuous integration in hardware development teams, as it falls into the category of dev ops.
+
+Nevertheless, thanks to the striking research about portable development environment solutions in the last decade, there are a bunch of alternatives to ease the path. The 'classic' approach is to use virtual machines with tools
+such as `VirtualBox <https://www.virtualbox.org/>`_, `QEMU <https://www.qemu.org/>`_ or `VMware <https://www.vmware.com>`_. This is still an option, but for most uses cases sharing complete system images is overkill. Here, `containerization or operating-system-level virtualization <https://en.wikipedia.org/wiki/Operating-system-level_virtualization>`_ comes into the game. Without going into technical details, containers are a kind of lightweight virtual machines, and the most known product that uses such a technology is `Docker <https://docker.com>`_. Indeed, products such as `Vagrant <https://www.vagrantup.com/>`_ are meant to simplify the usage of virtual machines and/or containers by providing a common (black) box approach. In the end, there are enough open/non-open and free/non-free solutions for each user/company to choose the one that best fits their needs. From the hardware designer point-of-view, we 'just' need a box (no matter the exact underlying technology) that includes VUnit and a simulator.
+
+Fortunately, contributors of project `GHDL <https://github.com/ghdl/ghdl>`_ provide ready-to-use docker images at `hub.docker.com/u/ghdl/dashboard <https://hub.docker.com/u/ghdl/dashboard/>`_. Some of these include not only GHDL but also VUnit:
+
+* ``ghdl/ext:vunit``: Debian Stretch image with GHDL built from the latest commit of the master branch, and the latest release of VUnit installed through ``pip``.
+* ``ghdl/ext:vunit-master``: Debian Stretch with GHDL built from the latest commit of the master branch, and the latest commit of VUnit from the master branch.
+
+As a result, the burden for the adoption of continuous integration for VUnit users is reduced to using docker; which is available in GNU/Linux, FreeBSD, Windows and macOS, and is supported in most cloud services (`Travis CI <https://travis-ci.org/>`_, `AWS <https://aws.amazon.com/docker/>`_, `Codefresh <https://codefresh.io/>`_, etc.) or CI frameworks (`Jenkins <https://jenkins.io/>`_, `Drone <https://drone.io/>`_, `GitLab Runner <https://docs.gitlab.com/runner/>`_, etc.).
+
+For example, script :vunit_file:`examples/vhdl/docker_runall.sh <examples/vhdl/docker_runall.sh>` shows how to run all the VHDL examples in any x86 platform:
+
+.. code-block:: bash
+
+   docker run --rm -t \
+     -v /$(pwd)://work \
+     -w //work \
+     ghdl/ext:vunit-master sh -c ' \
+       VUNIT_SIMULATOR=ghdl; \
+       for f in $(find ./ -name 'run.py'); do python3 $f; done \
+     '
+
+where:
+
+* ``run``: create and start a container.
+* ``--rm``: automatically remove the container when it exits.
+* ``-t``: allocate a pseudo-TTY, to get the stdout of the container forwarded.
+* ``-v``: bind mount a volume, to share a folder between the host and the container. In this example the current path in the host is used (``$(pwd)``), and it is bind to `/work` inside the container. Note that both paths must be absolute.
+* ``-w``: sets the working directory inside the container, i.e. where the commands we provide as arguments are executed.
+* ``ghdl/ext:vunit-master``: the image we want to create a container from.
+* ``sh -c``: the command that is executed as soon as the container is created.
+
+Note that:
+
+* The arguments to ``sh -c`` are the same commands that you would execute locally, shall all the dependencies be installed in the host:
+
+   .. code-block:: bash
+
+      VUNIT_SIMULATOR=ghdl
+      for f in $(find ./ -name 'run.py'); do python3 $f; done
+
+* The leading slashes in ``/$(pwd)`` and ``//work`` are only required for the paths to be properly handled in MINGW shells, and are ignored in other shells. See `docker/for-win#1509 <https://github.com/docker/for-win/issues/1509>`_.
+
+Final comments:
+
+* All the (automated) flow to generate ``ghdl`` docker images is open source and public, in order to let any user learn and extend it. You can easily replicate it to build you own images with other development dependencies you use.
+   * There are ready-to-use images available with additional tools on top of GHDL and VUnit. For example, ``ghdl/ext:vunit-gtkwave`` includes `GTKWave <http://gtkwave.sourceforge.net/>`_.
+* Although the licenses of most commercial simulators do not allow to share ready-to-use docker images, it is straightforward to mimic the process.
+   * If the installation of a tool needs to be executed with a GUI, a slightly different approach is required. See `Propietary applications inside a docker container <https://github.com/1138-4EB/hwd-ide/wiki/Continuous-Integration-%28CI%29#propietary-applications-inside-a-docker-container>`_
+* Both GHDL and VUnit are free software. Docker is almost fully open source, but this depends on the host platform. See `Is Docker still free and open source? <https://opensource.stackexchange.com/questions/5436/is-docker-still-free-and-open-source>`_.
+
+Further info:
+
+* `What is a container <https://www.docker.com/what-container>`_
+* `What is docker <https://www.docker.com/what-docker>`_
+* `docs.docker.com/engine/reference <https://docs.docker.com/engine/reference>`_
+   * `run <https://docs.docker.com/engine/reference/run/>`_
+   * `commandline/run <https://docs.docker.com/engine/reference/commandline/run/>`_
+* Docker offers two variants Community Edition (CE) and Enterprise Edition (EE). Any of them can be used. Moreover, part of Docker is being split to `Moby project <https://mobyproject.org/>`_.
+   * `Announcing Docker Enterprise Edition <https://blog.docker.com/2017/03/docker-enterprise-edition/>`_
+   * `Introducing Moby Project: a new open-source project to advance the software containerization movement <https://blog.docker.com/2017/04/introducing-the-moby-project/>`_
+* If you don't want or cannot install docker, you can still use it online. `Play with Docker <https://play-with-docker.com>`_ (PWD) *"is a Docker playground which allows users to run Docker commands in a matter of seconds. It gives the experience of having a free Alpine Linux Virtual Machine in browser, where you can build and run Docker containers and even create clusters"*.

docs/conf.py

@@ -357,5 +357,6 @@
 htmlhelp_basename = 'vunitdoc'
 
 extlinks = {'vunit_example' : ('https://github.com/VUnit/vunit/tree/master/examples/%s/', ''),
+            'vunit_file' : ('https://github.com/VUnit/vunit/tree/master/%s/', ''),
             'vunit_commit' : ('https://github.com/vunit/vunit/tree/%s/', '@'),
             'vunit_issue' : ('https://github.com/VUnit/vunit/issues/%s/', '#')}

docs/contributing.rst

@@ -4,8 +4,34 @@ Contributing in the form of code, feedback, ideas or bug reports are
 welcome. Code contributions are expected to pass all tests and style
 checks. If there are any problems let us know.
 
+Before doing any major changes we recommend creating an issue or
+chatting with us on gitter to discuss first. In this way you do not
+get started on the wrong track and wasting time.
+
+Being a testing framework we value automated testing and all
+contributions in both the Python and VHDL/SystemVerilog domain are
+expected to add new tests along with the new functionality.
+
+Copyright
+---------
+Any contribution must give the copyright to Lars Asplund.
+This is necessary to manage the project freely.
+Copyright is given by adding the copyright notice to the beginning of each file.
+
+.. code-block:: python
+
+   # This Source Code Form is subject to the terms of the Mozilla Public
+   # License, v. 2.0. If a copy of the MPL was not distributed with this file,
+   # You can obtain one at http://mozilla.org/MPL/2.0/.
+   #
+   # Copyright (c) 2014-2018, Lars Asplund [email protected]
+
+
+Python related
+--------------
+
 Running the tests
------------------
+~~~~~~~~~~~~~~~~~
 
 The test suite is divided into three parts:
 
@@ -22,44 +48,17 @@ The test suite is divided into three parts:
 The test suites must pass with both Python 2.7 and Python 3.x as well
 as with all supported simulators.
 
-Testing with Tox
-~~~~~~~~~~~~~~~~
-VUnit uses the Python `tox <http://tox.readthedocs.org/>`__ tool. Tox
-makes it easier to automatically test VUnit in various
-configurations. Tox automates creation of virtual environments and
-installation of dependencies needed for testing. In fact, all of the
-tests can be run in a single command:
-
-.. code-block:: console
-
-    vunit/ > tox
+For running the test locally we recommend using `pytest <https://pypi.python.org/pypi/pytest>`__.
 
-If tox is not available in your Python environment, it can be installed from
-PyPI with pip:
+Example
+'''''''
+.. code-block:: shell
+   :caption: Example of running all unit tests
 
-.. code-block:: console
-
-    vunit/ > pip install tox
-
-For most developers, running the full testsuite will likely lead to failed test
-cases because not all Python interpreters or HDL simulators are installed in
-their environment. More focused testing is possible by specifying which tox
-"environments" should be tested. For example, assume a developer uses Python 2.7
-and Modelsim and would like to test changes using tools available in his
-environment:
-
-.. code-block:: console
-
-    vunit/ > tox -e py27-unit,py27-acceptance-modelsim
-
-A full list of test environments can be seen by issuing the following command:
-
-.. code-block:: console
-
-    vunit/ > tox -l
+   pytest vunit/test/unit/
 
 Dependencies
-------------
+~~~~~~~~~~~~
 
 Other than the dependencies required to use VUnit as a user the
 following are also required for developers to run the test suite manually:
@@ -74,7 +73,7 @@ following are also required for developers to run the test suite manually:
    Code analysis.
 
 Code coverage
--------------
+~~~~~~~~~~~~~
 
 Code coverage can be measured using the
 `coverage <https://pypi.python.org/pypi/coverage>`__ tool. The following
@@ -91,9 +90,101 @@ this paragraph the total coverage was 92%. Missing coverage can be
 analyzed by opening the generated *htmlcov/index.html* produced by the
 above commands.
 
+VHDL related
+------------
+
+Running the tests
+~~~~~~~~~~~~~~~~~
+Each part of the VUnit VHDL code base has tests with a corresponding ``run.py`` file.
+For example :vunit_file:`vunit/vhdl/verification_components/run.py`.
+
+Example
+'''''''
+.. code-block:: shell
+   :caption: Example of running all verification component tests
+
+   python vunit/vhdl/verification_components/run.py
+
+
+Coding Style
+~~~~~~~~~~~~
+Contributions of VHDL code should blend in with the VUnit code style.
+
+- Use lower case and ``snake_case`` for all identifiers and keywords.
+- Do not use prefixes or suffixes like ``_c`` or ``_g`` for constants.
+- Use ``_t`` suffix for type like ``<typename>_t``.
+- Never use the fact that VHDL is case-insensitive; Do not use ``Foo``
+  and ``foo`` to refer to the same identifier.
+- Name array types ``<base_type_name>_vec_t``
+- Name packages with suffix ``_pkg``
+- Name files the same as the package or entity they contain such as ``<entity_name>.vhd``
+- Never put more than one entity/package in the same file.
+- Keep the architecture in the same file as the entity unless there
+  are several architectures. When there are several architectures put
+  them all in separate files named
+  ``<entity_name>_<architecture_name>.vhd``.
+- Put comments documenting functions and procedures above the
+  declaration in the package header rather than the definition in the
+  package body.
+
+Regarding formatting use look at other VHDL files and follow that
+style. For example :vunit_file:`examples/vhdl/uart/src/uart_tx.vhd`
+
+
+Continous Integration
+---------------------
+VUnit runs all test and lint checks on both Windows using AppVeyor and
+Linux using Travis CI with several versions of Python. GHDL is used to
+run the VHDL tests of all our libraries and examples.
+
+All tests will be automatically run on any pull request and they are
+expected to pass for us to approve the merge.
+
+Any commit on master that has a successful CI run will automatically
+update the `VUnit website <https://vunit.github.io>`__
+
+Testing with Tox
+~~~~~~~~~~~~~~~~
+VUnit uses the Python `tox <http://tox.readthedocs.org/>`__ tool in
+the CI flow. Typically developers do not need to run this on their
+local machine.
+
+Tox makes it easier to automatically test VUnit in various
+configurations. Tox automates creation of virtual environments and
+installation of dependencies needed for testing. In fact, all of the
+tests can be run in a single command:
+
+.. code-block:: console
+
+    vunit/ > tox
+
+If tox is not available in your Python environment, it can be installed from
+PyPI with pip:
+
+.. code-block:: console
+
+    vunit/ > pip install tox
+
+For most developers, running the full testsuite will likely lead to failed test
+cases because not all Python interpreters or HDL simulators are installed in
+their environment. More focused testing is possible by specifying which tox
+"environments" should be tested. For example, assume a developer uses Python 2.7
+and Modelsim and would like to test changes using tools available in his
+environment:
+
+.. code-block:: console
+
+    vunit/ > tox -e py27-unit,py27-acceptance-modelsim
+
+A full list of test environments can be seen by issuing the following command:
+
+.. code-block:: console
+
+    vunit/ > tox -l
+
 
 Making releases
----------------
+~~~~~~~~~~~~~~~
 
 Releases are automatically made by Travic CI on any ``master`` commit
 that has a new version set in ``vunit/about.py`` together with a