Earlier this year we added a feature to our popular IBM Swift Sandbox enabling developers to run sample packages from the IBM Swift Package Catalog. Now you can create your own samples / samples of your own packages to run in the sandbox. This will enable developers around the world to try your Swift package as they experiment with Swift on the server, directly from the sandbox.
This tutorial walks through how to create a sample directly from the IBM Swift Package Catalog in 5 easy steps.
We will create a sample project, create a file, populate the file, and then test it in the Sandbox. The fifth and final step is just for fun — sharing your new skill with the #SwiftLang community.
HOW TO INCLUDE A SAMPLE IN THE IBM SWIFT PACKAGE CATALOG
In order for a developer to enable the “Try in Sandbox” button and have their sample available for the world to use there are a couple of steps that must be completed first.
CREATE A SAMPLE PROJECT
First, we’ll create a separate GitHub repo project where our sample will exist. Inside of this project we need to implement the code that we wish to use to demonstrate the functionality of our package. This is done by creating a Swift project that can compiled and run on the Sandbox’s Linux runtime.
Note: That there are certain limitations imposed by the Sandbox that might constrain the types of samples you will build, namely, it restricts executions to 5 seconds and does not allow network access.
The following example is taken from the Helium Logger Sample project: https://github.com/IBM-Swift/HeliumLogger-Sample
In the Package.swift, the parent HeliumLogger package is defined for inclusion in this project as a dependency.
In the main.swift file, the sample imports HeliumLogger and then uses the HeliumLogger class to demonstrate some of the package’s functionality. All samples should contain both ample comments and provide visual text output to help explain to the user what’s happening.
CREATE THE .swift-sample FILE
Now that we have created a functioning sample project, our next step is to link the package we want to showcase to our new sample project.
In the package that we want to showcase (not in the sample package), we need to add a file named .swift-sample to the top level directory of the package.
POPULATE THE .swift-sample FILE
When we are populating the .swift-sample file we have the ability to include one or more samples project references. The way to include a single sample for our main project that we are showcasing is to add a single JSON object to the .swift-sample file. For multiple samples, we just define this as an JSON array of sample objects.
Just to give a short explanation about the fields in the above JSON examples.
type: Currently, this can only be “sandbox”. This field may be used for other, yet to be defined, services in the future.
title: This is what will be displayed as the title of the “Try in Sandbox” sample selection.
description: This will be displayed below the title to give some extended information about the sample. This could be used to explain what the differences are between multiple samples.
swiftversion: This is what version of Swift we would like the IBM Swift Sandbox to try to use for our sample. If that version is not available, then the latest Swift version is used.
giturl: This is the GitHub clone URL for our sample project. This is so that we have a reference to our sample project inside of our main project. This also allows us to name the sample project whatever we would like.
gittag: This is the tag of our sample project what we want the IBM Swift Sandbox to clone. This allows us to have an old sample for an older version of our main project and a new sample for a newer version of our main project.
WHAT HAPPENS NEXT
At this point, we have created the sample project with the ability to run the package we want to showcase, and added a .swift-sample to our showcase project with the information about our sample(s). All we need to do now is make sure our main package project is available in the IBM Swift Package Catalog. If the package is not currently available in the IBM Swift Package Catalog, you can submit it at the top of the Catalog’s webpage using its GitHub URL.
When a user locates and navigates to the package’s detail page, The catalog will check for an updated .swift-sample file. If found, a new “Try in Sandbox” button is shown, enabling the user to have an opportunity to really see how the package works, and explore further with the user’s own customizations.
By providing samples for your package, you are helping potential users to quickly understand how to use your package. You may want to inform your users of this capability in your project’s README file, or send out custom notifications or tweets to those interested. Your users may want to fork and customize your provided samples exploring more use cases. You should encourage this behavior by accepting Issues and/or Pull Requests of new samples within your main package’s project. This gives you, the package owner a chance to review the proposed sample before deciding to make it part of the samples exposed within your package in the IBM Package Catalog.