packages - PacletInfo.m documentation project

Packages can be made into paclets, which provides easy distribution and versioning. The paclet metadata is in the PacletInfo.m file. The PacletInfo settings also determine how the paclet can extend Mathematica: e.g. provide new functions for the kernel (a usual package), new palettes or stylesheets for the Front End, etc.

What settings and extensions can be used in a PacletInfo.m file and what are their effects?

Documenting these will be very useful for people who develop and publish packages.

---

Related posts:

Answer

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.

---

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.

---

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.

---

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.

---

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 All


• Root, defaults to "Documentation"


• Context, rarely needed, use same argument in Kernel extension instead


• MainPage


• LinkBase


• Resources

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:

• 
  

  Root, defaults to "FrontEnd"

  
  
  


• 
  

  WolframVersion

  
  


• 
  

  SystemID

  
  

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.

• 
  

  Root, defaults to LibraryResources.

  
  


• 
  

  WolframVersion

  
  


• 
  

  SystemID

  
  

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

  
  


• 
  
  

  Resources

  
  


• 
  

  SystemID

  
  

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