From c99dbebf0a6ead21cdb1dba605965dd84c66850d Mon Sep 17 00:00:00 2001 From: Matthias Koefferlein Date: Mon, 2 Oct 2017 00:25:29 +0200 Subject: [PATCH] Updated package manager doc. --- src/lay/lay/SaltManagerDialog.ui | 6 +- src/lay/lay/doc/about/packages.xml | 129 +++++++++++++++++++++++++---- 2 files changed, 118 insertions(+), 17 deletions(-) diff --git a/src/lay/lay/SaltManagerDialog.ui b/src/lay/lay/SaltManagerDialog.ui index cd998ae45..cf5d59037 100644 --- a/src/lay/lay/SaltManagerDialog.ui +++ b/src/lay/lay/SaltManagerDialog.ui @@ -607,7 +607,7 @@ - Installed Packages + Current Packages @@ -786,8 +786,8 @@ 0 0 - 537 - 284 + 343 + 207 diff --git a/src/lay/lay/doc/about/packages.xml b/src/lay/lay/doc/about/packages.xml index aa9f8c4c6..8457778a7 100644 --- a/src/lay/lay/doc/about/packages.xml +++ b/src/lay/lay/doc/about/packages.xml @@ -50,7 +50,7 @@

- 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 (sami.klayout.org). 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.

+

Installing Packages

+

- 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. +

+ +

+ A filter above the package list allows selecting packages by name. + The right panel shows details about the package currently selected. +

+ +

Updating Packages

+ +

+ 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. +

+ +

Uninstalling Packages

+ +

+ 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. +

+ +

Creating Packages

+ +

+ For package development you can utilize KLayout to initialize and edit the files inside + the package folder or populate the folder manually. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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 public open source deployment, only certain providers are supported. + There is separate documentation covering this topic. +

+ +

+ 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 KLAYOUT_SALT_MINE environment variable in form of + a URL. The basic format of this file 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>
+  ...
+</salt-mine>
+
+ +

+ For public deployment, the "Salt.Mine" service can be used to register and + list new packages in the repository dictionary.

The DNA

@@ -81,12 +180,19 @@

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 - http://sami.klayout.org/repository.xml by default. You can set the KLAYOUT_SALT_MINE - 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. +

+ +

+ When the package manager is opened, KLayout will download this list 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.

@@ -97,9 +203,4 @@ subversion equivalent.

-

- For package development you utilize KLayout to initialize and edit the files inside - the package folder or populate the folder manually. -

-