Package Usage and Development » Paclet Development

‌

Paclet Structure

We briefly mentioned what a paclet looks like previously, but we didn't discuss what the different types of paclets will look like and how this will be reflected in the PacletInfo.m file.

First we'll handle some PacletInfo.m basics then get into more details on how paclet structure is reflected here.

PacletInfo.m

The PacletInfo.m file supplies a Paclet expression that encodes metadata in rules. The absolute simplest example might be: 

 Paclet[
  Name->"MyPaclet",
  Version->"1.0.0"
  ]

This simply tells the system there is a paclet named "MyPaclet" that has version "1.0.0" . There are many different parameters we can supply though:

  • WolframVersion — specifies the minimum version of Mathematica necessary to get the paclet to function properly

This should be a string that looks like "11.0.1+" or "10+" or similar

  • SystemID — specifies the operating system or systems on which the paclet may be expected to work.

The valid IDs are the valid IDs for $SystemID .

  • Loading — specifies the loading mode for the paclet

The valid loading modes are Manual (default), Automatic , and "StartUp" . With the "StartUp" mode, the paclet is loaded right after the PacletManager . The Automatic mode will configure autoloading for any symbols that are provided as part of the "Kernel" extension (we'll get into this later).

There are also a number of useful bits of descriptive metadata that are used by the Installed Add-Ons Guide and other third-party interfaces:

  • Description — provides a brief description for the paclet
  • Creator — specifies the creator of the paclet

This should generally be a name and an email as one string, e.g. "b3m2a1 <b3m2a1@gmail.com>"

  • Publisher — specifies the organization publishing the paclet, if relevant
  • Thumbnail — relative path to an icon for the paclet

Other bits of standard data are:

  • License — the license for the paclet
  • Copyright — the copyright holder of the paclet
  • Support — contact info for support

Extensions

The Paclet expression can also supply an "Extensions" parameter that tells the manager what kinds of things may be done with it. A paclet with extensions will look like: 

 Paclet[
  Name->"MyPaclet",
  Version->"1.0.0",
  Extensions->
    {
      {"Extension1", "Prop1"->val1, ...},
      {"Extension2", "Prop1"->val1, ...},
      ...
      }
  ]

The different extensions are what allow different types of resources to be served by the PacletManager . We'll break these down in turn.

Kernel

The first and probably most common extension we'll want is the "Kernel" extension. If a paclet supplies code, it will want a "Kernel" extension.

It has three main parameters it can take:

  • "Root" — this is the root off of which the "Kernel" folder should be located. Defaults to "." .
  • "Context" — this supplies the contexts the paclet can load
  • "Symbols" — this supplies a set of symbols that the paclet provides. If the Loading is set to Automatic , autoloading will be set up for everyone of these symbols.

For a paclet structure that looks like

```

MyPaclet + PacletInfo.m Kernel + init.m MyPaclet.m SubContext.m ```

We'd write the extension to look like:

```{ "Kernel", "Root"->".", "Context"->{"MyPaclet", "MyPacletSubContext", ...} } ``

FrontEnd

The "FrontEnd" extension tells the PacletManager to make the supplied front-end resources available system-wide. It has a few parameters:

  • Root — the path to the front-end root directory. Defaults to "FrontEnd" .
  • Prepend — if True the resources are prepended to the lookup path for the FE

We can supply four different types of FE resources, each within a sub-folder of the "FrontEnd" folder:

  • "StyleSheets" — the folder containing stylesheet notebooks

These notebook will appear in the main menu under Format » Stylesheet . If placed within a sub-folder, they'll be place in the group with that name in the menu. If nested twice they won't appear in the menu at all.

  • "Palettes" — the folder containing palette notebooks

These operate fundamentally the same as the stylesheets with respect to the sub-folders and appearing in the menu.

  • "TextResources" — the folder containing .tr files that serve resources for FrontEndResource

More info on these text resources can be found here or elsewhere on the Mathematica StackExchange.

  • "SystemResources" — the folder containing various system resources that may be used by the front-end. There are two subfolders:
    • "Bitmaps" — the sub-folder containing various bitmaps and icons to be served
    • "AutocompletionData" — the sub-folder containing pieces of autocompletion data to be served, especially the specialArgFunctions.tr file or .trie files

Anytime we want front-end resources we provide to be used we should add the extension: 

 {
  "FrontEnd",
  Prepend->True
  }

Documentation

Allows documentation files to be found and searched automatically. It has the following parameters:

  • "Language" — the target language for the docs (defaults to All )
  • "Root" — the root path for the docs (defaults to "Documentation" )
  • "LinkBase" — the path root (e.g. "PacletManager" in "PacletManager/ref/PacletInstall" )
  • "MainPage" — the default landing page for the paclet

If we want to add English-language documentation to our paclet we'd set up the paclet like: 

 MyPaclet
 + PacletInfo.m
 Documentation
  English
   ReferencePages
    Symbols
     + MySymbol1.nb
     + MySymbol2.nb
     ...
    Guides
     + MyPaclet.nb
     + OtherGuide.nb
     ...
    Tutorials
     + Feature1.nb
     + Feature2.nb
     ...

Then our extension would look like: 

 {
  "Documentation",
  "Language"->"English",
  "LinkBase"->"MyPaclet",
  "MainPage"->"Guides/MyPaclet"
  }

Resource

The "Resource" extension may be used multiple times and supplies different resources that can be accessed via PacletResource .

Each resource takes a set of parameters

  • "Root" — the root from which lookups are done
  • "Resources" — a set of relative paths to the resources
  • "SystemID" — a specific system ID for the resource (defaults to All )

Each elements in the "Resources" should either be the relative path or a list {name, path} where name is a nickname for the resource.

As an example, if we wanted to supply a set of resources we could have our paclet setup like: 

 MyPaclet
 + PacletInfo.m
 Resources
  + MyResource1.mx
  SubResources
   + SubResource1.mx

And then the extension would look like 

 {
  "Resource",
  "Root"->"Resources",
  "Resources" ->
    {
      {"Resource", "MyResource1.mx"},
      {"SubResource", "SubResources/SubResource1.mx"}
      }
  }

JLink

Automatically adds the supplied .jar files to the classpath. Has the following parameters:

  • "Root" — specifies the root directory (defaults to "Java" )
  • "WolframVersion" — the versions for which the .jar files are valid
  • "SystemID" — the systems for which the .jar files are valid

LibraryLink

Automatically makes the supplied library files locatable via FindLibrary . Note that FindLibrary will find the file Root/$SystemID . Has the same kind of parameters as "JLink" :

  • "Root" — specifies the root directory (defaults to "LibraryResources" )
  • "WolframVersion" — the versions for which the library files are valid
  • "SystemID" — the systems for which the library files are valid

AutoCompletionData

Provides autocompletion data for lookup. Only supplies the "Root" parameter.