Let there be work, bread, water and salt for all.
-- Nelson Mandela
"Salt"? Without salt, food is often a little tasteless. By adding salt, you make things interesting. "Salt" is KLayout's package manager, "Salt.Mine" is a package index service where new packages are registered, so users will see those packages in their package manager.
Quick links:
The easiest way to create packages is to let KLayout instantiate one from a template. Choose "Manage Packages" from the "Tools" menu. Go to the "Current Packages" page for a list of installed packages. Click on "Create (Edit) Packages" in the bottom right corner. Pick a template you want to start with (for example "Ruby Macro") and chose a package name. The name can be anything, like "mypackage", but it needs to be unique. Hit "Ok" the let KLayout initialize the package. The new package appears in the list of current packages.
Next thing is to supply some basic information. Select the new package if not already selected and press the "Pen" (Edit Package Details) button in the upper right corner. A package should have at least:
Not required but useful entries are:
Your new package comes with some files already. The file tree in the details page depicts the files that are installed with the package. The templates already come with a fake documentation page. The "grain.xml" is the badge of the package - this is the file that makes a directory a package and holds the package details. Depending on the template, some more folders may be there - like "macros" for a Ruby macro package. These folders are already populated.
Get creative now. Use your favorite editor to edit the documentation pages. Edit macros in KLayout macro development IDE - you'll find "Ruby macros" packages in a new section on the "Ruby" tab. Use the technology editor to edit technology packages. Feed the "libraries" folder of static library packages with layout files. Whatever you want. A package can even combine multiple aspects such as technologies, libraries and DRC scripts.
But wait - what if you damage something? A package is just a folder initially. So unless you create backups there is no way back. Version control is required. KLayout does not come with a built-in client for a versioning system, but there are many choices. Two important ones are easy to use with KLayout: Subversion (SVN) and Git. I assume now that you know how to create a SVN/Git repository or you have the social skills to persuade your favorite geek to set one up for you. If you managed that, the next steps will feel very easy.
If you plan to go public with your project, you can skip the geek part, just go to GitHub and create a project there (preferably with the same name than you package). You'll use Git on GibHub then. This is the only option currently for publishing projects on Salt.Mine.
The basic problem is that there is a non-versioned directory which you need to attach to a versioning system. The local directory is the directory named after your package below the "salt" folder. You see it in the package details as the root of the "Installed files". If your project goes to GitHub, you can follow their nice How-to article for connecting an existing folder (the package subfolder in your case) with a Git project.
If you don't want to publish your package but keep it inside your organisation you need to attach to your local server. It's even possible to deploy (publish) packages that way to other users inside your organisation. The About Packages manual page explains how.
Regularly commit/push to create new snapshots of your work. Use a meaningful commit message. You can't spoil the soup if you make this a habit - in the worst case, pull an older version and start over again. If you're not familiar with Subversion or Git yourself, remember your social skills.
You're not creating a package for your own - packages are supposed to be served. The final step is to deploy a package. Deployment is the sweet part - after deployment all you need to do is to wait and collect the praises.
This is about public releases from GitHub and into the Salt.Mine index. Local deployment is another topic which is covered below.
There are basically two ways to serve a release. One is to keep the release name the same and increment the version. This approach is easy to implement, but you cannot easily revert back to a previous release. Plus, with Salt.Mine, there is a time span in which the public package index and the package are out of sync. This may become an issue for users that try to install a package during this period. The release names are technically "tags". GitHub creates tags when you use their release feature. You can call the tag for a release "released" (or something alike) and move this tag forward whenever you have a new release. Then, the package details are the only way to tell the version of the package and there can only be one released version.
The other option is to create a new release name for each release. This way you accumulate releases in your repository, but there is nothing wrong with this. But you'll need to point Salt.Mine to the new release. That's an additional step, but it's pretty painless and helps Salt.Mine to keep synchronized with your releases. In this model, you create a new release tag with every release, preferably with the released version as a name.
Basically, having a release tag is all you need to publish a GitHub-hosted package to the world on Salt.Mine. Except one more thing: you'll need a mail account. The mail account is basically the owner of a package and you'll need it to manage your package. You please pick a mail account that has a future life and which you have control over. No throw-away mail accounts or student accounts. Your mail address won't become visible to others. You'll need the mail account for re-registration of a new package release or package revokation, so be sure you remember it.
A package needs to be registered at Salt.Mine at least once. Registration requires a GitHub project URL and the mail account for confirmation. On the Salt.Mine main page, chose "Register Package" to open the package registration form. The most important information is the package download URL. This is the source where KLayout will download the packages from. The actual URL needs to be formed from the project URL and the tag name.
The project URL can be found in the "Clone or download" box on the GitHub project page. It's an URL looking like https://github.com/myself/packagename.git ("myself" will be your user name on GitHub and "packagename" the name of your project). To this URL add "/tags/releasename" where "releasename" is the name of your release (for example the version). Example:
https://github.com/klayoutmatthias/qrcode_pcell.git/tags/1.0
Once you submit the request, Salt.Mine will send a mail to the account given on the registration page and ask for confirmation of the request. Once the confirmation is done, the new package will be listed on Salt.Mine and the package becomes visible to all KLayout users.
If you created a new release of an existing package with a new tag name, you just re-register the package with the new URL. Package re-registration uses the same form than package registration. Enter the new URL and the original mail address. In this case, the package ownership is recognized and the original package is replaced by the new version.