XicTools Open-Source  Release
                         October 1, 2017
                       Revised May 29, 2022

Whiteley Research is pleased to offer the XicTools programs:  Xic
(graphical editor) and WRspice (circuit simulator) as open-source. 
The two programs have sold commercially for more than 20 years, having
been updated steadily along the way.  However, a lot more development
is required to increase usage, and Stephen Whiteley, the author of most
of this, is ready to try a new approach.

It is expected that these programs will enjoy accelerated development
in an open-source environment, with the contributions of one and all
adding capability.  One day they may become widely used and known for
stability and available on-line support through user and developer
groups.  With this critical mass, the programs may become a viable
choice for foundry users, particularly those who may lack the
resources to pay for the Big Box tools.  This would never be achieved
with a proprietary software model given the limited capabilities of a
tiny company such as Whiteley Research.

The XicTools software is being released under the Apache-2.0 license,
which is actually one of the most "free" licenses available.  One is
not restricted in using this software in a commercial environment, or
in commercial products.  There is no requirement that you must share
your source code if you use this.  The code can be redistributed with
few restrictions.  See the LICENSE-2.0.txt file for the wording of the
license.  Basically, if you are commercial and this software can add
to your bottom line, go for it, and we might even help you!

However, this software, like virtually all software, has a history. 
Much of it originalted from places like the University of California,
Berkeley (e.g., WRspice is a direct descendent of Berleley Spice). 
There are bits and pieces that come from other universities.  The
university licenses are also very unrestrictive and likely highly
compatible with the Apache-2.0 license (remember that if you paid US
taxes, you almost certainly paid for the software developed at the
university).

At least one accessory (the help viewer) is tainted by the GNU library
license.  So, at the time of this initial release, there may be some
question as to whether the full terms of the Apache-2.0 license apply
in some cases.  This shall presumably be clarified in the future.  All
old headers have been retained, so users can make their own judgement
about the constraints on a given set of files.  Incorporating a better
HTML viewer, that understands CSS, should be a priority.


1. Overview - What's Here

The distribution consists of several semi-independent programs and
libraries, rooted in subdirectories.  These are described below.

adms
This is a wrapper around the adms tool for creating run-time loadable
device models for WRspice.

fastcap
This is a customized version of the venerable capacitance extraction
program from MIT.  It is called from within Xic for capacitance
extraction of layouts, and can be used stand-alone as well.

fasthenry
This is a customized version of the venerable inductance extraction
program from MIT.  It is called from within Xic for inductance
extraction of layouts, and can be used stand-alone as well.

KLU
This is simply a wrapper around the SuiteSparse sparse matrix package
written by Timothy A. Davis, available from
http://faculty.cse.tamu.edu/davis/suitesparse.html

The provided makefile operates on the SuiteSparse distribution file,
applying needed patches, compiling and linking.  The reslt is a
run-time loadble module which provides the sparse matrix capability,
for use with WRspice (or any other application with a suitable interface).
WRspice does not require this plug-in, but will employ it when provided.
Use of the SuiteSparse package generally reduces simulation time.

mozy
The mozy package contains the help system and viewer used by Xic and
WRspice, including an http/ftp file transfer utility, and a screen
capture into image file utility.  This code (and only this program
code) is derived from GNU-licensed code.  Commercial users may wish to
build the XicTools without the mozy package, which is a top-level
option.

mrouter
The MRouter is derived from the Qrouter maze router by Tim Edwards,
available at http://www.opencircuitdesign.com.  It may be used as a
stand-alone tool similar to Qrouter, or run-time loaded into Xic as
a plug-in, in which case its functionality is available within Xic.
This integration is at a very early development stage.

secure (aka xtlserv)
This package provides the license server, client-side code, and
license-generating utilities for the licensing system used with the
commercial version of Xic and WRspice.  This, of course, is no longer
used.  This package is retained, for now at least, in the chance that
it may be of value to someone.

vl
This is a Verilog simulator, which is integrated with WRspice but can
be used as a stand-alone non-graphical simulator.

wrspice
The WRspice program is a SPICE-derived circuit simulator.

xic
The Xic program is a graphical editor, used for displaying and editing
layouts and schematics.  It provides DRC, extraction, and a lot of
other  capability.

xt_base
This contains base libraries and configuration scripts for use with
the other packages.


2.  Dependencies

wrspice
  mozy (optional)
  xt_base
  KLU
  vl

xic
  mozy (optional)
  xt_base
  mrouter

mozy
  xt_base

vl
  xt_base

adms
fastcap
fasthenry
  xt_base


3.  Building the XicTools

3.1  Graphics Toolkit

The Xic, WRspice and other graphical programs have historically used
the GTK-2.0 toolkit.  This, however, is rather old and obsolete. 
After an abortive effort to migrate to GTK-3.0 (which is also obsolete
but less so) it became clear that a major change of direction was
required, and a huge effort was initiated to switch to the Qt toolkit. 
This is mostly done, but details are still being fixed and probably a
lot of issues will be uncovered in use.

Status as of April 27, 2024
- The GTK-2.0 remains as the "reference".
- Pre-built packages use the GTK-2.0 toolkit.
- The GTK version should be considered as approaching "end of life".
- Qt releases are equivalent and users are encouraged to try them.
- New features will be developed in the Qt branch, and may not be
  ported to the GTK branch.

3.2  Packages vs. Building from Source

Historically, pre-built packages were available for various operating
systems on wrcad.com.  However, due to time constraints the packages
have not kept up with operating system or code changes, and only
Windows has up-to-date packages available at this point.

The plan is to drop packages entirely, and instead users will build
from source.  By providing detailed information and possibly
automation scripts, building from source should be easy for most
users.  This will provide several advantages for users:

1. The tools can be updated through a simple command, and rebuilt.
2. If the operating system is updated, the tools can be rebuilt if
   necessary.
3. Users can track either the "master" branch, which is stable, or
   the "devel" branch, which contains the latest code (or both).
4. Users can control aspects of the build, such as file locations,
   GTK vs. Qt, etc.
5. We at the factory can focus on improving the programs instead of
   churning out and uploading package files.
6. The make system used to build the programs can also generate
   package files, so if anyone wants to produce their own, this is
   possible.

3.3  Building from Source, Prerequisites

The XicTools can be built on macOS with MacPorts, Windows with MSYS2,
or any reasonably current Linux system.

In general, it will be helpful to have some familiarity with building
open-source software, with makefiles, compilers, and the tools needed
to build and maintain Linux programs.  However, this is mostly for
cases when something goes wrong, so the user can diagnose and fix a
problem.  Eventually, we hope to make everything "just work" with no
intervention required, but this will take time to evolve.

Your system will need to have the standard software development tools
and utilities.  You will also need to have the development versions of
several different libraries installed.  As you encounter missing
header files, etc., these should be installed on your system from your
operating system source repositories.  It can be a bit of a challenge
to figure out which packages to install, Google is your friend. 
Requirements are partially listed below for various operting systems.

To install system software as above on Linux, you will need root
permission, or an IT department that can do this for you.  If you
are already in a corporate software development environment, then
this software will quite likely be installed already, as it is at
Synopsys, for example.

Programs and Utilities:
There may be a meta-package containing the development toolchain,
which should be installed.  These programs may be missing and would
require installation.

  git, autoconf, flex, bison,
  pkg-config for GTK only

Libraries and Development Packages:
Often, the basic libraries are provided, but a separate "devel"
package contains the include files needed to compile programs with the
libraries.  If a build fails with a missing header (.h) file, the game
is to figure out which development package provides it, and install
the package.  In other cases, the library may be wholly missing, so
both the library and development packages should be installed. 
Install the devel version, which will also install the bare library if
necessary.

  libgsl, libjpeg, libtiff, ncurses
  gtk2, (GTK only)

The gtk2 package will bring in a large number of dependent packages.

Below are lists of package names that I had to install on some
operating systems.  Note that I've specified the Qt-5 libraries here. 
These may well be already installed, and seemed to be the standard. 
You should also be able to build with the newer Qt-6 libraries if
available.  These would have the same form as below but with "qt5" ->
"qt6".

I've indicated the requirements for GTK and Qt below. You can choose
either one or both, depending on the tools version(s) you intend to
build.

Note:  It doesn't hurt to attempt to install software that is already
installed with the commands below.  If the software is alredy installed.
you will get a message indicating this.

Ubuntu 20
Debian 11
   These use the same packages.  The "build-essential" provides the
   program development toolchain.  The package names can be listed after
   "apt install", or the command can be invoked on the packages
   individually or in smaller groups.

   apt install build-essential autoconf automake flex bison gpp git
   apt-install libgsl-dev libtiff-dev libjpeg-dev libncurses5-dev
   apt-install libgtk2.0-dev  (for GTK)
   apt-install qt5-qtbase-devel  (for Qt)

Fedora 40
    In Fedora, the development tools are preinstalled, but you may have
    to install g++ to get C++ support.  Again, packages can be installed
    one at a time or in groups.

    dnf install autoconf automake flex bison patch g++ gpp
    dnf install gsl-devel rpm-build libjpeg-turbo-devel ncurses-devel
    dnf install gtk2-devel  (for GTK)
    dnf install qt5-qtbase-devel  (for Qt)

CentOS 8 Stream/ Rocky 8/ Red Hat 8
    The first line installs the development tools, including for C++.

    dnf group install "Development Tools"
    dnf install gsl-devel ncurses-devel libtiff-devel libjpeg-devel
    dnf install gtk2-devel  (for GTK)
    dnf install qt5-qtbase-devel  (for Qt)


3.4  Obtaining the Git Repository

The file you are presently reading (README) is at the top level of the
XicTools source tree.  It may or may not be part of a git repository
depending on how the files were obtained.  You really want to have a
git repository, and not just a collection of files from a zip or tar
file.  The "git" program is a software management tool, and using a
git repository allows you to update the files from the primary
repository on github.com with a simple command.

If there is a subdirectory named ".git" in the directory containing
this file, then you probably have a git repository.  If not, lets
start over.  Go to the parent directory containing this one, and use
"rm -rf" to delete this directory and everything under it (which will
include this file unless you save a copy some place).

Next, give the following command to clone the xictools repository into
the current directory:

git clone https://github.com/wrcad/xictools.git

If this fails because "git" is not found, then you will need to install
it (see previous section).  This would be uncommon to not find git
installed on a Linux system, however you will need to instal the MSYS2
version on Windows or the MacPorts version on macOS, see instructions
that follow.

Otherwise, you should have a subdirectory named "xictools" which contains
this README file, and a whole lot more.
  

3.4  Build Procedure for Linux

This section assumes that you are in the directory containing this
README file in your xictools git repository.  It assumes that you have
installed the software build tools and development libraries as listed
above, or a best guess depending on your system.

The procedure is as follows.

    1.  Copy Makefile.sample into "Makefile", edit Makefile to set the
        configuration flags, as described in the Makefile.
    2.  Give the command "make config" to configure the source tree to
        your build environment.  You may see errors and early termination
        if there are missing utilities or libraries.  This should take
        maybe 5 minutes.
    3.  Give "make all" to build all of the programs.  If all went
        right for Xic and WRspice, there should be files present:
        xic/bin/xic and wrspice/bin/wrspice
    4.  in the future, after changes, do "make reconfig" followed by
        "make all" to rebuild the programs.  Alternatively, if you
        want to start over from a fresh environment, give
        "make distclean", then "make config" and "make all".

The present default build procedure assumes that the intended
installation procedure is to first build a binary package (e.g., RPM)
for each program, then install the packages on your system using the
wr_install script.  The wr_install script is available on wrcad.com
with the package files, and in the source tree under
xictools/xt_base/packages/util/wr_install.  The Makefiles will
actually prevent running "make install" to the default location
(typically under /usr/local).  However, you can modify the top-level
Makefile (in this directory) to allow this (see the ITOPOK variable),
and skip the packaging step entirely if you wish.

If you are buikding/installing packages:
    5. "make packages" will create all of the package files.
       Packages are left in xictools/xt_base/packages/pkgfiles.

    6. cd to xt_base/packages/pkgfiles, then give
       "../util/wr_install all". This will install the programs from
       the package files.  If you are installing to a system location
       such as the default under /usr/local, you need to have sudo
       privileges.  The wr_install script will ask for your password. 
       It doesn't matter if this fails of you are installing to a
       location where you have write permission.

Otherwise:
    5,6.  If you are installing to a system location like the default
       under /usr/local, you must get root privileges somehow.  On
       Current Linux systems this means that you will probably use the
       sudo command and your account will be listed in the
       /etc/sudoers file.  If at work, you may have to get help from
       IT.  However you can install to a directory where you have
       write permission without becomming root.  Next, give "make
       install".  It may take half an hour or so, since this builds
       the example Verilog-A models for WRspice which takes a while.
    
In either case:
    7. Set your shell search path to include the main XicTools
       bin, by default /usr/local/xictools/bin.

You should now be able to use the programs.


3.3  Windows

Currently the MSYS2/MINGWx64 environment is used to build and run on
Windows.  The user will have to install this environment, or at least
the run-time components.  This replaces the "gtk2-bundle" which
provided the needed libraries previously and was distributed with the
program packages.

Go to msys2.org, download and run the installer, and follow the
instructions, using the defaults.  When done you will have a shell
window on screen.  Add packages as needed, but you will want the
development toolchain for mingw64:

    pacman -S base-devel
    pacman -S mingw-w64-x86_64-toolchain

Add the vim editor, the winpty program needed to run wrspice, and
the mingw64 versions of the gtk2 and gsl libraries.

    pacman -S vim
    pacman -S winpty
    pacman -S mingw_w64-x86_64-gsl
    pacman -S mingw_w64-x86_64-gtk2  (for GTK)
    pacman -S mingw_w64-x86_64-qt6  (for Qt)

Add some other needed utilities:

    pacman -S autoconf-wrapper
    pacman -S bison
    pacman -S flex
    pacman -S make
    pacman -S patch
    pacman -S libiconv-devel
    pacman -S ncurses-devel

Use the vim editor to edit the .bash_profile file that exists in the
current (and home) directory adding the following lines to the bottom
of the file.

    mount c:/usr/local/xictools /usr/local/xictools
    export PATH="/usr/local/xictools/bin:$PATH"
    export XT_HOMEDIR=c:/msys64/home/<your_username>

Of course, replace <your_username> with the correct text.

Also used is the inno-setup 5.5.9 packager
(http://www.jrsoftware.org/).  You might wish to get this (or a newer
release) if you intend to produce packages for Windows.  The XicTools
Makefile assumes that this is installed at c:/inno-5.5.9 which is
mounted on /inno-5.5.9 in MSYS2.

To start the shell window the next time, click "MSYS2 64bit" in the
Start menu, then click "MSYS2 MinGW x64" in the sub-menu.  This
provides the MSYS2 shell environment with support for mingw64.  MinGW
is "minimal Gnu (for) Windows" and is a library that provides a
limited Linux-like programming environment under Windows.  The
XicTools programs use this environment and are thus Windows-native
programs.

This is about complete to build XicTools, but there may be a thing or
two missing.  You will have to use the "pacman" package manager
commands to find the package needed, then use commands like above to
install it.

You will run the installer in the future to update your packages, and
to add packages needed later.

The actual build procedure follows the Linux procedure above, but there
is no need to worry about root access.


3.4  macOS

The Qt versions of the tools are "native" masOS applications.  Other
than not needing an X-server, the main difference is that the
application main menus appear in the Mac location at the top of the
screen, and not in the application window.

1.  Install xcode
    This is Apple's development package, available as a download from the
    App store.

2.  Install the "command line tools"
    Install this by giving the following command in a terminal window:
      xcode-select --install

3.  Run xcode to sign off on the license agreement.
    Give the following command and agree to the terms:
      xcodebuild -license

4.  To run the GTK versions of the programs you will need an X11
    server.  The recommended server is XQuartz (www.xquartz.org). 
    This is the "official" X server for the Mac, however others are
    available, including one through macports.  Follow the
    instructions to install and start the server.

    If you will build and run the Qt versions only, you do not need
    XQuartz.

5.  Download the MacPorts installer from macports.org.  This provides
    the graphical libraries used by the programs.  Following the
    instructions, install MacPorts for your operating system.  Be sure
    to install the default package which installs in the default
    location (i.e., don't build from source and change the location).

    Once the basic installation is done, run, as root, the following
    commands:

    port -v selfupdate
    port install gtk2  (for GTK)
    port install pkgconfig  (for GTK)
    port install qt6  (for Qt)
    port install gsl
    port install python2_select
    port install python27
    port install autoconf

6.  Set your shell search path to include /usr/local/xictools/bin.

You should now be able to build XicTools following the procedure above
for Linux.