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

Updated doc.

This commit is contained in:
Matthias Koefferlein 2017-10-02 23:17:19 +02:00
parent c99dbebf0a
commit e8a29ac612
1 changed files with 13 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
src/lay/lay/doc/about/packages.xml
View File

@ -51,7 +51,7 @@
<p>
The key component for public package deployment is the "Salt.Mine" package repository
service (<tt>sami.klayout.org</tt>). It is a web service that maintains a package list. It
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
@ -98,8 +98,8 @@
</p>
<p>
KLayout offers to initialize new packages from a template. You can modify the template
package later.
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
@ -112,7 +112,7 @@
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 screenshot that gives
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
@ -134,73 +134,25 @@
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 public open source deployment, only certain providers are supported.
There is separate documentation covering this topic.
</p>
<p>
After a package has been made available for download, it needs to be entered
in the dictionary. For local deployment, the dictionary can be a file hosted
on a web server or on the file system. The dictionary's location must be
specified by the <tt>KLAYOUT_SALT_MINE</tt> environment variable in form of
a URL. The basic format of this file is XML with this structure:
</p>
<pre>&lt;salt-mine&gt;
&lt;salt-grain&gt;
&lt;name&gt;name&lt;/name&gt;
&lt;version&gt;Version&lt;/version&gt;
&lt;title&gt;Title of the package&lt;/title&gt;
&lt;doc&gt;A brief description&lt;/doc&gt;
&lt;doc_url&gt;Documentation URL&lt;/doc_url&gt;
&lt;url&gt;Download URL&lt;/url&gt;
&lt;license&gt;License model&lt;/license&gt;
&lt;icon&gt;Icon image: base64-encoded, 64x64 max, PNG preferred&lt;/icon&gt;
&lt;/salt-grain&gt;
...
&lt;/salt-mine&gt;
</pre>
<p>
For public deployment, the "Salt.Mine" service can be used to register and
list new packages in the repository dictionary.
</p>
<h2>The DNA</h2>
<p>
Technically, packages are folders stored below the "salt" folder within KLayout's home
path. Prefixed packages are kept in sub-folders named after the prefix. Each package
directory contains a description file called "grain.xml" and the files that make up the
package. For Ruby macros, for example, the package folder will contain a "macros"
sub-folder. Basically, packages do not require to be of a specific kind - they can
provide technology information, DRC scripts and macros in the same package. In this
example, the will be a "tech", "drc" and "macros" sub-folder with the corresponding
files. KLayout will scan the package folders for useful files and load them automatically.
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 <tt>KLAYOUT_SALT_MINE</tt> environment variable which contains the
download URL of the package index file.
</p>
<p>
Packages are published on the Salt.Mine server. This is a web service that delivers a
dictionary of packages 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.
</p>
<p>
When the package manager is opened, KLayout will download this list from
<tt>http://sami.klayout.org/repository.xml</tt>. You can set the <tt>KLAYOUT_SALT_MINE</tt>
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.
For public deployment, the <a href="http://sami.klayout.org">Salt.Mine Service</a> 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.
</p>
<p>
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.
There is separate documentation provided for details about the development and deployment
process.
</p>
</doc>