Skip to content

Commit 62e45da

Browse files
author
Matthias Koefferlein
committed
Updating doc.
1 parent ad850f3 commit 62e45da

1 file changed

Lines changed: 190 additions & 0 deletions

File tree

‎src/doc/doc/about/about_libraries.xml‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
<title>About Libraries</title>
77
<keyword name="Library"/>
88
<keyword name="Libraries"/>
9+
<keyword name="Lib Files"/>
10+
<keyword name="Static Libraries"/>
911

1012
<p>
1113
Starting with version 0.22, KLayout offers a library concept.
@@ -50,6 +52,22 @@
5052
name of the library file minus the extension.
5153
</p>
5254
</li>
55+
<li><p><b>Layout files by declaration:</b>
56+
Starting with version 0.30.8, KLayout supports declaration of static libraries by
57+
a library definition file. This is an alternative mechanism to the "libraries" folder
58+
and has a number of advantages:
59+
</p>
60+
<ul>
61+
<li>Libraries can be referenced from any place in the file system</li>
62+
<li>Library definition files can include other files and include environment variables</li>
63+
<li>Additional attributes are available for declaration</li>
64+
</ul>
65+
<p>
66+
This feature is limited to static libraries - i.e. libraries declared by library
67+
definition files cannot include PCells. PCells are an exclusive feature of coded
68+
libraries.
69+
</p>
70+
</li>
5371
<li><b>Coded libraries:</b>
5472
Such libraries are provided by code, either through shared objects/DLL's or through Ruby code.
5573
Basically such code has to provide a layout object containing the library cells.
@@ -65,5 +83,177 @@
6583
about packages.
6684
</p>
6785

86+
<p>
87+
Static libraries, whether defined by a library declaration file or implicitly from the
88+
"libraries" folder, are automatically reloaded, when the file changes. If this feature
89+
is not desired, you can disable automatic reload in the Setup dialog and manually refresh
90+
the libraries if required.
91+
</p>
92+
93+
<h2>How libraries work</h2>
94+
95+
<p>
96+
Unlike other systems, libraries are not external references for KLayout. Instead, a library
97+
is essentially a copy source. When you use a library cell, it is copied into your
98+
working layout and is weakly linked to the original place. You can refresh the library,
99+
which will also refresh the copy. This process is called "replication".
100+
</p>
101+
102+
<p>
103+
This approach implies a memory adder, but has a number of benefits:
104+
</p>
105+
106+
<ul>
107+
<li>The working layout is "whole" - i.e. if a library vanishes or is not available
108+
when transferring the layout to someone else, the layout is still functional. The
109+
copy acts as a snapshot.
110+
</li>
111+
<li>
112+
The independent copy allows for compensating database unit differences and layer details,
113+
so the libraries can be made with a different database unit than the working layout for example.
114+
</li>
115+
<li>
116+
This design greatly simplifies the database organisation, as the internal
117+
structure does not need to care about layer index translations and all information
118+
needed to build lookup trees is available in a single layout object. It is easy
119+
to temporarily detach a layout object from the libraries without destroying the
120+
structure.
121+
</li>
122+
</ul>
123+
124+
<p>
125+
The design also implies that libraries are read-only. You edit the working
126+
copy only - library cells pulled into the layout are copies that cannot and
127+
should not be edited, as they are restored from their original source
128+
occasionally. Libraries should be thought of as external deliveries similar
129+
to Python modules for example.
130+
</p>
131+
132+
<p>
133+
When saving a working layout, the copies are stored in the layout file too.
134+
This feature can be disabled in a per-library basis in the library declaration
135+
files (only available for static libraries). See the description of the
136+
"replicate" attribute below. Note that when you use this feature, you can
137+
only restore the entire layout, if you have these libraries installed.
138+
</p>
139+
140+
<h2>Library declaration files</h2>
141+
142+
<p>
143+
By default, library declaration files are called "klayout.lib" and are looked up in
144+
all places of the KLayout search path - this includes the home folder, the technology
145+
folders and the package folders. You can override this mechanism by setting the
146+
"KLAYOUT_LIB" environment variable to a specific file. In that case, only this
147+
file is loaded.
148+
</p>
149+
150+
<p>
151+
The format of the library declaration file is "KLayout expressions". This means: function
152+
calls need to be with round brackets and expressions are separated
153+
by ";". For more information about expressions, see <link href="/about/expressions.xml"/>.
154+
</p>
155+
156+
<p>
157+
Two functions are available: "define" and "include". These are used to build
158+
the declaration files.
159+
</p>
160+
161+
<h3>"include" function</h3>
162+
163+
<p><b>Usage:</b></p>
164+
165+
<pre>include(path);</pre>
166+
167+
<p><b>Description:</b></p>
168+
169+
<p>
170+
Includes the lib file given by the path. The path is
171+
resolved relative to the current lib file.
172+
</p>
173+
174+
<h3>"define" function</h3>
175+
176+
<p><b>Usage:</b></p>
177+
178+
<pre>define(name, path [, options]);
179+
define(path [, options]);</pre>
180+
181+
<p><b>Description:</b></p>
182+
183+
<p>
184+
Defines a library. In the path-only version, the library name
185+
is taken from the layout file's LIBNAME record (GDS) or the
186+
file name. In the name/path version, "name" is the name the
187+
library is registered under.
188+
</p>
189+
190+
<p>
191+
The path is resolved relative to the current lib file.
192+
If you want to include an environment variable, use the "env" expression
193+
function:
194+
</p>
195+
196+
<pre>define("A", env("HOME") + "/mylibs/a.gds");</pre>
197+
198+
<p>
199+
Note that the order of library definitions matters. Dependencies
200+
need to be defined already when a library is loaded. For example
201+
if a library "B" uses components from library "A", the order needs
202+
to be:
203+
</p>
204+
205+
<pre>define("A", "a.gds");
206+
define("B", "b.gds");</pre>
207+
208+
<p>
209+
The following options are available:
210+
</p>
211+
212+
<ul>
213+
214+
<li>
215+
216+
<p><b>technology</b>: binds a library to a technology - i.e. it is only
217+
available in the editor when that technology is selected:</p>
218+
219+
<pre>define("A", "a.gds", technology="SG13A");</pre>
220+
221+
<p>
222+
By default, libraries are not bound to a technology, except if
223+
the library file is loaded in the context of a technology (i.e.
224+
sits in a technology folder). You can explicitly enable a library
225+
for all technologies using:
226+
</p>
227+
228+
<pre>define("A", "a.gds", technology="*");</pre>
229+
230+
</li>
231+
232+
<li>
233+
234+
<p><b>technologies</b>: binds a library to several technologies. The
235+
argument is a list:</p>
236+
237+
<pre>define("A", "a.gds", technologies=["SG13A","GF180"]);</pre>
238+
239+
</li>
240+
241+
<li>
242+
243+
<p><b>replicate</b>: this flag indicates that components of the library
244+
are replicated in the layout files using a library element.
245+
This allows loading that file without actually having the library.
246+
However, it comes with a size overhead, that can be avoided
247+
by skipping this replication:
248+
</p>
249+
250+
<pre>define("A", "a.gds", replicate=false);</pre>
251+
252+
<p>By default, replication is enabled.</p>
253+
254+
</li>
255+
256+
</ul>
257+
68258
</doc>
69259

0 commit comments

Comments
 (0)