Wolfram Language Paclet Repository
Community-contributed installable additions to the Wolfram Language
Creating Paclets for the Wolfram Language Paclet Repository
Creating Paclets for the Wolfram Language Paclet Repository
This provides basic instructions and guidelines for creating a paclet in preparation for publication in the Wolfram Language Paclet Repository.
The Wolfram Language Paclet Repository is a growing collection of community-contributed paclets that users can install and use on their own systems. Paclets are units of Wolfram functionality, packaged up in a way that allows them to be discovered, installed, updated and integrated seamlessly into the Wolfram environment. Paclets can contain many types of content, including Wolfram Language files, LibraryLink libraries, front end resources like palettes and stylesheets, documentation notebooks, etc.
We encourage submissions of all kinds, with only a few guidelines that we ask to be followed. Documentation for paclet-related functions can be found here, and a detailed reference for paclet developers is here.
Publisher ID
Publisher ID
What Is a Publisher ID?
What Is a Publisher ID?
A publisher ID is an identifier used for publishing content in the Wolfram Language Paclet Repository and in other repositories in the Wolfram Resource System. The publisher of a paclet controls the paclet. Each publisher ID has one or more authorized users who can update, delete and modify paclets published by that publisher ID.
Getting a Publisher ID
Getting a Publisher ID
If you are creating a paclet from your own work, you should probably use your own PublisherID. You can get an automatically assigned personal publisher ID here or request a custom publisher ID here.
If you are creating a paclet for an organization, you should probably use an organizational publisher ID, like "Wolfram". You can request a custom publisher ID here.
Using a Publisher ID
Using a Publisher ID
In[1]:=
$PublisherID
Out[1]=
JaneDeveloper
If you are authorized to use multiple publisher IDs, you can select which one to use by setting $PublisherID.
$PublisherID="ACMECorp";
Publisher ID–Based Names
Publisher ID–Based Names
The publisher ID is used to create a dedicated namespace for the paclet, its symbols and other named resources.
Paclets published in the Wolfram Paclet Repository have paclet names of the form:
In[2]:=
PacletObject["PublisherID/PacletBaseName"]
In[3]:=
ResourceObject["PublisherID/PacletBaseName"]
Contexts created within your paclets should have the form:
In[4]:=
"PublisherID`PacletBaseName`"
By convention, user-accessible symbols and functions in paclets have the form:
In[4]:=
PublisherID`PacletBaseName`SymbolName
The value of $PublisherID is included when a paclet is submitted for publication in the paclet repository and it must match the prefix in the paclet name and contexts.
Definition Notebook
Definition Notebook
The Paclet Resource Definition Notebook is a form-like notebook that provides an interface for developing and managing a paclet. It provides a summary of the content in a paclet as well as fields for defining metadata. The paclet definition notebook headers provide tools for validating, building, deploying and publishing paclets.
Throughout the definition notebook, information buttons like the one below provide details about the appropriate content for each field.
Sections
Sections
The top of the definition notebook contains cells for defining the name and description of the paclet followed by four main sections: “Paclet”, “Web Content”, “Examples” and “Source and Additional Information”.
Paclet
Paclet
The paclet section contains two parts: a paclet directory selector, which determines where the paclet defined by the definition notebook is located, and a non-editable manifest, which provides a summary of the paclet file content as well as locations for validation hints associated with those files.
Web Content
Web Content
The web content section defines the material that will appear on the paclet’s homepage when it is deployed to the cloud or published in the paclet repository. This content is used only for the website and is not contained in the paclet when it is built and distributed.
Examples
Examples
The examples section provides an opportunity to show a high-level overview of the features of the paclet. It should attempt to give users a brief idea of the paclet’s primary use cases. Including too many examples in the definition notebook can cause poor performance of the website generation and display during paclet deployment and publication. Comprehensive examples showing specifics of each function and symbol should be included in the documentation pages.
Source & Additional Information
Source & Additional Information
This section contains several fields for defining metadata. This metadata will help people discover your paclet in the repository and determine if it is appropriate for their use.
Specify environments with which your paclet is or is not compatible and disclose any external effects your paclet can take on a user’s systems and accounts. Providing this information will allows users to have more confidence in your paclet before installing it.
Buttons
Buttons
The header of the definition notebook contains a collection of buttons for developing and distributing a paclet.
The Tools button opens a toolbar with addition buttons for working in the definition notebook itself, as well as Documentation Tools, which launches a palette for writing paclet documentation.
The Check drop-down menu contains buttons that run validators that examine your paclet and report errors and suggestions wherever possible.
The Build drop-down menu builds the paclet, including the documentation into a format ready for distribution.
The Deploy drop-down menu allows you to make personal deployments of the paclet either on your computer or in your Wolfram Cloud account.
The Submit to Repository button submits the paclet for publication in the public Wolfram Language Paclet Repository.
Definition Notebook and PacletInfo File
Definition Notebook and PacletInfo File
The definition notebook and PacletInfo file overlap in content, but serve two different primary purposes.
The PacletInfo file contains information required for the building, installation and integration of paclets into a Wolfram Language system. It is included in, and remains a functioning part of the built and distributed paclet.
The definition notebook is a tool for development and administration of a paclet. It is not included in or used by the built and distributed paclet.
Fields that are common between both the PacletInfo file and the definition notebook (i.e. “Name” and “Description”) should be identical in both places. Using the Check button in the definition notebook will ensure all common values are synchronized.
Converting Existing Paclets
Converting Existing Paclets
The definition notebook system contains a convenient tool for converting existing paclets into a form suitable for publication in the paclet repository. The conversion adds publisher ID prefixes throughout the most commonly required places in the paclet. The following procedure shows how to convert an existing paclet. Before starting, you must have a publisher ID.
In[1]:=
|
Out[1]=
NotebookObject
 | Paclet Resource | Create Definition Notebook |
In the resulting dialog enter the paclet directory. This is the directory that contains your PacletInfo file:
A new dialog offers to convert the paclet based on your publisher ID. You can choose to leave the existing paclet directory intact and perform the conversion on a copy of the paclet directory.
Click OK to begin the conversion. The converted paclet directory will be added next to the original paclet directory. A definition notebook will automatically be generated and saved next to the converted paclet directory in your file system. When the conversion is complete use the Check →All button in the definition notebook to find any remaining issues.
Creating New Paclets
Creating New Paclets
The definition notebook system contains a convenient tool for creating a new paclet directory to start developing a paclet suitable for publication in the paclet repository. You must have a publisher ID to submit your paclet to the repository, but you can develop it and use it locally without an id.
Choose a new path or an empty directory. The dialog will add the following fields for defining basic paclet metadata:
Click OK to create a new paclet directory along with a definition notebook. The new paclet will contain a Kernel directory with a single .wl file containing some placeholder content:
Modify the SayHello placeholder content to begin developing your paclet.
Paclet Development
Paclet Development
Documentation on developing paclets either for the Paclet Repository or for any other use can be found in PacletTools.
Updating Published Paclets
Updating Published Paclets
Publishing updates to your paclet using the definition notebook is easy. After making the desired changes to the paclet and the documentation, use Check and Build to prepare your paclet. Then, click the Submit to Repository button. If needed, a dialog will help you set an appropriate version number for the update.
Semantic versioning
Semantic versioning
The paclet repository strongly encourages the use of semantic versioning standards. Version numbers should have the form XX.YY.ZZ, where increases to the XX digits represents a major, potentially incompatible change; increases to the YY digits represent a minor or incremental change; and changes to the ZZ digits represent a bug fix or patch.
Continuous Integration and Continuous Deployment
Continuous Integration and Continuous Deployment
A continuous integration workflow for GitHub is in development and will be soon be available for automating validation, building, deployment and publication of paclets. A development version of the tools for defining actions is available as a paclet from the paclet repository.
