diff --git a/src/lay/doc/about/about_libraries.xml b/src/lay/doc/about/about_libraries.xml index dbab64710..a6b37ce0f 100644 --- a/src/lay/doc/about/about_libraries.xml +++ b/src/lay/doc/about/about_libraries.xml @@ -59,8 +59,10 @@

- Libraries are loaded on startup and reside in memory while KLayout is running. Therefore, in - order to update a library when the content has changed, KLayout must be restarted. + 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 for details + about packages.

diff --git a/src/lay/doc/about/about_pcells.xml b/src/lay/doc/about/about_pcells.xml index 909c27220..bcbcf0341 100644 --- a/src/lay/doc/about/about_pcells.xml +++ b/src/lay/doc/about/about_pcells.xml @@ -60,11 +60,15 @@

PCell's are usually packed in libraries. PCell libraries can be provided as shared objects/DLL's (in C++) or as Ruby scripts. Because PCell code is only executed if - required, performance is not absolutely mandatory. A Ruby implementation + required, performance usally is not the main objective. A Ruby implementation will therefore be sufficient in most cases and - is a much easier to provide. The Ruby approach also benefits from KLayout's integrated development + is a much easier to maintain. The Ruby approach also benefits from KLayout's integrated development environment.

+

+ For an introduction into PCell programming with Ruby, see . +

+ diff --git a/src/lay/doc/about/ide_browser_toolbar.png b/src/lay/doc/about/ide_browser_toolbar.png index 0431e2989..078125b0a 100644 Binary files a/src/lay/doc/about/ide_browser_toolbar.png and b/src/lay/doc/about/ide_browser_toolbar.png differ diff --git a/src/lay/doc/about/ide_console.png b/src/lay/doc/about/ide_console.png index cd5252284..8de2dba81 100644 Binary files a/src/lay/doc/about/ide_console.png and b/src/lay/doc/about/ide_console.png differ diff --git a/src/lay/doc/about/ide_debugging_snapshot.png b/src/lay/doc/about/ide_debugging_snapshot.png index df5581ead..cb089f2b0 100644 Binary files a/src/lay/doc/about/ide_debugging_snapshot.png and b/src/lay/doc/about/ide_debugging_snapshot.png differ diff --git a/src/lay/doc/about/ide_editor_toolbar.png b/src/lay/doc/about/ide_editor_toolbar.png index 603071b82..3c73bed5e 100644 Binary files a/src/lay/doc/about/ide_editor_toolbar.png and b/src/lay/doc/about/ide_editor_toolbar.png differ diff --git a/src/lay/doc/about/ide_py_debugging_snapshot.png b/src/lay/doc/about/ide_py_debugging_snapshot.png index 62a502903..107f26bae 100644 Binary files a/src/lay/doc/about/ide_py_debugging_snapshot.png and b/src/lay/doc/about/ide_py_debugging_snapshot.png differ diff --git a/src/lay/doc/about/ide_snapshot.png b/src/lay/doc/about/ide_snapshot.png index b6de1dd59..32a23ad30 100644 Binary files a/src/lay/doc/about/ide_snapshot.png and b/src/lay/doc/about/ide_snapshot.png differ diff --git a/src/lay/doc/about/index.xml b/src/lay/doc/about/index.xml index 6b1e48e5c..f586a54a4 100644 --- a/src/lay/doc/about/index.xml +++ b/src/lay/doc/about/index.xml @@ -24,6 +24,7 @@ + diff --git a/src/lay/doc/about/macro_editor.xml b/src/lay/doc/about/macro_editor.xml index 05a87d774..e0ad2060e 100644 --- a/src/lay/doc/about/macro_editor.xml +++ b/src/lay/doc/about/macro_editor.xml @@ -30,6 +30,12 @@ menu extension.

+

+ Macros can be technology specific. This means, they are packaged with a technology and are associated + with the technology in the user interface: if they provide a menu item, this item will only become + visible when the respective technology is active. +

+

KLayout also offers an integrated development environment (IDE) that allows editing and debugging of Ruby and Python scripts. It offers a simple debugger with the ability to set breakpoints and @@ -70,17 +76,31 @@ The "macros" or "pymacros" folders in KLayout's user specific application folder. On Unix that is "~/.klayout/macros". This is the "local" repository. Any user can store his or her own macros here. +

  • + Plain Ruby or Python files can be kept inside "ruby" and "python" directories next to "macros" and "pymacros". In + contrast to "macros" and "pymacros", the locations of "ruby" and "python" paths are added to the Ruby or Python + search paths. This makes those folders useful for keeping plain Ruby or Python libraries. Generic ".lym" files cannot + reside there and those locations are not scanned for autorun macros. +
  • In addition, further repositories can be given on the command line with the "-j" option. This allows adding development repositories which are under configuration management and contain the latest code for the macros. Those repositories are called "project" repositories.
    • +
  • + Technology folders: each technology folder can carry a "macros" or "pymacros" subfolder where technology-specific + macros are kept. See for details about technologies. +
    • +
  • + Macros can be kept in packages and installed from a remote repository. See for + details about packages. +

    • The macro IDE will store Python and Ruby macros separately in "macros" and "pymacros" for easier management, but technically these folders are equivalent. KLayout will automatically derive the interpreter - from the context stored in ".lym" files or the file extension (".rb" or ".py"). + from the context stored in ".lym" files or the file extension (".rb" or ".py").

    diff --git a/src/lay/doc/about/packages.xml b/src/lay/doc/about/packages.xml new file mode 100644 index 000000000..89ffea698 --- /dev/null +++ b/src/lay/doc/about/packages.xml @@ -0,0 +1,105 @@ + + + + + + About Packages + Packages Manager + Packages + Salt + +

    + "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: +

    + +
      +
    • Ruby or Python macros
      • +
    • DRC runsets
      • +
    • Technologies
      • +
    • Fonts for the Basic.TEXT PCell
      • +
    • Static layout libraries
      • +
    • PCell libraries
      • +
    • Code libraries for Ruby and Python
      • +
    • Binary extensions
      • +
    + +

    + 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. + The choice of the prefix is entirely up to you. You can use a domain name that is owned by + yourself for example. +

    + +

    + 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 the package repository 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 + 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. +

    + +

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

    + +

    The DNA

    + +

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

    + +

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

    + +

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

    + +

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

    + + diff --git a/src/lay/doc/about/technology_manager.xml b/src/lay/doc/about/technology_manager.xml index 89398081c..59a440a28 100644 --- a/src/lay/doc/about/technology_manager.xml +++ b/src/lay/doc/about/technology_manager.xml @@ -94,9 +94,8 @@

    - Macros and DRC scripts associated with a technology are shown in the technology manager, but - cannot be edited there. The right place to edit, run or debug macros or DRC script is the - macro development environment. To open the macro development environment choose "Macros/Macro Development". + Macros and DRC scripts associated with a technology are shown in the technology manager. To edit + or debug scripts of macros, use the macro development environment ("Macros/Macro Development"). If a technology has a macros or DRC scripts folder, the macro or DRC scripts tree in the development environment will show a corresponding top-level branch for that technology.

    diff --git a/src/lay/layHelpResources.qrc b/src/lay/layHelpResources.qrc index abad5f0fc..b33622559 100644 --- a/src/lay/layHelpResources.qrc +++ b/src/lay/layHelpResources.qrc @@ -134,6 +134,7 @@ doc/about/drc_ref_layer.xml doc/about/drc_ref_source.xml doc/about/drc_ref_global.xml + doc/about/packages.xml doc/manual/adjust_origin.xml