Creating Paclets
Wolfram Language paclets are the standard way to extend the Wolfram System with new functionality. Paclets can include Wolfram Language code, documentation, assets and data files, palettes, stylesheets, Wolfram LibraryLink modules and more. Paclets can be shared as a .paclet file or deployed to the Wolfram Cloud.
The PacletTools package provides functions for creating and developing paclets.
| CreatePaclet | create a new paclet within a specified directory |
| PacletDocumentationBuild | build documentation for a paclet |
Use the CreatePaclet function to create the initial content for your paclet. Begin by evaluating the following statements to load PacletTools and create your new paclet:
To view the files in your new paclet in your operating system's file browser application, evaluate the following:
The presence of a PacletInfo.wl file indicates that this directory contains a paclet. PacletInfo files contain the programmatic description of the paclet, in the form of a PacletObject declaration. The contents of the new PacletInfo.wl file will look something like this:
PacletObject[<|
"Name" -> "MyPaclet",
"Version" -> "1.0.0",
"WolframVersion" -> "12.3+",
"Extensions" -> {
{"Kernel", "Root" -> "Kernel", "Context" -> "MyPaclet`"},
{"Documentation"}
}
|>]
This PacletInfo.wl file declares that this paclet is called "MyPaclet", that its version number is "1.0.0" and that it is compatible with versions of the Wolfram System greater than or equal to 12.3. It also declares that MyPaclet extends the system with new "Kernel" (Wolfram Language code) and "Documentation" content.
Note that although the new paclet was created by using CreatePaclet, the system is not yet aware of the paclet:
Later on, you will use PacletInstall to install the finished paclet for use in future sessions, but during development, you can temporarily tell the system about the paclet using PacletDirectoryLoad:
Almost all paclets extend the Wolfram System with new packages. Packages are named collections of Wolfram Language source code. The name of a package must be a valid Wolfram Language context. See "Wolfram Language Packages" for more information about contexts and the structure of packages.
In the PacletInfo.wl file content shown previously, the "Context" property in the "Kernel" extension declares to the system that the source code for the "MyPaclet`" package is provided by this paclet:
{"Kernel", "Root" -> "Kernel", "Context" -> "MyPaclet`"}
When MyPaclet is installed, this declaration makes it possible for users of the paclet to load the source code using Needs["MyPaclet`"].
This is the relationship between paclets and packages in the Wolfram System: MyPaclet is a paclet that extends the system with (among other things) a package called MyPaclet`. Note that the package(s) provided by a paclet (if any) is not required to have the same name as the paclet that provides it, but that is the standard naming convention adopted by the vast majority of paclets that provide packages.
The MyPaclet.wl file created by CreatePaclet contains placeholder content demonstrating the standard structure of a Wolfram Language package file:
BeginPackage["MyPaclet`"]
(* Declare your package's public symbols here. *)
SayHello
Begin["`Private`"]
(* Define your public and private symbols here. *)
SayHello[name_?StringQ] := Print["Hello ", name, "!"]
End[] (* End `Private` *)
EndPackage[]
See "Wolfram Language Packages" for information about standard practices for writing packages.
In addition to extending the system with packages, paclets can also extend the system with new documentation, like this tech note page you are currently reading.
Documentation in the Wolfram System consists of specially prepared notebooks, of which the three most common types are symbol reference pages, guide pages and tech notes. These notebooks are authored using the Documentation Tools palette, and built into their final form using the DocumentationBuild package.
To add documentation to your paclet, begin by opening Documentation Tools by clicking the Palettes ▶ Documentation Tools menu item.
Documentation Tools will automatically add subdirectories to the Documentation directory for storing the different documentation types (note that tech notes live in the Tutorials directory):
The most common type of Wolfram documentation pages are symbol reference pages (also called function reference pages). Symbol reference pages describe the usage and behavior of individual symbols defined by a package.
To create a symbol reference page, click the New Function Page button in the (F)unction tab of the Documentation Tools palette:
Annotated screen capture showing the location of the New Function Page button in the Documentation Tools palette.
Screen capture showing the New Function Page dialog. Enter the name of the new symbol reference page to create it.
Upon clicking OK, Documentation Tools will create a new symbol documentation "authoring" notebook in the Documentation/English/ReferencePages/Symbols/ directory of your paclet. Symbol documentation notebooks contain basic usage descriptions for the symbol, notes on behavior and available function options, links to related documentation pages, and examples. The Documentation Tools palette provides tools for inserting a variety of formatted content into documentation authoring notebooks.
More information about authoring symbol documentation can be found in Authoring Symbol Pages Using Documentation Tools.
Documentation authoring notebooks look different from the finished documentation that is built into the Wolfram System. Authoring notebooks are transformed into so-called "in-product" notebooks via a build process. Paclet documentation can be built using PacletDocumentationBuild:
By default, built paclet documentation is placed in the MyPaclet/build/MyPaclet/Documentation/ directory. The built SayHello.nb documentation can be opened by evaluating:
Once your paclet is ready to be shared, it can be built into a distributable .paclet archive file using PacletBuild:
- It builds the documentation using PacletDocumentationBuild.
- It excludes files from the paclet source directory that are not part of the paclet's declared "extensions".
The Success object returned by PacletBuild includes a manifest of all files included in the built paclet (except the PacletInfo.wl file), as well as their file hashes:
The .paclet file produced by PacletBuild contains the complete content of the paclet. The built paclet can be installed using PacletInstall:
ForceVersionInstall True is required here because our previous call to PacletDirectoryLoad has made a copy of 'MyPaclet' available already in this session, and PacletInstall by default will not install a paclet if a paclet with the same version is already available.
An installed paclet is persistent between Wolfram Language sessions, and is only removed by calling PacletUninstall.
If you want to try using your installed paclet, but you have previously loaded the paclet's source directory in the current session using PacletDirectoryLoad, it is recommended that you start a fresh Wolfram Language session by evaluating Quit[] in your current Wolfram Language session. In the new session, content from the installed paclet is immediately usable; for example, Needs["MyPaclet`"] can be evaluated without first calling PacletDirectoryLoad.
Publishing a paclet to the Wolfram Cloud is a fast and easy way to share your paclet. Before publishing, ensure that your current session is connected to the Wolfram Cloud using CloudConnect:
If you do not have a Wolfram Cloud account, you can sign up for free from the cloud connection prompt, or by visiting www.wolframcloud.com.
To publish to the cloud, copy the .paclet file you created in the previous section to a CloudObject location:
By default, the cloud object will have private permissions: it is only viewable by the cloud account that created it:
To grant permission for another user or group to view the paclet cloud object, use SetPermissions:
To install the paclet locally from the CloudObject, evaluate:
Other users can install the paclet directly from the CloudObject URL:
PacletInstall["https://www.wolframcloud.com/obj/example/MyPaclet-0.0.1.paclet"]
The Wolfram Paclet Repository is a repository of community-contributed paclets that anyone can use and upload to. Paclets published to the Wolfram Paclet Repository are public and can be easily installed by other users of the Wolfram Language.
To publish a paclet to the Wolfram Paclet Repository, consult the official guidelines and instructions, and follow the steps in Publish in the Paclet Repository.