UP

# TUTORIAL: Manage XSCHEM design / symbol libraries

There are various ways to describe symbol locations in xschem,

- first approach: define a `XSCHEM_LIBRARY_PATH` that is a list of paths to last level directories containing .sym /.sch files
- second approach: define a `XSCHEM_LIBRARY_PATH` that is a list of paths one or more levels above the directories containing .sym/.sch files
- Third approach: define a `XSCHEM_LIBRARY_PATH` that is a hierarchy of paths, zero, one or more levels above the directories containing .sym/.sch files. If you have a directory tree where each directory level may contain .sch and .sym files you should list the deepest directories first so xschem will start searching for a symbol reference in the deepest levels first.

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
      }