From f9f56ff487b16c312143bd4e81949f4f5db1e9e8 Mon Sep 17 00:00:00 2001 From: rahulp13 Date: Thu, 6 Aug 2020 01:55:36 +0530 Subject: updated doc files --- NgspiceChanges.md | 65 ------------------- Ngspice_Version_Change.md | 68 ++++++++++++++++++++ README.md | 16 ++--- Ubuntu/README.md | 159 ++++------------------------------------------ Windows/README.md | 106 +++++++++++++++++++++++++++++++ Windows/readme.md | 106 ------------------------------- 6 files changed, 196 insertions(+), 324 deletions(-) delete mode 100644 NgspiceChanges.md create mode 100644 Ngspice_Version_Change.md create mode 100644 Windows/README.md delete mode 100644 Windows/readme.md diff --git a/NgspiceChanges.md b/NgspiceChanges.md deleted file mode 100644 index 5bf5afb..0000000 --- a/NgspiceChanges.md +++ /dev/null @@ -1,65 +0,0 @@ -# Changes for Ngspice version upgrade - -1. Manually add the GHDL server close patch (header files and “close_server” function at the appropriate location) in the outitf.c which comes with the new Ngspice version ->Refer to previous version of NGHDL outitf.c file for reference - -call this function [ close_server(); ] in outitf.c before the line -```c -fprintf(stdout, "\nNo. of Data Rows : %d\n", run->pointCount); -``` -Which occurs in two functions in outitf.c (may not be same in the future), in functions named -```c - static void fileEnd(runDesc *run) -``` -and -```c - static void plotEnd(runDesc *run) -``` -**--- Do not replace old outitf.c with the outitf.c in the new ngspice version.\ ---- Make sure to maintain OS independence of the code, that is same code file for Windows and Linux.** - -2. Similarly manually add patch for identification of Mingw and linking of libws2_32.a to makedefs.in at */ngspice/src/xspice/icm* **after the line `LIBS = -lm`** (important) -```make -ISMINGW = $(shell uname | grep -c "MINGW64") -ifeq ($(ISMINGW), 1) - LIBS = -lm -lws2_32 -endif - -ISMINGW = $(shell uname | grep -c "MINGW32") -ifeq ($(ISMINGW), 1) - LIBS = -lm -lws2_32 -endif - -ISMINGW = $(shell uname | grep -c "MSYS") -ifeq ($(ISMINGW), 1) - LIBS = -lm -lws2_32 -endif -``` - -3. Add patch for linking libws2_32.a in Windows at Makefile.in at */ngspice/src/* by modifying the line -```make -@WINGUI_TRUE@am__append_19 = -lpsapi -lShlwapi -``` -To -```make -@WINGUI_TRUE@am__append_19 = -lpsapi -lShlwapi -lws2_32 -``` - - -4. Add patch for addition of GHDL codemodel to the spinit.in file at */ngspice/src/* as an addition to the section -```make -* The other codemodels -``` -with the line -```make -@XSPICEINIT@ codemodel @pkglibdir@/ghdl.cm -``` -and in GNUmakefile.in at */ngspice/src/xspice/icm* by replacing the line -```make -CMDIRS = spice2poly digital analog xtradev xtraevt table -``` -with -```make -CMDIRS = spice2poly digital analog xtradev xtraevt table ghdl -``` -5. Create a **`ghdl folder`** with two empty files named `modpath.lst` and `udnpath.lst` at the location */ngspice/src/xspice/icm/* diff --git a/Ngspice_Version_Change.md b/Ngspice_Version_Change.md new file mode 100644 index 0000000..8f3fda1 --- /dev/null +++ b/Ngspice_Version_Change.md @@ -0,0 +1,68 @@ +# Changes for Ngspice version upgrade + +1. Manually add the GHDL server close patch (header files and `close_server` function at the appropriate location) in the `outitf.c` which comes with the new Ngspice version. + +> Note: Compare with previous version of NGHDL `outitf.c` file for applying the patch. + +2. Call this function `close_server()` in `outitf.c` before the line: + +```c + fprintf(stdout, "\nNo. of Data Rows : %d\n", run->pointCount); +``` +occurring in following two functions of `outitf.c` (may not be same in the future): +```c + static void fileEnd(runDesc *run) +``` +and +```c + static void plotEnd(runDesc *run) +``` +> Note: +> 1. Do not replace old `outitf.c` with the `outitf.c` in the new Ngspice version. +> 2. Make sure to maintain OS independence of the code, that is same code file for Windows and Linux. + +3. Similarly, manually add patch for identification of Mingw and linking of `libws2_32.a` to `makedefs.in` at *`/ngspice/src/xspice/icm`* **after the line `LIBS = -lm`** (important) +```make + ISMINGW = $(shell uname | grep -c "MINGW64") + ifeq ($(ISMINGW), 1) + LIBS = -lm -lws2_32 + endif + + ISMINGW = $(shell uname | grep -c "MINGW32") + ifeq ($(ISMINGW), 1) + LIBS = -lm -lws2_32 + endif + + ISMINGW = $(shell uname | grep -c "MSYS") + ifeq ($(ISMINGW), 1) + LIBS = -lm -lws2_32 + endif +``` + +4. Add patch for linking `libws2_32.a` in Windows OS at `Makefile.in` at *`/ngspice/src/`* by modifying the line: +```make + @WINGUI_TRUE@am__append_19 = -lpsapi -lShlwapi +``` +To +```make + @WINGUI_TRUE@am__append_19 = -lpsapi -lShlwapi -lws2_32 +``` + +5. Add GHDL codemodel to the spinit.in file at *`/ngspice/src/`* as an addition to the section: +```make + * The other codemodels +``` +with the line: +```make + @XSPICEINIT@ codemodel @pkglibdir@/ghdl.cm +``` +and in `GNUmakefile.in` at *`/ngspice/src/xspice/icm`* by replacing the line: +```make + CMDIRS = spice2poly digital analog xtradev xtraevt table +``` +with +```make + CMDIRS = spice2poly digital analog xtradev xtraevt table ghdl +``` + +6. Create a **`ghdl` folder** with two empty files named `modpath.lst` and `udnpath.lst` at the location *`/ngspice/src/xspice/icm/`* diff --git a/README.md b/README.md index b86b7c3..b9bbb59 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ -NGHDL Installers +NGHDL Packaging ==== -It contains all the documenation for making installations on various platforms. +It contains all the documentation for packaging NGHDL to be distributed with [eSim](https://github.com/fossee/esim). -## How to package NGHDL with eSim? -1. Add GHDL executable and the corresponding installer for the target OS in the `nghdl` folder. +## Packaging NGHDL with eSim? -> Note : Instructions on how to generate NGHDL executable and distribute it along with GHDL are -> provided under respective target OS directory. +1. NGHDL is currently packaged for Ubuntu OS (Linux) and MS Windows OS. -2. Rename `nghdl` folder as `nghdl-master` and compress it to `.zip` format. +2. Refer the [documentation](Ngspice_Version_Change.md) for the changes to be done when the Ngspice is to be upgraded to a new verion. Note that these changes are common to both Ubuntu and Windows OS. -3. Place this compressed file in `eSim-` folder. +3. Refer the [documentation](Ubuntu/README.md) to package eSim for Ubuntu OS. + +4. Refer the [documentation](Windows/README.md) to package eSim for Windows OS. \ No newline at end of file diff --git a/Ubuntu/README.md b/Ubuntu/README.md index 04e3647..cbc0adb 100644 --- a/Ubuntu/README.md +++ b/Ubuntu/README.md @@ -1,156 +1,25 @@ NGHDL Installer (Ubuntu OS) ==== +It contains the documentation to package NGHDL for 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. +> Note: If planning to freeze the NGHDL source code for a target platform (Ubuntu OS), then refer this [documentation](executable.md). Remember to update the installer script to work with this executable! +## How to package NGHDL for Ubuntu OS? -## NGDHL EXECUTABLE: +1. Take the `master` branch containing the source code. Rename the folder to `nghdl`. -1. Download `virtualenv` package and create virtual environment as: +2. Add GHDL source code `ghdl-.tar.xz` in the `nghdl` folder. - $ pip install virtualenv - $ virtualenv -p /usr/bin/python3 nghdl +3. Add the installer script `install-nghdl.sh` in the `nghdl` folder. - OR - - $ sudo apt install -y python3-venv - $ python3 -m venv nghdl +4. Add the NGHDL executable (if available) in `nghdl/src` folder. Also, remove following files from this folder: + - `.git` folder + - all python files (Applicable only if eSim executable is used) + - GHDLside.md + - Workflow.md + - .gitignore -2. Activate the virtual environment as: - - $ source nghdl/bin/activate +2. Compress it to `.zip` format. -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 /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 +3. Place this compressed file in `eSim-` folder. diff --git a/Windows/README.md b/Windows/README.md new file mode 100644 index 0000000..6f5aae9 --- /dev/null +++ b/Windows/README.md @@ -0,0 +1,106 @@ +NGHDL Installer (Windows OS) +==== + + +It contains all the documenation for making NGHDL executable (using PyInstaller) and packging for eSim Installation Script on Windows 7 and above. + + +## NGHDL Executable: + +1. Download and install "Python-3.5.2", "Git For Windows". Use "Git Bash" for all following shell commands. + + Reference - https://gitforwindows.org/ + +2. Add alias to python.exe in Git shell: + + $ alias python='winpty python.exe' #Need to be done for each new shell created + +3. Download `virtualenv` package as: + + $ pip install virtualenv + +4. Create a virtual environment as: + + $ python -m virtualenv nghdl + +5. Activate the virtual environment as: + + $ source nghdl/Scripts/activate + +6. Install all Python dependencies for NGHDL within the virtual environment as: + + - Install PyInstaller, tornado, SetupTools through pip : + + $ pip install pyinstaller + $ pip install --upgrade 'setuptools<45.0.0' + + - Install PyQt4 through pip (Reference - https://stackoverflow.com/questions/22640640/how-to-install-pyqt4-on-windows-using-pip) : + + $ pip install --upgrade 'sip<5.0.0' + $ pip install + + Download PyQt4 Wheel from - [https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyqt4] + Where cp37 represents the Python version i.e. 3.7.x and so on + + > Note : + - If there are any issues regarding loading of DLL files, refer : https://stackoverflow.com/questions/2738879/cannot-import-pyqt4-qtgui + - If above step works, then goto step 7. + +7. Test whether only NGHDL dependencies are available or not: + + $ pip freeze + +> Note : Following dependencies should be available - +> - PyQt4 +> - sip +> - altgraph +> - future +> - pefile +> - pyinstaller +> - pywin32-ctypes + + +8. Create spec file as: + + $ pyi-makespec --onefile -n nghdl /src/ngspice_ghdl.py + +9. Create onefile executable using pyinstaller as: + + $ pyinstaller -F --clean nghdl.spec + +10. Verify whether all NGHDL `src` files (`*.py`) have been included in `Analysis-00.toc` file under the build folder generated by PyInstaller. +11. nghdl.exe is generated at the dist folder. + + + +## How to package NGHDL with eSim ? + +1. Place the nghdl.exe generated from the above process at the location /nghdl/src/ + +2. Delete all python files (files ending in .py) at /nghdl/src/ + +3. Remove the following files at /nghdl/ + - .gitignore + - GHDLside.md + - Workflow.md + +4. Place **nghdl** folder containing `src folder`, `Example folder` & `LICENSE` under folder named eSim/ + +5. Final directory structure should be: +- eSim/nghdl/Example +- eSim/nghdl/src +- eSim/nghdl/LICENSE + +6. Compress the `eSim` folder from step 4 in 7z format (Make sure that there is folder named `eSim` inside this compressed file) and name it as `nghdl-src.7z`.\ +(7z compression tool can be downloaded from - https://www.7-zip.org/download.html ) + +7. ALong with `nghdl-src.7z` from step 5, place the following 7z files at the installer folder for eSim. +(these can be obtained under *sources/* folder in the repository ) +- ghdl.7z +- MSYS.7z +- ngspice-nghdl.7z +- mingw64.7z + +8. Place the script `installnghdl.nsi` at the eSim installer location. + +9. Follow the rest of the instructions for packging eSim [https://github.com/FOSSEE/eSim/tree/installers/Windows] and compile the NSI script (`esim-setup-script.nsi` file). Now only use the generated installer for distribution. diff --git a/Windows/readme.md b/Windows/readme.md deleted file mode 100644 index 6f5aae9..0000000 --- a/Windows/readme.md +++ /dev/null @@ -1,106 +0,0 @@ -NGHDL Installer (Windows OS) -==== - - -It contains all the documenation for making NGHDL executable (using PyInstaller) and packging for eSim Installation Script on Windows 7 and above. - - -## NGHDL Executable: - -1. Download and install "Python-3.5.2", "Git For Windows". Use "Git Bash" for all following shell commands. - - Reference - https://gitforwindows.org/ - -2. Add alias to python.exe in Git shell: - - $ alias python='winpty python.exe' #Need to be done for each new shell created - -3. Download `virtualenv` package as: - - $ pip install virtualenv - -4. Create a virtual environment as: - - $ python -m virtualenv nghdl - -5. Activate the virtual environment as: - - $ source nghdl/Scripts/activate - -6. Install all Python dependencies for NGHDL within the virtual environment as: - - - Install PyInstaller, tornado, SetupTools through pip : - - $ pip install pyinstaller - $ pip install --upgrade 'setuptools<45.0.0' - - - Install PyQt4 through pip (Reference - https://stackoverflow.com/questions/22640640/how-to-install-pyqt4-on-windows-using-pip) : - - $ pip install --upgrade 'sip<5.0.0' - $ pip install - - Download PyQt4 Wheel from - [https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyqt4] - Where cp37 represents the Python version i.e. 3.7.x and so on - - > Note : - - If there are any issues regarding loading of DLL files, refer : https://stackoverflow.com/questions/2738879/cannot-import-pyqt4-qtgui - - If above step works, then goto step 7. - -7. Test whether only NGHDL dependencies are available or not: - - $ pip freeze - -> Note : Following dependencies should be available - -> - PyQt4 -> - sip -> - altgraph -> - future -> - pefile -> - pyinstaller -> - pywin32-ctypes - - -8. Create spec file as: - - $ pyi-makespec --onefile -n nghdl /src/ngspice_ghdl.py - -9. Create onefile executable using pyinstaller as: - - $ pyinstaller -F --clean nghdl.spec - -10. Verify whether all NGHDL `src` files (`*.py`) have been included in `Analysis-00.toc` file under the build folder generated by PyInstaller. -11. nghdl.exe is generated at the dist folder. - - - -## How to package NGHDL with eSim ? - -1. Place the nghdl.exe generated from the above process at the location /nghdl/src/ - -2. Delete all python files (files ending in .py) at /nghdl/src/ - -3. Remove the following files at /nghdl/ - - .gitignore - - GHDLside.md - - Workflow.md - -4. Place **nghdl** folder containing `src folder`, `Example folder` & `LICENSE` under folder named eSim/ - -5. Final directory structure should be: -- eSim/nghdl/Example -- eSim/nghdl/src -- eSim/nghdl/LICENSE - -6. Compress the `eSim` folder from step 4 in 7z format (Make sure that there is folder named `eSim` inside this compressed file) and name it as `nghdl-src.7z`.\ -(7z compression tool can be downloaded from - https://www.7-zip.org/download.html ) - -7. ALong with `nghdl-src.7z` from step 5, place the following 7z files at the installer folder for eSim. -(these can be obtained under *sources/* folder in the repository ) -- ghdl.7z -- MSYS.7z -- ngspice-nghdl.7z -- mingw64.7z - -8. Place the script `installnghdl.nsi` at the eSim installer location. - -9. Follow the rest of the instructions for packging eSim [https://github.com/FOSSEE/eSim/tree/installers/Windows] and compile the NSI script (`esim-setup-script.nsi` file). Now only use the generated installer for distribution. -- cgit