UMHDL Files

========================================================================
                               **  UMHDL ** 
Multi-platform Integrated Development Environment (IDE) for learning HDL
========================================================================

0. Contents
1. Description
2. Credits
3. Installation instructions

-- * --

+----------------+
| 0. Contents    |
+----------------+

Folder/File           | Description
----------------------|---------------------------------------------------------------
src                   | Source code of the application and necessary libraries
info                  | Brochures of UMHDL (and Simulin), English and Spanish
bin                   | Native executables (Windows, Linux and Mac OS X)
umhdl-install-es.pdf  | Detailed install guide (in Spanish)
README.txt            | This file (in English)
LEEME.txt             | This file (in Spanish)


+----------------+
| 1. Description |
+----------------+

UMHDL is an educational Integrated Development Environment (IDE) intended for learning digital designing with programmable logic devices using Hardware Description Languages (HDL) through simulation. It is an open-source application created at the Miguel Hern‡ndez University (UMH). The aim for the UMHDL development was to have a graphical application that allows learning the VHDL language without licensing restrictions (using some existing open-source tools) and requiring few resources. So, the interface developed acts as a front-end that allows writing code (with syntax highlighting), invokes an external VHDL compiler and simulator (such as GHDL), and displays the result of the simulation graphically as waveforms (invoking to GTKWave).

The user can choose the IDE language (Spanish, English, etc.). UMHDL has been developed in Java language, so it is multi-platform; it has been tested in Windows (32/64-bit), Linux (32/64-bit) and Mac OS X.

There exists another free application named Simulin, although not open-source, which is a digital circuit simulator for educational purposes.


+------------+
| 2. Credits |
+------------+

This project have been developed at the Miguel Hernandez University (UMH), Spain.
For details, see the section Wiki > About:
https://sourceforge.net/p/umhdl/wiki/About/


+-----------------+
| 3. Installation |
+-----------------+

The installation instructions for Windows, Linux, and MacOS X are in the project's Wiki:
https://sourceforge.net/p/umhdl/wiki/Home/


+------------------------------+
| 3.a) Installation :: Windows |
+------------------------------+

1. UMHDL
--------

- To install UMHDL, download and execute the installer (e.g. umhdl-setup-1.60.exe)
  and follow the instructions.
  The windows installer includes al the necessary pieces of software: GHDL and GTKwave,
  which will be installed in the subdirectory:
     C:\Program Files\Umhdl\Ghdl_gtkwave\bin
  That path should be included in the PATH environment variable, or be set in the
  configuration options (menu Options > Configure).

  NOTE: with Windows 7 it could be necessary to install GHDL manually.

- To uninstall, execute Start > Programs > UMHDL > Uninstall.
  In case of installing a new version it is not necessary to uninstall it manually,
  as it will be uninstalled automatically. 

2. Possible problems in Windows
-------------------------------

2.a) Problem: the GHDL compiler cannot be found.

     Solution: to solve it there are two possibilities:
     a) Modify the PATH environment variable; the path can contains blank spaces.
     b) Set the application configurations of UMHDL (menu Options > Configure).
        It is necessary to set the 'bin' subdirectory for both GHDL and GTKwave.
        In this case, the path cannot contains blank spaces, and it should be 
        specified in 8.3 format. For example, instead of:
           C:\Program Files\Umhdl\Ghdl_gtkwave\bin
        it have to be specified with the short name:
           C:\Progra~1\Umhdl\Ghdl_gtkwave\bin
       
       NOTE: from Windows 8 there exists two different paths for 32 and 64-bits
          applications:
          - 'C:\Program Files'         ->  C:\Progra~1  (64-bit)
          - 'C:\Program Files (x86)'   ->  C:\Progra~2  (32-bit)
          As both UMHDL, GHDL and Gtkwave are 32-bit programs, they will be installed
          in the last one, so the path will be:
             C:\Progra~2\Umhdl\Ghdk_gtkwave\bin
             C:\Progra~2\Ghdl\bin
             ...

2.b) Problem: when compiling a VHDL module with GHDL the following message is got:

     err: module:23:10: package "numeric_std" is obsoleted by package "std_logic_1164"
     err: module:23:5: package "numeric_std" is obsolete
     Finished with 2 errors! (1883 ms.)

     Solution:
     (1) In Windows, the application includes a botton in the configuration options
         that rebuild all the GHDL libraries.
     (2) Another option es to reinstall GHDL manually, for example, with the installer
         ghdl-installer-0.29.1.exe. Then, the 'bin' directory should be included in the
         PATH environment variable, or in the application options (as explained before).


+----------------------------+
| 3.b) Installation :: Linux |
+----------------------------+

In Linux it is necessary to install UMHDL and the external tools GHDL and GTKwave.

1. UMHDL
--------

- To install UMHDL:
  1. Download the installer (e.g. umhdl-setup-1.60.bin) to a path without blank spaces.
  2. Check that the installer can be execute:
     chmod +x umhdl-setup-1.60.bin
  3. Execute it and follow the instructions; it would be necessary to install it
     as root or using "sudo", depending of the choosen path:
     $ sudo ./umhdl-setup-1.60.bin
  4. Write the installation path (/usr/local/umhdl by default) and press [Intro];
     the path cannot contains blank spaces.
  5. Optionally, you can create a shortcut in the desktop.
     For example, in Ubuntu or Linux Mint:
     5.a) Create a launcher (right-click on the desktop > Create laucher)
     5.b) Right-click > Properties > Drag an icon (*.gif, *.ico) to top-left of
          the "Basic" tap.

  NOTE: for Linux 64-bit it is possible to obtain the following error:
     "Exception in thread "main" java.lang.UnsatisfiedLinkError:
      exception occurred in JNI_OnLoad"
     In this case it is necessary to install the package ia32-libs
     (ia32-libs-multiarch:i386) and other depending packages.
     $ sudo apt-get install ia32-libs

- To uninstall, execute the Uninstall program:
     $ cd /usr/local/umhdl
     $ sudo ./Uninstall

2. GHDL compiler
----------------

There are two possibilities to install GHDL:

  a) By using some package manager:
     $ sudo apt-get install ghdl
     It will be installed in /usr/local/bin, which should be already included in PATH.

  b) By downloading the binaries and unpacking them manually:
     $ wget http://ghdl.free.fr/site/uploads/Main/ghdl-i686-linux-latest.tar
     $ sudo tar xvf ghdl-i686-linux-latest.tar
       (this generates the file ghdl-0.29-i686-pc-linux.tar.bz2)
     $ cd ghdl-0.29-i686-pc-linux
     $ sudo tar -C / -jxvf ghdl-0.29-i686-pc-linux.tar.bz2
       (this copy the files to /usr/local/bin and /usr/local/lib).

Anyway, the destination directory should be already included in PATH.

Links:
   http://gna.org/projects/ghdl/
   http://ghdl.free.fr/
   http://sourceforge.net/projects/ghdl-updates/

3. GTKwave
----------

As with GHDL, there are two possibilities to install GTKwave:

  a) By using some package manager (RECOMMENDED):
     $ sudo apt-get install zlib1g-dev gtkwave
     It will be installed in /usr/bin, which should be already included in PATH.

  b) By downloading the binaries and unpacking them manually:
     $ wget http://gtkwave.sourceforge.net/gtkwave-3.3.58.tar.gz
     $ sudo tar xvfz gtkwave-3.3.58.tar.gz -C /usr/local
       (this generates the path /usr/local/gtkwave-3.3.58)
     $ sudo ./configure
     $ sudo make
     $ sudo make install

Anyway, the destination directory should be already included in PATH.
We can check the directory with the 'which' or 'whereis' commands:
     $ which ghdl
     /usr/local/bin/ghdl
     $ whereis gtkwave
     gtkwave: /usr/bin/gtkwave /usr/bin/X11/gtkwave /usr/share/man/man1/gtkwave.1.gz

Links:
   http://gtkwave.sourceforge.net/

4. Possible problems in Linux 64-bits
-------------------------------------

4.a) Problem: in Linux 64-bits the following errors are got when compiling:
        /home/myworkspace/e~and_gate.s: Assembler messages:
        /home/myworkspace/e~and_gate.s:40: Error: invalid instruction suffix for `push'
        /home/myworkspace/e~and_gate.s:42: Error: invalid instruction suffix for `pop'

     Solution: the problem is that GHDL is a 32-bit program. The solution is to
        append some extra options when invoking to GHDL.
           ghdl -a -Wa,--32 ...
           ghdl -e -Wa,--32 -Wl,-m32 ...
        UMHDL already checks the Operating System when executing and take it into account,
        so that errors should not ocurr.

4.b) Problem: in Linux 64-bits the following errors are got when compiling:
        /usr/bin/ld: skipping incompatible /usr/lib/gcc/x86_64-linux-gnu/4.6/libgcc.a
        when searching for -lgcc

     Solution: it is necessary to install the gcc-4.5-multilib package and dependencies.
        $ sudo apt-get install gcc-4.5-multilib

4.b) Problem: in Linux 64-bits the following errors are got when compiling:
        /usr/bin/ld: cannot find -lz
     Solution: it is necessary to install the zlib1g-dev (zlib1g-dbg),
        lib32z1-dev (+lib32z1) packages and dependencies.
        $ sudo apt-get install lib32z1-dev
 

+------------------------------+
| 3.c) Installation :: MacOS X |
+------------------------------+

In MacOS X it is necessary to install UMHDL and the external tools GHDL and GTKwave.
Furthermore, GTKwave requieres a X11 server.

1. UMHDL
--------
- To install UMHDL, uncompress the file 'umhdl-mac-app-1.60.zip' in any location, 
  for example, in the Applications folder.
  It contains a single application file (.app) that can be added to the Dock or
  to the desktop (creating a Alias previously).

2. X11 server
-------------
- Recent Mac OS X versions (Mavericks 10.9, Yosemite 10.10, ...) does not includes
  any X11 server as older ones. It is necessary to install XQuartz:Á, which can be
  downloaded from:
  http://xquartz.macosforge.org
- Once installed it is necessary to reboot the computer.

3. GHDL
-------
- For OS X Mavericks 10.9 or later download the file ghdl-0.31-mcode-darwin13.mpkg.zip
  from:
     http://sourceforge.net/projects/ghdl-updates/files/Builds/ghdl-0.31/OSX/
  For earlier versions download the file ghdl_mcode_r142.dmg.
- The program will be installed to: /usr/local/bin

4. GTKWave
----------
-  Using MacPorts o Fink (RECOMMENDED):
   0. Install MacPorts (if needed), which requieres Xcode:
      https://www.macports.org/install.php
   1. Update MacPorts (if needed):
      $ sudo port selfupdate --nosync
      $ sudo port selfupdate
   2. Update installed programs with MacPorts:
      $ sudo port outdated
      $ sudo port selfupdate
      $ sudo port upgrade outdated
   3. Install the gtkwave port:
      $ port search gtkwave
      $ port install gtkwave

- The program will be installed to: /opt/local/bin

- It is also possible to download an installer from:
  http://eng-osx.sourceforge.net/GTKwave.html

- Finally, it is possible to use WINE for installing from a Windows installer:
  http://dwellangle.wordpress.com/2010/04/30/installing-ghdl-on-a-mac/

5. Environment variables
-----------------------
- The PATH environment variable should include the path for the 'ghdl' and 'gtkwave':
  ghdl:    /usr/local/bin
  gtkwave: /opt/local/bin

  In order to set these paths it is necessary to modify the '/etc/launchd.conf' file,
  because if they are included in the '.bash_profile' they will not be taken into
  account when invoking external tools from a graphical application like UMHDL:
   $ sudo vi /etc/launchd.conf
   setenv JAVA_HOME /Library/Java/Home
   setenv PATH /usr/local/bin

- Alternatively, it is possible to set that paths in the application configuration.

- We can check the directories with the 'which' or 'whereis' commands:
     $ which ghdl
     /usr/local/bin/ghdl
     $ which gtkwave
     /opt/local/bin/gtkwave