NGHDL Installer (Ubuntu OS)
====


It contains all the documenation for making NGHDL executable (using PyInstaller) and NGHDL Installation Script on Ubuntu 14.04 and above.
Separate installers are required to resolve dependencies only for GHDL and are mentioned below. 


## NGDHL EXECUTABLE:

1. Download `virtualenv` package and create virtual environment as:

	    $ pip install virtualenv
	    $ virtualenv -p /usr/bin/python3 nghdl

			OR
		
	    $ sudo apt install -y python3-venv
	    $ python3 -m venv nghdl

2. Activate the virtual environment as:
	
		$ source nghdl/bin/activate

3. Install all Python dependencies for NGHDL within the virtual environment as:

		$ pip install wheel
		$ pip install pyinstaller
		$ pip install --upgrade 'setuptools<45.0.0'
		$ sudo apt install build-essential python3-dev libqt4-dev qt4-dev-tools
		$ mkdir nghdl/build
		$ cd nghdl/build/
		$ wget http://sourceforge.net/projects/pyqt/files/PyQt4/PyQt-4.12.3/PyQt4_gpl_x11-4.12.3.tar.gz
		$ wget https://www.riverbankcomputing.com/static/Downloads/sip/4.19.21/sip-4.19.21.tar.gz
		$ tar xzvf sip-4.19.21.tar.gz
		$ tar xvzf PyQt4_gpl_x11-4.12.3.tar.gz
		$ cd sip-4.19.21/
		$ python configure.py --sip-module PyQt4.sip
		$ make
		$ make install
		$ cd ../PyQt4_gpl_x11-4.12.3/
		$ python configure.py
		$ make
		$ make install

4. Now uninstall PyQt4, sip, matplotlib, numpy, dateutil and cycler globally (if any).

5. Test whether only NGHDL dependencies are available or not:

		$ pip freeze

> Note : Following dependencies should be available -
>	- PyQt4
> 	- sip

6. Create spec file as:

		$ pyi-makespec --onefile -n nghdl <path_to_nghdl>/src/ngspice_ghdl.py

7. Add `PyQt4.sip` as hiddenimports in the generated spec file.

8. Create onefile executable using pyinstaller as:
		
		$ pyinstaller -F --clean nghdl.spec

9. Verify whether all NGHDL `src` files (`*.py`) have been included in `Analysis-00.toc` file under the build folder generated by PyInstaller.


## Fully-Static Bundled Version of NGHDL:

1. To create a [fully-static bundled version](https://github.com/pyinstaller/pyinstaller/wiki/FAQ#GNULinux) of NGHDL (through PyInstaller), use a tool like [StaticX](https://github.com/JonathonReinhart/staticx/).

2. To create fully-static NGHDL :

	- Activate the virtual environment as:
	
		$ source nghdl/bin/activate

	- Install StaticX as:

		$ pip install staticx
		$ pip install patchelf-wrapper

	- Create static NGHDL as:

		$ staticx /path/to/executable/nghdl /path/to/output/executable/nghdl

3. To verify if all dynamic libraries are removed :
	
	- Type following command in a terminal :

		$ ldd path/to/output/executable/nghdl

	- Output of above command should be similar to `	not a dynamic executable`


## Differences in Ubuntu 14.04, Ubuntu 16.04 and above installers (w.r.t GHDL):

1. Dependency on gnat :

	- Ubuntu 14.04 : gnat (v4.6)

	- Ubuntu 16.04 : gnat-5 (v5.4)

	- Ubuntu 18.04 : gnat-5 (v5.5)

2. Dependency on llvm :

	- Available version on Ubuntu 14.04 : llvm (v3.4)

	- Available version on Ubuntu 16.04 : llvm (v3.5)

	- Available version on Ubuntu 18.04 : llvm (v6.0)

	- Requires llvm version between 3.5 and 3.9 for compilation of GHDL with llvm config

	- Ubuntu 18.04 requires installation of LLVM on target machine as it is used during runtime of GHDL as shared library.

3. Dependency on gcc : 

	- Ubuntu 14.04 and 16.04 : gcc (v5.4.0) is available without pie (i.e. position-independent executable)

	- Ubuntu 18.04 : gcc (v7.4.0) is available with pie enabled as default option.

	- Refer [this](https://github.com/ghdl/ghdl/issues/213) Github issue for dependency on gcc for Ubuntu 18.04 and above.


## GHDL Compilation:

1. Compilation of GHDL is OS specific and GHDL executables should be generated on that system for distribution on same OS configuration.

2. For distribution of GHDL (v0.36) on Ubuntu 14.04, directly use the llvm executable provided on GHDL's Github page.

3. For distribution of GHDL (v0.36) on Ubuntu 16.04 and above, follow the steps:

	a. Download source code (v0.36) from GHDL's Github page.

	b. Extract the tar file, open a terminal and change directory one-level inside.

	c. First install gnat(v5) dependency as:
	
		$ sudo apt install gnat-5

	d. Install llvm(v3.9) dependency as:

		$ sudo apt install llvm-3.9

	e. Install clang dependency:

		$ sudo apt install clang

	f. To compile GHDL, type following commands:

		$ sudo ./configure --with-llvm-config=/usr/bin/llvm-config-3.9
		$ sudo make
		$ sudo make install