This is a community project to produce useful documentation for PacletInfo.m. Feel free to edit and improve this answer.
While the Paclet Manager is loaded from .mx files, its plain text .m sources are also available. Much of the information in this post comes from the comments in those source files. See SystemOpen@Lookup[PacletInformation["PacletManager"], "Location"], especially Extension.m and Paclet.m.
Some other information comes from PacletInfo.m files that come with Mathematica:
paclets = Import[#, "Package"] & /@ FileNames["PacletInfo.m", $InstallationDirectory, Infinity];
as well as the GitLink package.
Introduction
Paclets are a format and distribution mechanism for packages or other resources that can extend Mathematica. The paclet is described by the PacletInfo.m file. This file is used by the PacletManager, which is built into the Wolfram Language.
When would a Mathematica user want to create a PacletInfo.m file?
This is generally useful when building packages or applications. Having this file allows integrating documentation into the Documentation Center, or bundling the package into a .paclet file and installing it with PacletInstall. The file is also recognized in applications installed into $UserBaseDirectory/Applications or $BaseDirectory/Applications manually (the usual way) and not using PacletInstall.
In addition to Paclets installed into a base directory, the PacletDirectoryAdd command can be used to add a directory containing paclets to the PacletManager so that it is recognized by the Mathematica FrontEnd and Needs. This allows a paclet or a library of multiple paclets to reside anywhere, such as a network drive where it can be accessed by multiple users.
Todd Gayley gave a presentation about paclets at Wolfram Technology conference 2019.
Example
A sample PacletInfo.m file from GitLink:
Paclet[
Name -> "GitLink",
Version -> "2100.0",
MathematicaVersion -> "10.1+",
Root -> ".",
Internal -> True,
Extensions ->
{
{"Kernel", Root -> ".", Context -> "GitLink`"},
{"Documentation", Language -> "English"},
{"LibraryLink"}
}
]
Note: GitLink is eventually going to become part of Mathematica. The Internal flag may be related to this and may not be appropriate for user packages.
Settings
These are some of the settings that can be given in PacletInfo files. See the default values using
Normal[PacletManager`Paclet`Private`$piDefaults]
The following should generally be present in any PacletInfo file:
Name, paclet name. This can be used to refer to the paclet, e.g. PacletFind["name"] or PacletUpdate["name"].
Version, paclet version. Must be up to five .-separated numbers. If multiple versions of a paclet are installed, it is always the latest one that will be used.
This value is parsed as PadRight[ToExpression@StringSplit[version, "."], 5].
The following can affect whether the paclet may be loaded:
MathematicaVersion (deprecated) or WolframVersion (current since M10), minimum compatible Mathematica version, e.g. "10+" or "10.0.2+". The paclet will not load in incompatible versions. As of M11.0, it defaults to "10+".
While the MathematicaVersion form is deprecated, using MathematicaVersion -> "10+" allows Mathematica 9 to correctly identify a paclet as incompatible. M9 doesn't understand WolframVersion.
SystemID, compatible system types. Can be a string, a list of strings, or All. See $SystemID for possible values. Defaults to All, and should be omitted unless your package is only compatible with certain operating systems.
Other settings:
Root, probably the paclet root relative to PacletInfo.m. Not tested yet.
Loading, can be Manual, Automatic, or "Startup". Defaults to Manual, i.e. the package can be loaded with Needs as usual. Automatic is allowed only when the Symbols argument of the Kernel extension is set (see below). "Startup" causes the package to load at kernel startup.
This setting will be exposed in the Documentation Center (see below) and can be changed by the user.
Warning: Be careful if the package does more than issue definitions upon loading. Some operations do not work during kernel initialization and may even lock up the kernel.
Internal, can be True/False, ???
Qualifier, have seen values like $SystemID, ???
Paclets that provide the Documentation extension will be listed in the Documentation Center under guide/InstalledAddOns.
The following metadata will be listed for each package/paclet on that page:
Creator, author name.
Description, description.
Publisher, publisher name.
Thumbnail, relative path to an image file. Will be used as the package icon. Should be 46 by 46 pixels.
Warning: There are some problems with the thumbnail retrieval. Rescaling to 46×46 fails (small bug) and using a thumbnail causes high CPU usage in M11 while the add-ons list is open (but not in M10.x).
URL, package homepage.
Other metadata:
These can be retrieved for installed paclets using PacletInformation["name"]
BuildNumber, Category, Copyright, License, Support.
Extensions
The Extensions setting contains a list of extensions, each in the form
{"ExtensionName", "Argument1" -> Value1, "Argument2" -> Value2, ...}
The possible extensions and their arguments are below.
Application
Seems to work in a similar way to Kernel. Not sure what the difference is. At this moment I believe that one can (perhaps should) always use Kernel instead.
Arguments:
Root, defaults to "." (same as Kernel extension)Context
AutoCompletionData
???
Arguments:
Hints: See PacletFind["EntityFramework"]
ChannelFramework
???
Hints: See PacletFind["DemoChannels"] for the implementation of the Demo:OneLiner channel which is shown in ChannelListen -> Applications -> Chat.
Documentation
Fully documented in the Workbench Help.
Used to integrate documentation into the Documentation Center.
Will cause the application to show up in the auto-generated application list in the Documentation Center at guide/InstalledAddOns.
Arguments:
Language, defaults to AllRoot, defaults to "Documentation"Context, rarely needed, use same argument in Kernel extension insteadMainPageLinkBaseResources
Multiple instances of the Documentation extension can be used in the same PacletInfo file. For example, if multiple languages are supported there should be one extension for each language. For an example, see the Parallel paclet in AddOns/Applications.
The LinkBase argument is needed only in cases where documentation is stored in a different paclet from the code*. For an example, see the Parallel paclet in AddOns/Applications which links to the ParallelTools paclet.
The Resources should never need to be used by outside developers of paclets used in version 7+*.
FrontEnd
Will cause subdirectories within the FrontEnd to be handled, e.g. FrontEnd/Palettes, FrontEnd/StyleSheets, FrontEnd/SystemResources, FrontEnd/TextResources. These items will be recognized by the Front End, e.g. palettes will show up in the Palettes menu.
Arguments:
References:
JLink
Will cause .jar files within the root ("Java" by default) to be added to the classpath.
Arguments:
Root, defaults to "Java"
WolframVersion
SystemID
Kernel
Makes the package loadable by Needs.
Arguments:
Root, defaults to "." for compatibility but "Kernel" is also typical. FindFile resolves the specified context to this location during the first stage of its name resolution. See also https://mathematica.stackexchange.com/q/133242/12.
Context, package context or list of contexts. Used by FindFile. Also causes >> documentation links to be added to usage messages when documentation is present.
Symbols, a list of symbols that will trigger autoloading if Loading -> Automatic is set. It is required for Loading -> Automatic to be a valid setting. Similar to DeclarePackage. Symbols can be given with full context, e.g. Symbols -> {"MyPack`MyFun1", "MyPack`MyFun2"}.
WolframVersion
SystemID
HiddenImport
LibraryLink
Arguments:
Will cause shared libraries within LibraryResources/$SystemID to be found by FindLibrary.
Path
???
Arguments:
Base
Root
WolframVersion
SystemID
Resource
The Resource extension can be used to create new extensions that are managed by the PacletManager and can be located using PacletResources or PacletResource. These functions cull the resources by SystemID, Wolfram Language version and Language, providing a system-independent method to manage arbitrary files that paclets depend on.
To use the resource in a package, use PacletResource to retrieve the path to the resource, then use that path in the package functions as appropriate.
An example is the MachineLearning paclet in SystemFiles\Components. It provides a number of system-specific libraries used by the component, and demonstrates how to use aliases for the resources.
MachineLearning defines a "KenLM" resource. To get the path to the system-appropriate resource, use PacletResource["MachineLearning", "KenLM"]. This returns "C:\\Program Files\\Wolfram \
Research\\Mathematica\\11.0\\SystemFiles\\Components\\MachineLearning\
\\Resources\\Binaries\\Windows-x86-64\\lmplz.exe" on a 64-bit Windows machine.
To find all paclets with a "Libraries" resource, use PacletResources["Resource", "Libraries"]. This returns two paclets and resource paths: {{Paclet["Cryptography","1.0",<>],{"C:\\Program Files\\Wolfram Research\\Mathematica\\11.0\\SystemFiles\\Components\\Cryptography\\Resources\\Libraries"}},{Paclet["MachineLearning","1.0.0",<>],{"C:\\Program Files\\Wolfram Research\\Mathematica\\11.0\\SystemFiles\\Components\\MachineLearning\\Resources\\Libraries"}}}
Arguments:
Root is the path to the folder the resources are stored in, relative to the paclet directory.
Resources is a list of resources. Each resource can be defined as a string for the resource path or a list {"Name", "Path"} where Name is an alias to identify the resource. The path is relative to the Root path. The resource can be a file or directory.
SystemID must be used when resources are system specific.
* From personal correspondence with Todd Gayley, WRI
.zipfor extraction in a place where it can be loaded. However, deploying a paclet seems to be the future and the more consistent way of doing this. $\endgroup$