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

Updated package manager doc.

This commit is contained in:
Matthias Koefferlein 2017-10-02 00:25:29 +02:00
parent 5eb8172c57
commit c99dbebf0a
2 changed files with 118 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/lay/lay/SaltManagerDialog.ui
View File

@ -607,7 +607,7 @@
</widget>
<widget class="QWidget" name="tab">
<attribute name="title">
<string>Installed Packages</string>
<string>Current Packages</string>
</attribute>
<layout class="QVBoxLayout" name="verticalLayout_3">
<item>
@ -786,8 +786,8 @@
<rect>
<x>0</x>
<y>0</y>
<width>537</width>
<height>284</height>
<width>343</width>
<height>207</height>
</rect>
</property>
<layout class="QGridLayout" name="gridLayout_2">

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

@ -50,7 +50,7 @@
</p>
<p>
The key component for the package repository is the "Salt.Mine" package repository
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
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
@ -59,11 +59,110 @@
account for confirmation.
</p>
<h2>Installing Packages</h2>
<p>
Currently, GitHub is supported as a host site. As a package author you'll need a GitHub
account and open a project for your package there. GitHub acts both as a code repository
for your development and as a deployment platform. KLayout can download packages directly
from your GitHub project's master or a release tag.
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.
</p>
<p>
A filter above the package list allows selecting packages by name.
The right panel shows details about the package currently selected.
</p>
<h2>Updating Packages</h2>
<p>
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.
</p>
<h2>Uninstalling Packages</h2>
<p>
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.
</p>
<h2>Creating Packages</h2>
<p>
For package development you can utilize KLayout to initialize and edit the files inside
the package folder or populate the folder manually.
</p>
<p>
KLayout offers to initialize new packages from a template. You can modify the template
package later.
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.
</p>
<p>
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 screenshot 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.
</p>
<p>
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.
</p>
<p>
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 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>
@ -81,12 +180,19 @@
<p>
Packages are published on the Salt.Mine server. This is a web service that delivers a
complete list of packages plus a little meta data such as current version, the icon
and a brief description. KLayout will download this list from
<tt>http://sami.klayout.org/repository.xml</tt> by default. You can set the <tt>KLAYOUT_SALT_MINE</tt>
environment variable to a different URL which makes KLayout use another repository
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.
</p>
<p>
@ -97,9 +203,4 @@
subversion equivalent.
</p>
<p>
For package development you utilize KLayout to initialize and edit the files inside
the package folder or populate the folder manually.
</p>
</doc>