About Libraries

Starting with version 0.22, KLayout offers a library concept. Libraries are a way to import cell layout into a layout from the outside and thus a convenient way to provide standard building blocks for the layout. Using a cell from a library is easy: when asked for a cell, select the library where to take the cell from and choose a cell from that library.

Libraries are basically just foreign layouts that are virtually linked to the current layout. When a cell is imported from a library, it is copied into the current layout, so that the current layout by itself is a valid entity.

When a layout containing library references is saved, KLayout stores some meta information in that file which allows it to restore the library links and related information. For GDS, that meta information is stored in a separate top cell. For OASIS, the meta information is stored in special per-cell properties. For other formats, the meta information is not stored currently.

Libraries can be provided in several ways:

As ordinary layout files: Such libraries are simple layout files (GDS, OASIS or other support format). KLayout looks up those libraries in the "libraries" subfolders of the search path and gathers all layout files it finds there into the library repository.
The search path usually includes the installation site (where the KLayout executable resides) and the application folder (i.e. "~/.klayout" on Linux). Hence libraries can be installed locally (i.e. in "~/.klayout/libraries") or globally (at the installation site).
For GDS files, the library name will be the LIBNAME of the GDS file. Otherwise it will be the name of the library file minus the extension.
Layout files by declaration: Starting with version 0.30.8, KLayout supports declaration of static libraries by a library definition file. This is an alternative mechanism to the "libraries" folder and has a number of advantages:
- Libraries can be referenced from any place in the file system
- Library definition files can include other files and include environment variables
- Additional attributes are available for declaration
This feature is limited to static libraries - i.e. libraries declared by library definition files cannot include PCells. PCells are an exclusive feature of coded libraries.
Coded libraries: Such libraries are provided by code, either through shared objects/DLL's or through Ruby code. Basically such code has to provide a layout object containing the library cells. A coded library can also provide PCells (parametrized cells) as library components. Sell About PCells for details about parametrized cells.

Starting with version 0.25, libraries can be provides through packages. This means, they can be downloaded from some repository and can be managed within the package manager. Library installation is very simple this way. Library deinstallation too. See About Packages for details about packages.

Static libraries, whether defined by a library declaration file or implicitly from the "libraries" folder, are automatically reloaded, when the file changes. If this feature is not desired, you can disable automatic reload in the Setup dialog and manually refresh the libraries if required.

How libraries work

Unlike other systems, libraries are not external references for KLayout. Instead, a library is essentially a copy source. When you use a library cell, it is copied into your working layout and is weakly linked to the original place. You can refresh the library, which will also refresh the copy. This process is called "replication".

This approach implies a memory adder, but has a number of benefits:

The working layout is "whole" - i.e. if a library vanishes or is not available when transferring the layout to someone else, the layout is still functional. The copy acts as a snapshot.
The independent copy allows for compensating database unit differences and layer details, so the libraries can be made with a different database unit than the working layout for example.
This design greatly simplifies the database organisation, as the internal structure does not need to care about layer index translations and all information needed to build lookup trees is available in a single layout object. It is easy to temporarily detach a layout object from the libraries without destroying the structure.

The design also implies that libraries are read-only. You edit the working copy only - library cells pulled into the layout are copies that cannot and should not be edited, as they are restored from their original source occasionally. Libraries should be thought of as external deliveries similar to Python modules for example.

When saving a working layout, the copies are stored in the layout file too. This feature can be disabled in a per-library basis in the library declaration files (only available for static libraries). See the description of the "replicate" attribute below. Note that when you use this feature, you can only restore the entire layout, if you have these libraries installed.

Library declaration files

By default, library declaration files are called "klayout.lib" and are looked up in all places of the KLayout search path - this includes the home folder, the technology folders and the package folders. You can override this mechanism by setting the "KLAYOUT_LIB" environment variable to a specific file. In that case, only this file is loaded.

The format of the library declaration file is "KLayout expressions". This means: function calls need to be with round brackets and expressions are separated by ";". For more information about expressions, see About Expressions.

Two functions are available: "define" and "include". These are used to build the declaration files.

"include" function

Usage:

include(path);

Description:

Includes the lib file given by the path. The path is resolved relative to the current lib file.

"define" function

Usage:

define(name, path [, options]);
define(path [, options]);

Description:

Defines a library. In the path-only version, the library name is taken from the layout file's LIBNAME record (GDS) or the file name. In the name/path version, "name" is the name the library is registered under.

The path is resolved relative to the current lib file. If you want to include an environment variable, use the "env" expression function:

define("A", env("HOME") + "/mylibs/a.gds");

Note that the order of library definitions matters. Dependencies need to be defined already when a library is loaded. For example if a library "B" uses components from library "A", the order needs to be:

define("A", "a.gds");
define("B", "b.gds");

The following options are available:

technology: binds a library to a technology - i.e. it is only available in the editor when that technology is selected:
```
define("A", "a.gds", technology="SG13A");
```
By default, libraries are not bound to a technology, except if the library file is loaded in the context of a technology (i.e. sits in a technology folder). You can explicitly enable a library for all technologies using:
```
define("A", "a.gds", technology="*");
```
technologies: binds a library to several technologies. The argument is a list:
```
define("A", "a.gds", technologies=["SG13A","GF180"]);
```
replicate: this flag indicates that components of the library are replicated in the layout files using a library element. This allows loading that file without actually having the library. However, it comes with a size overhead, that can be avoided by skipping this replication:
```
define("A", "a.gds", replicate=false);
```
By default, replication is enabled.
description: Specifies a description for that library.
```
define("A", "a.gds", description="Library A");
```