UP

TUTORIAL: Manage XSCHEM design / symbol libraries

There are various ways to describe symbol locations in xschem,

In the first approach a 'npn.sym' symbol placed in a schematic will be saved as 'npn.sym' in the .sch file, when loading back the parent schematic xschem will go through the elements of XSCHEM_LIBRARY_PATH and look for a directory containing npn.sym.

In the second approach the 'npn.sym' will be saved as 'devices/npn.sym' (assuming devices/ is the directory containing this symbol) . This is because the XSCHEM_LIBRARY_PATH is pointing to something like /some/path/xschem_library/ and xschem_library/ contains devices/ (names are just given as examples, any dir name is allowed for xschem_library/ and devices/)

In the third approach 'npn.sym' or some other dir/symbol.sym will be searched in all path elements listed in XSCHEM_LIBRARY_PATH, by appending the symbol reference to each path element until a file is found. the first match is used. This is the reason you should put the deepest directories first in XSCHEM_LIBRARY_PATH. If /a/b/c/dir/symbol.sym is inserted in the design and XSCHEM_LIBRARY_PATH contains the following definitions:
set XSCHEM_LIBRARY_PATH /a/b/c /a/b /a
the symbol reference will be just dir/symbol.sym, since appending the symbol reference to the first path an existing file is found. If the following definition for XSCHEM_LIBRARY_PATH is given instead:
set XSCHEM_LIBRARY_PATH /a /a/b/ /a/b/c
then the symbol reference will be /b/c/dir/symbol.sym since the first path component was found in the absolute path of the inserted symbol and the only matching prefix is removed from the relative symbol reference that will be saved in the schematic.

The first approach is preferred by pcb hobbysts, people working on small designs. the second approach is preferred for big designs where a one or more directory level indirection is desired for symbols, so any symbol in xschem is given as 'libname/symname.sym' (one level directory specification in symbol references) or 'libgroup/libname/symname.sym' (2 level directory specification in symbol references) instead of just 'symname.sym'

SYMBOL LOOKUP (ie when loading a schematic):
The absolute path of the symbol reference is obtained by appending the symbol reference to the XSCHEM_LIBRARY_PATH paths in the order they are listed until the resulting file is found in the machine filesystem. The first match is used.
SYMBOL INSERTION (ie when drawing a schematic and inserting a component):
The relative symbol reference that is saved in the schematic file is obtained by removing the first occurrence of a matching path prefix from the ones listed in XSCHEM_LIBRARY_PATH in the order they are listed. The first matching prefix is used to determine the relative symbol reference. This is the reason deepest path elements must be listed first in XSCHEM_LIBRARY_PATH if you want the shortest possible symbol relative reference to be saved in the schematic file.

For VLSI / big designs I strongly suggest using the second approach, just as an example i have the following dirs: 

  ~/share/xschem/xschem_library/
    containing:
    devices/
    TECHLIB/
  
  ~/xschem_library/
    containing:
    stdcell_stef/
  
  ~/share/doc/xschem/
    containing:
    library_t9/
    dram/

then in my xschemrc i have the following:

set XSCHEM_LIBRARY_PATH \
$env(HOME)/share/xschem/xschem_library:$env(HOME)/share/doc/xschem/:$env(HOME)/xschem_library

You may choose either method, but please be consistent throughout your design.

Change project setup runtime

Since Xschem now handles multiple windows or tabs, it is desirasble to load schematics from different projects into a single running instance of xschem. This is not difficult to do and you might want to write your own procedure into your xschemrc to automate this. Lets suppose you open a new schematic tab. After opening the new tab go to the xschem prompt in the terminal you launched Xschem from, and redefine your XSCHEM_LIBRARY_PATH:

    set XSCHEM_LIBRARY_PATH {} ;# clear previous definitions
    append XSCHEM_LIBRARY_PATH :${XSCHEM_SHAREDIR}/xschem_library  ;# for devices/
    append XSCHEM_LIBRARY_PATH :/home/schippes/share/pdk/sky130A/libs.tech/xschem ;# for sky130 libs
    # project specific variables (either tcl variables or shell variables via the TCL env() array)
    set PDK_ROOT /home/schippes/share/pdk
    set PDK sky130A
    set SKYWATER_MODELS ${PDK_ROOT}/${PDK}/libs.tech/ngspice
    set SKYWATER_STDCELLS ${PDK_ROOT}/${PDK}/libs.ref/sky130_fd_sc_hd/spice

At this point your new tab will work with the new defnitions while the previous tab will continue with its previous settings.

you should create a small procedure and put int into your xschemrc so you will just need to type the procedure name: 


  proc set_sky130 {} {
      ## XSCHEM_SHAREDIR points to XSCHEM install path, example: /usr/local/share/xschem
      ## USER_CONF_DIR is usually ~/.xschem
      ## env may be used to set environment variables, like:
      ## set env(PDK_ROOT) .....
      global XSCHEM_LIBRARY_PATH XSCHEM_SHAREDIR USER_CONF_DIR env
      ## Other global TCL variables listed here depend on the project setup.
      global PDK_ROOT PDK SKYWATER_MODELS SKYWATER_STDCELLS

      # project specific variables (either tcl variables or shell variables via the TCL env() array)
      set PDK_ROOT /home/schippes/share/pdk
      set PDK sky130A
      set SKYWATER_MODELS ${PDK_ROOT}/${PDK}/libs.tech/ngspice
      set SKYWATER_STDCELLS ${PDK_ROOT}/${PDK}/libs.ref/sky130_fd_sc_hd/spice

      set XSCHEM_LIBRARY_PATH {} ;# clear previous definitions
      append XSCHEM_LIBRARY_PATH :${XSCHEM_SHAREDIR}/xschem_library  ;# for devices/
      append XSCHEM_LIBRARY_PATH :${PDK_ROOT}/${PDK}/libs.tech/xschem
  }