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

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 done, but use will likely uncover things that need fixing.

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.

Status as of September 17, 2024

• The build and packaging systems can generate and contain separate binaries for GTK2, Qt-5, and Qt-6 toolkits. This is temporary, as GTK2 will go away at some point.
• Pre-built packages contain GTK2 and Qt binaries.

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 may have reasonably current packages available.

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 operating systems.

3.3.a Installing Needed Packages on Linux

To install system software 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 (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) Qt5 (For Qt. You can alternatively install the newer Qt6 if available)

The gtk2 and Qt packages 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 mostly specified the Qt5 libraries here. These may well be already installed, and seemed to be the standard. You should also be able to build with the newer Qt6 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, Debian 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/ AlmaLinux8/ 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.3.b Installing MSYS2 and Needed Packages on Windows

This is based on experience installing on a new Windows 11 machine, June 2024.

Currently the MSYS2/MinGWx64 environment is used to build and run on Windows. This replaces the "gtk2-bundle" which provided the needed libraries previously and was distributed with the program packages. The user will have to install the MSYS2/MinGW64 environment.

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. The package manager program for MSYS2 is named "pacman". Basic information on this can be found in the installation web site. It will be used to add packages to the shell environment to support building/running XicTools. Type the commands below to install the needed packages. In the future, you may wish to install extra goodies, a lot is available.

Add the software development commands for the "MinGW" environment. MinGW "Minimal GNU for Windows" is a simplified Linux-like environment called "Posix" provided by Microsoft as part of Windows.

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/or Qt 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 git
pacman -S autoconf-wrapper

That is all of the packages that need to be installed currently. You should now close the shell window.

In the future, to upgrade the packeges to the lastest, give the command

pacman -Syu

This should be done every so often to keep current. When this is done, the XicTools programs should be rebuilt, as will be described below.

To continue with the configuration and build, you should open a new shell window specificly for the MinGW64 environment. In the Start menu, scroll down to th MSYS2 entry and open the sub-menu. There are five alternative environments available. Select the one with the MinGW64 label. You should ALWAYS choose this option for working with XicTools programs, the others will probably NOT WORK! Making the selection will bring up a new shell window, similar to what you had before, but the prompt will include "MinGW64".

You will always use a window like this to build and run XicTools programs. It is similar to a Linux shell, and provides many of the same commands. You can add more of your favorite Linux commands with the pacman tool.

We can now continue the first time only configuration.

1. Type the following command.

   mkdir -p /c/usr/local/xictools

2. 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. Of course, replace with the correct text. This is the name of the current directory, or the name printed when you give the "whoami" command.

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

3. You will need to set "Developer Mode". Developer mode is required to create symbolic links, used in the install. a. From Settings (gear-shaped icon in the Start menu) select System b. Scroll down to "For Developers" and select. c. Turn on "Developer Mode", answer prompt.

4. Finally, if you intend to create packages, you will need the inno-setup packager (http://www.jrsoftware.org/). The Makefiles assume release 6.6.3. 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-6.6.3 which is mounted on /inno-6.6.3 in MSYS2.

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

3.3.c Installing MacPorts and Needed Packages on macOS.

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 will provide 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, the following commands:

   Warning: For a few weeks after a major OS release, these commands build from source and can take hours to run. Also, there might be failures, requiring some googling to find fixes. At some point, packages become available at which point the commands run fairly quickly and failures are very unlikely.

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

   (This is for adms maintenance mode, you won't need it unless you work on adms.) sudo port install perl5.34-xml-libxml

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

In the future you will want to update the ports every so often to keep current. This can be done with the commands

sudo port -v selfupdate
sudo port upgrade outdated

After doing this you will need to rebuild and reinstall the XicTools programs as will be described below.

The Qt versions of the tools are "native" macOS 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.

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).

Here is the starting point to create a new xictools git repository. Make sure that you have the git program installed (the command "which git" should provide a path to the git program). It needs to be installed if not. From a terminal (shell) window give the following command to clone the xictools repository into the current directory:

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

You should then have a subdirectory named "xictools" which contains this README file, and a whole lot more. This contains all of the source code for XicTools, and a "hidden" compressed git database. You will build the tools in this area.

3.5 The Build Procedure.

First, change to the top directory of the cloned repository created as above.

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 basic procedure is as follows.

The first time, you will need to set up the main Makefile.

1. Copy Makefile.sample into "Makefile", edit Makefile to set the configuration flags, as described by the comments in the Makefile. Crucial for Windows: uncomment the MINGW define.

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 everything went correctly 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".

5. Make sure that your shell search path includes the main XicTools bin, which is by default /usr/local/xictools/bin. Use the actual path if you changed PREFIX in the Makefile.

The present package releases of the XicTools contain separate binaries using the GTK2 and Qt graphics packages used for the GUI display. This is likely to be temporary as the Qt versions will replace the GTK versions, as the GTK2 library is considered to be obsolete. For now, both version are included for comparison purposes, and possibly as a work around if there is trouble with one or the other.

When building the source, you can use the following procedure to build both versions.

1. After setting up the top-level Makefile as normal, run make reconfig make all (Note: if this is the first time building, or you have run "make distclean" run "make config" rather than "make reconfig".)

2. Edit the top-level Makefile to switch the chosen graphical toolkit to Qt from GTK2 or vice-versa. If doesn't matter which you start with.

3. Give the commands make reconfig make all (Note: only the parts that change will be rebuilt, not the whole thing!

This completes the build procedure.

3.6 The Installation Procedure.

The present default installation 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 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 building/installing packages:

1. "make packages" will create all of the package files. Packages are left in xictools/xt_base/packages/pkgfiles. It may take half an hour or so, since this builds the example Verilog-A models for WRspice which takes a while.

2. 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 if you are installing to a location where you have write permission.

Otherwise: 1,2. 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 becoming 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.

You should now be able to use the programs. Have fun!

3.7 Switching between running GTK2 and Qt-based tools.

You can switch between the two versions using a .xtrc file which is found either in the current directory or your home directory. You will need to create this file to use the Qt version. This is easily done with a text editor. If this file is not found, GTK2 is the default.

The .xtrc file contains a single line that looks like grpref=GTK2

Note that there is no white space around the '=' character. The GTK2 is replaced by QT5 or QT6 when you want to run Qt. The 5/6 corresponds to the Qt version, either of which can be used if you build from source. For the packages, the Qt versions included are Windows QT6 macOS QT6 all Linux QT5

You can change which version to run by modifying the .xtrc file with a text editor. This will take effect the next time a graphical tool is started.

4.0 Maintaining the Installation Using Git

There are two "branches" in the git repository: "master" (the default) and "devel". The "master" branch is intended to provide stable releases of the tools for effective use, and most users should choose this. The devel branch represents the latest development code. You should track this if you are helping develop the programs, or just want the latest. However, programs may not build and other transient problems may be encountered.

To check out the devel branch, give the command git checkout devel To revert to the master branch git checkout master To see which branch you're on git branch

To update the current branch code to the latest from the github repository: git pull

You should do this every so often to update your source code so as to not get too out of date.

On Windows and macOS, you should periodically upgrade the packages you have installed to support XicTools. For Windows the command is

pacman -Syu

For macOS the commands are

sudo port selfupdate
sudo port upgrade outdated 

After updating, or changing the branch, you will need to recompile and reinstall the programs. This means repeating the procedure described above: make reconfig make all follow the installation procedure you have chosen

If your operating system is updated, you may also want to rebuild the programs, however this is only required if a program no longer works. This can happen if a system library is updated, and no backwards compatibility library is provided. In this case, run the same commands as above to rebuild/reinstall the tools.

End of document.