reorganized files

1 files changed, 156 insertions, 0 deletions

diff --git a/Ubuntu/README.md b/Ubuntu/README.md
new file mode 100644
index 0000000..04e3647
--- /dev/null
+++ b/Ubuntu/README.md
@@ -0,0 +1,156 @@
+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