UP

# TUTORIAL: Manage XSCHEM design / symbol libraries

There are 2 ways to describe symbols 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

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/`)

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`'

In any case the real path of the symbol reference is obtained by prepending the XSCHEM_LIBRARY_PATH paths to the symbol reference until the resulting file is found in the machine filesystem.

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
      }