"Salt" is KLayout's package manager which allows selecting and installing packages from a global repository. Packages make KLayout more tasty. Packages (the "grains") may cover a variety of features:
Packages can depend on other packages - these are installed automatically if a package requires them and they are not installed yet.
Packages are identified by name. A package name needs to be unique in the package universe. You can use a prefixed name like www.mydomain.org/nameofpackage to create a non-ambiguous name. Use a slash to separate the prefix from the actual package name. The choice of the prefix is entirely up to you as long as it contains letters, digits, underscores, hypthens or dots. You can use a domain name that is owned by yourself for example. You can use multiple prefixes to further differentiate the packages inside your namespace.
Packages also come with version information, so KLayout can check for updates and install them if required. KLayout will assume strict upward compatibility. This specifically applies to packages that other packages are depending on (such as code libraries). If you need to change them in a non-backward compatible way, you'd need to provide a new package with a different name.
Packages come with some meta data such as authoring information, an optional icon and screen shot image, license information and more. The more information you provide, the more useful a package will become.
The key component for public package deployment is the "Salt.Mine" package repository service. This is a web service that maintains a package index. It does not host the packages, but stores links to the actual hosting site. In order to author a package, you need to upload the package to one of the supported host sites and register your package on the Salt.Mine page. Registration is a simple process and the only information required is the link to your host site and a mail account for confirmation.
To install external packages, open the package manager with "Tools/Manage Packages". On the "Install New Packages" page, a list of available packages is shown. Select the desired packages and mark them using the check mark button. Marked packages will be downloaded and installed with the "Apply" button.
A filter above the package list allows selecting packages by name. The right panel shows details about the package currently selected.
To check for updates, use the "Update Packages" tab of the package manager. In the list, those packages for which updates are available are shown. Mark packages for update using the check mark button. Click "Apply" to apply the selected updates.
To uninstall packages, open the package manager using "Tools/Manage Packages". Go to the "Current Packages" tab. Select a package and use the "Remove Package" button to uninstall the package.
For package development you can utilize KLayout to initialize and edit the files inside the package folder or populate the folder manually.
KLayout offers initialization of new packages from templates. You can modify that package according to your requirements afterwards. To create a package from a template, open the package manager using "Tools/Manage Packages", go to the "Current Packages" tab and push the "Create (Edit) Package" button. Chose a template from the list that opens and enter a package name (with prefix, if desired). Select "Ok" to let KLayout create a new package based on the template you selected.
The package details can be edited with the "pen" button at the top right of the right details panel. Please specify at least some author information, a license model and a version. If the package needs other packages, the dependencies can be listed in the "Depends on" table. Those packages will be automatically installed together with the new package. The showcase image can be a screen shot that gives some idea what the package will do. The package details are kept in a file called "grain.xml" inside the package folder. You can also edit this file manually. The "grain.xml" is the basic description file for the package.
If the package is a macro or static library package, the macro editor can be used to edit the package files. If the package is a tech package, the technology manager can be used to edit the technology inside the package. To populate the package folder with other files use your favorite editor of KLayout itself for layout files.
Once a package is finished, it needs to be deployed to make it available to other users. Deployment basically means to put it on some public place where others can download the package. For local deployment inside an organisation, this can be a web server or a folder on a file server. KLayout talks WebDAV, so the web server needs to offer WebDAV access. A subversion (SVN) server provides WebDAV by default, so this is a good choice. For the packages themselves, Git or WebDAV/Subversion can be used. You need to specify the protocol in the package URL (see below).
After a package has been made available for download, it needs to be entered in the package index. For local deployment, the index can be a file hosted on a web server or on the file system. The package index location needs to be specified by the KLAYOUT_SALT_MINE environment variable which contains the download URL of the package index file.
For public deployment, the Salt.Mine service (http://sami.klayout.org) is used to register new packages in the package index. By default, KLayout loads the package index from that service, so once your package is registered there, everyone using KLayout will see it.
Public Packages are published on the Salt.Mine server. This is a web service that delivers a packages index with some meta data such as current version, the icon and a brief description. KLayout uses this list to inform users of packages available for installation and available updates. For local deployment, the package index can be served by other ways too. The only requirement is to be accessible by a http, https or file URL.
The basic format of the index is XML with this structure:
<salt-mine>
<salt-grain>
<name>name</name>
<version>Version</version>
<title>Title of the package</title>
<doc>A brief description</doc>
<doc-url>Documentation URL</doc-url>
<url>Download URL</url>
<license>License model</license>
<icon>Icon image: base64-encoded, 64x64 max, PNG preferred</icon>
</salt-grain>
...
<include>URL to include other index files into this one</include>
...
</salt-mine>You can include other repositories - specifically the default one - into a custom XML file. This allows extending the public index with local packages.
When the package manager is opened, KLayout will download the index from http://sami.klayout.org/repository.xml. You can set the KLAYOUT_SALT_MINE environment variable to a different URL which makes KLayout use another dictionary service, i.e. one inside your own organisation. This service can be any HTTP server that delivers a package list in the same format than the Salt.Mine package service. The URL can also be a "file:" scheme URL. In this case, KLayout will download the list from the given file location.
When installing a package, KLayout will simply download the files from the URL given in the package list. KLayout employs the WebDAV protocol to download the files. This protocol is spoken by Subversion and GitHub with the subversion bridge. The latter requires a simple translation of the original Git URL's to obtain the subversion equivalent.
Package URLs are the locations from where KLayout will download the package files. The package data is a hierarchy of files. The package description file ("grain.xml") needs to be located at the root of this hierarchy.
A plain package URL will instruct KLayout to download the package file from the given hierarchy using the WebDAV protocol. You can add "svn+" at the front of the URL to make this specification a little more explicit. These are WebDAV/Subversion URLs:
https://www.klayout.org/example-package svn+https://www.klayout.org/example-package
Git is another option to host packages. In order to use the Git protocol, add "git+" at the front of the URL:
git+https://github.com/klayout/example-package.git
This will make KLayout clone the "example-package" repository and use the default branch for checking out the files. It will expect a file named "grain.xml" at the root of the package file hierarchy.
To use a different branch or tag, specify the tag or branch name in square brackes. For example:
git+https://github.com/klayout/example-package.git[v1.0]
This will use the "v1.0" tag or branch for checking out the files.
It is also possible to have packages in the a subfolder of the repository. To specify the subfolder, separate the subfolder path from the repository URL using "+", like this:
git+https://github.com/klayout/repository.git+klayout/package-data[v1.0]
This will clone the "repository" project and in this project, KLayout will checkout files from "klayout/package-data" and below. This is also the place, where KLayout expects the "grain.xml" file.
Scripts can register an event through Application#on_salt_changed which indicates that packages have been installed or uninstalled.
Packages itself can supply special scripts which are executed after a package was installed or before a package is uninstalled:
Both scripts need to be stored in the same location as "grain.xml" and have to use "lym" format. This is the generic XML script format KLayout employs as an interpreter-agnostic script representation.