xschem/XSchemWin/README_WIN

XSCHEM : schematic capture and netlisting EDA tool

Xschem is a schematic capture program, it allows creation of hierarchical representation
of circuits with a top down approach . By focusing on interfaces, hierarchy and instance
properties a complex system can be described in terms of simpler building blocks. A VHDL
or Verilog or Spice netlist can be generated from the drawn schematic, allowing the 
simulation of the circuit. Key feature of the program is its drawing engine written in C
and using directly the Xlib drawing primitives; this gives very good speed performance,
even on very big circuits. The user interface is built with the Tcl-Tk toolkit, tcl is
also the extension language used.

DOCUMENTATION AND MANUAL

http://repo.hu/projects/xschem

BUILDING & RUNNING

Please read additional information in file INSTALL_WIN for installation instructions

SUBDIRECTORIES

XSchemWin:       Windows specific files (e.g. xschem.tcl, xschemrc, config.h)

INSTRUCTIONS TO COMPILE XSCHEM IN VISUAL STUDIO 2022

1. requirements

    - Microsoft Visual Studio 2022
    - Wix Toolset Visual Studio 2022 Extension (Download through Microsoft Extensions on VS 2022)
    - Wix Toolset Build Tools v3.11 (Download online from wixtoolset)
      (WiX Toolset requires the .NET Framework 3.5.1 Windows feature to be enabled.)
        Turn Windows features on or off
        Select .NET framework 3.5 (include .NET 2.0 and 3.0)
    - ActiveState tcl/tk 8.6 (Remember install directory where includes files are, see step h)
      32-bit, 64-bit ActiveState need to match XSchem x86, x64, respectively.
    - bison (Remember executabled directory for step h, preferably don't have spaces in the directory path (ie., don't use Program Files)) 
      (http://gnuwin32.sourceforge.net/packages/bison.htm, Complete package, except sources (bison-2.4.1-setup.exe))
    - flex (Remember executabled directory for step h, see bison note)
      (http://gnuwin32.sourceforge.net/packages/flex.htm, Complete package, except sources (flex-2.5.4a-1.exe))
   
   Optional:
    - Windows Ghostscript (to print)
      Add directory of gswin64.exe to PATH if installer didn't do it
    - Jpeg for Windows (GNU Win32)
      http://www.ijg.org

*** NOTE: DO 2A OR 2B, but NOT BOTH ***
2A. Steps in (2B) are already saved in XSchemWin/XSchemWin.sln.
    Open "XSchemWin/XSchemWin.sln" in VS2022  and proceed to (3).
    2B is very helpful if you run into compile errors in VS2022.

2B. Create new XSchemWin project on Visual Studio 2022

    a. Open VS2022
    b. Create a new project 
    c. Select Empty Project
    d. Project Name: XSchemWin
          Location: D:\Projects\XSchem
          Solution Name: XSchemWin (Check Place solution and project in the same directory).
    e. Click Create
          A new folder XSchemWin will be created (XschemWin.sln and XSchem.vcxproj)
    f. Add C/H files under src into the project (e.g. svn://repo.hu/xschem/trunk/src)
          - Exclude src/expandlabel.c, src/expandlabel.h, src/parselabel.c (add later after using Windows Flex and bison)
          - Exclude src/xschem.tcl and src/xschemrc (add the two files from svn://repo.hu/xschem/trunk/src/XSchemWin/)
          - Add config.h from svn://repo.hu/xschem/trunk/src/XSchemWin/
            config.h is generated by Linux counterpart.  Edit if necessary
    g. XSchemWin Property Page > Linker > Input (All Configuration for x64 depending on what machine dependency you installed for Active State): 
          Add "tcl86t.lib;tk86t.lib" for Additional Dependencies
    h. For (All Configurations, x64)
          XSchemWin Property Page > VC++ Directories > Include Directories, Add "C:\ActiveTcl\include"
          XSchemWin Property Page > VC++ Directories > Library Directories, Add "C:\ActiveTcl\lib"
          XSchemWin Property Page > VC++ Directories > Executable Directories, Add "D:\GnuWin32\bin"
    i. XSchemWin Property Page > C/C++ > Preprocessor, Add ";_CRT_SECURE_NO_WARNINGS" to proceed with the following compile error:
          Severity	Code	Description	Project	File	Line	Suppression State
          Error	C4996	'sprintf': This function or variable may be unsafe. Consider using sprintf_s instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.	XSchemWin	D:\Projects\XSchem\src\actions.c	117	
    j. Right click parselabel.l
          Property Pages > Item type, change from "Does not participate in build" to "Custom Build Tool"
          Click Apply to get options for "Custom Build tool"
          Command Line: flex -l -oparselabel.c ..\src\parselabel.l
          Outputs: parselabel.c
    k. Right click expandlabel.y
          Property Pages > Item type, change from "Does not participate in build" to "Custom Build Tool"
          Command Line: bison -d -o expandlabel.c ..\src\expandlabel.y 
          Outputs: expandlabel.c

3. Compiling
    - config.h can be edited to change default's XSCHEM_LIBRARY_PATH.
      It's defaulted to include the following directories:
        C:/Program Files/XSchem/share/xschem/xschem_library/devices
        C:/Program Files/XSchem/share/doc/examples
        C:/Program Files/XSchem/share/doc/ngspice
        C:/Program Files/XSchem/share/doc/logic
        C:/Program Files/XSchem/share/doc/binto7seg
        C:/Program Files/XSchem/share/doc/generators
        C:/Program Files/XSchem/share/doc/pcb
        C:/Program Files/XSchem/share/doc/rom8k

     Ctrl-b
     - After compiling the first time, add expandlabel.c, expandlabel.h, parselabel.c into the project.
       These 3 files are created in D:\Projects\XSchem\XSchemWin

4. running from Visual Studio 2022.  If you run the debug version, you can set breakpoints on the code and step the code with VS 2022.

     F5

5. To compile and create Xschem Windows Installer
   a. Right click on "XSchemWix" and select "Build"
   b. If the compilation is successful, the Windows installer is located in XSchemWix/bin/Release/XSchem.msi
   c. Double click on XSchem.msi to install it into it on your Windows machine.
   d. Use Windows "Add or Remove Programs" to uninstall Xschem before installing a newer version.

INSTRUCTIONS TO COMPILE CAIRO AND COMPILE XSCHEM WITH IT ON VISUAL STUDIO 2022

1. Create a cairo_win directory in XSchemWin
2. cd cairo_win and git clone from "https://github.com/gleb-t/Cairo-VS" (inside the newly cairo_win directory, use command "git clone https://github.com/gleb-t/Cairo-VS .")
   Note: Latest source can be downloaded from the following (or alternatively, you can use packed-lib-source.zip provided by gleb-t):
     a. cairo: https://www.cairographics.org/releases/ (e.g. cairo-1.16.0.tar.xz)
     b. freetype: https://github.com/freetype/freetype
     c. libpng: http://www.libpng.org/pub/png/libpng.html (e.g., libpng-1.6.37.tar.gz)
     d. pixman: https://www.cairographics.org/releases/ (e.g., pixman-0.40.0.tar.gz)
     e. zlib: https://zlib.net/ (e.g., zlib-1.2.11.tar.gz)
   Put each source content into the appropriate subdirectory in cairo_win directory.
   For example, in cairo_win/cairo folder, you should have the following folders: boilerplate, build, doc, perf, src, test, util, ...
3. Compile freetype (x64, release_static) library in freetype directory:
     a. Open freetype/builds/windows/vc2010/freetype.sln in VS2022
     b. Select Release_static; x64 and build solution (library file is created in freetype\objs\x64\Release Static\freetype.lib)
4. Compile cairo: Open VS 2019 solution in projects/cairo.sln (Retarget solution if using VS 2022)
   a. Change to Release, x64 build
   b. Change cairo > Properties > Librarian > General > freetype271.lib to freetype.lib (Optional: Also do this for Debug,x64 build if needed, freetype271d.lib)
   c. cairo > Properties > Configuration Properties > VC++ Directories, append the following to Library directories for freetype.lib compiled in (3):
        ;$(ProjectDir)../../freetype/objs/x64/Release Static
        For Debug,x64 build: ;$(ProjectDir)../../freetype/objs/x64/Debug Static 
   d. Edit cairo > Header Files > cairo-features.h by adding the following line "#define CAIRO_HAS_XLIB_SURFACE 1" at the end before the last #endif
   e. cairo.lib and pixman.lib are in cairo_win/projects/x64/Release
5. Setup xschem VS 2022 to compile with cairo library 
   a. Uncomment "#define HAS_CAIRO 1" and "#define CAIRO_WIN32_STATIC_BUILD" in config.h

   *** Note: Do 5B OR 5BB, but NOT BOTH *** 
   Steps in (5bb) are saved in XSchemWin_cairo.vcxproj *** 
   b. To use it:
      (i) Close the solution
      (ii) Rename non cairo XSchemWin.vcxproj to some other name
      (iii) Change XSchemWin_cairo.vcxproj to XSchemWin.vcxproj.
       
   bb. For Release, x64
       * Properties > VC++ Directories > Include: ;cairo_win\cairo\src;cairo_win\projects\cairo\src;
                                         Libraries: ;cairo_win\projects\x64\Release;cairo_win\libs;cairo_win\freetype\objs\x64\Release Static
       * Properties > Linker > Input > Additional Dependencies: Add ;cairo.lib;pixman.lib;zlib.lib;libpng.lib;freetype.lib;
       For Debug, x64
       * Properties > VC++ Directories > Include: ;cairo_win\cairo\src;cairo_win\projects\cairo\src;
                                         Libraries: ;cairo_win\projects\x64\Debug;cairo_win\libs;cairo_win\freetype\objs\x64\Debug Static
       * Properties > Linker > Input > Additional Dependencies: Add ;cairo.lib;pixman.lib;zlibd.lib;libpngd.lib;freetype.lib;

OPTIONAL: INSTRUCTIONS TO COMPILE WITH JPEG FOR WINDOW (To be used with CAIRO)
   1. Download jpegsr9e.zip from http://www.ijg.org/ (as of 1/30/2023)
   2. Unzip jpeg-9e into cairo_win directory (See above)
   3. Open the Developer Command Prompt for VS 2022 (Tools > Command Line > Developer Command Prompt)
   4. cd to source  in (2) 
   5. Type: nmake /f makefile.vs setupcopy-v17
   6. Open the solution file jpeg.sln, build the library project.
   7. Build for Release, x64

   Updating Xschem's properties and compile:

   Uncomment the following from config.h
   a. /* #define HAS_LIBJPEG 1 */
   b. For Release and Debug, x64
        * Properties > VC++ Directories > Include: ;cairo_win\jpeg-9e
                                          Libraries: ;cairo_win\jpeg-9e\Release\x64
        * Properties > Linker > Input > Additional Dependencies: Add ;jpeg.lib