luke
/
xschem
mirror of https://github.com/StefanSchippers/xschem.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

more details on xschem tutorial page about library path management

This commit is contained in:
stefan schippers 2023-12-29 22:57:19 +01:00
parent 64ca25b9fe
commit bc2676f211
1 changed files with 35 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/xschem_man/tutorial_xschem_libraries.html
View File

@ -19,7 +19,7 @@ p{padding: 15px 30px 10px;}
<!-- slide title -->
<h1> TUTORIAL: Manage XSCHEM design / symbol libraries </h1>
<p>
There are 2 ways to describe symbols in xschem,<br>
There are various ways to describe symbol locations in xschem,<br>
</p>
<ul>
<li>
@ -30,6 +30,12 @@ p{padding: 15px 30px 10px;}
second approach: define a <kbd>XSCHEM_LIBRARY_PATH</kbd> that is a list of paths
one or more levels above the directories containing .sym/.sch files
</li>
<li>
Third approach: define a <kbd>XSCHEM_LIBRARY_PATH</kbd> 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.
</li>
</ul>
<p>
In the first approach a '<kbd>npn.sym</kbd>' symbol placed in a schematic will be
@ -47,6 +53,22 @@ p{padding: 15px 30px 10px;}
examples, any dir name is allowed for <kbd>xschem_library/</kbd> and <kbd>devices/</kbd>)
</p>
<p>
In the third approach '<kbd>npn.sym</kbd>' or some other <kbd>dir/symbol.sym</kbd> will be searched in all
path elements listed in <kbd>XSCHEM_LIBRARY_PATH</kbd>, 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 <kbd>XSCHEM_LIBRARY_PATH</kbd>. If <kbd>/a/b/c/dir/symbol.sym</kbd> is inserted in the design and
XSCHEM_LIBRARY_PATH contains
the following definitions:<br>
<kbd>set XSCHEM_LIBRARY_PATH /a/b/c /a/b /a</kbd><br>
the symbol reference will be just <kbd>dir/symbol.sym</kbd>, 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:<br>
<kbd>set XSCHEM_LIBRARY_PATH /a /a/b/ /a/b/c</kbd><br>
then the symbol reference will be <kbd>/b/c/dir/symbol.sym</kbd> 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.
</p>
<p>
The first approach is preferred by pcb hobbysts, people working on
small designs.
@ -56,10 +78,18 @@ p{padding: 15px 30px 10px;}
or '<kbd>libgroup/libname/symname.sym</kbd>' (2 level directory specification in symbol references)
instead of just '<kbd>symname.sym</kbd>'<br>
</p>
<p>
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.
<p class="important"><strong>
SYMBOL LOOKUP (ie when loading a schematic):<br>
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.<br>
SYMBOL INSERTION (ie when drawing a schematic and inserting a component):<br>
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 <kbd>XSCHEM_LIBRARY_PATH</kbd> in the order they are listed. The first matching prefix
is used to determine the relative symbol reference. </strong> 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 saved in
the schematic file.
</p>
<p>