PacletAssurance`
PacletAssurance`

CreateDeveloperPaclet

CreateDeveloperPaclet["name","package"{"fn1","fn2",…}]

creates a paclet layout called name that defines package containing exports fni placed within $DeveloperDirectory.

Details and Options

  • CreateDeveloperPaclet creates a directory containing a corresponding PacletInfo.wl.
  • CreateDeveloperPaclet creates a "developer paclet" that is designed to be progressively modified in-place in $DeveloperDirectory until ready for a final build and install.
  • Following the creation of the paclet PacletDataRebuild is automatically called to ensure that the package becomes immediately available.
  • The following options are supported:
  • "PacletLayout""Classic"the layout used to create a new paclet
    "Extensions"{"Kernel","Documentation","TestFiles"}the set of paclet extensions provided by the new paclet
    "ExtensionLayoutFunctions"<| |>key-value pairs used to create extensions in the new paclet
    "Version""0.0.1"the initial "Version" number of the new paclet
    "WolframVersion"Automaticthe initial "WolframVersion" requirement of the new paclet. Defaults to any version greater than or equal to $VersionNumber
    "PacletLayoutLocation"Automaticthe location of a paclet layout used as a template for creating a new paclet
    "DeveloperDirectory"$DeveloperDirectorythe directory into which the created paclet is placed
  • Possible settings for "PacletLayout" include:
  • "Classic"creates a flat paclet layout with .wl source files
    "ClassicNotebook"creates a paclet layout with .nb files containing intialization cells that automatically generate source .wl files
  • The setting of options "ExtensionLayoutFunctions", and "PacletLayoutLocation" are only needed if a custom layout is required either by modifying an existing pacletlayout or by creating a new one. To do this it is necessary to understand the steps that CreateDeveloperPaclet follows:
  • CreateDeveloperPaclet["name", …, "PacletLayout""pacletlayout", "PacletLayoutLocation""dir", "DeveloperDirectory""devdir"] copies the paclet in dir/pacletlayout into devdir/name renaming it in the process before modifying the created paclet according to settings in ExtensionLayoutFunctions["pacletlayout"] or as defined/overridden in the option "ExtensionLayoutFunctions".
  • The output of ExtensionLayoutFunctions["pacletlayout"] is an association typically of the form "Kernel" fnk,"Documentation"fnd, "TestFiles"fnt, … with keys specifying extension names and functions, fni specifying how the layout of the extension name is to be created from the corresponding paclet template.
  • ExtensionLayoutFunctions["pacletlayout"]="Extension1" fn1, … defines a function,
    , that takes the same two arguments as those of the canonical form of CreateDeveloperPaclet and modifies the file layout of "Extensioni". The modification takes place on the paclet initially placed at the location developerdirectory/name.
  • The value of the option "ExtensionLayoutFunctions" is an association of the same form as the value of ExtensionLayoutFunctions["pacletlayout"].
  • The option "ExtensionLayoutFunctions" can be used to specify the layout of an extension that is not specified in ExtensionLayoutFunctions["pacletlayout"].
  • The default value of "PacletLayoutLocation" is PacletObject["CodeAssurance"]["Assets","PacletLayoutLocation"].
  • To create your own pacletlayout, place a template paclet layout at pacletlayoutlocation/pacletlayout and ensure that ExtensionLayoutFunctions[pacletlayout] is defined and specifies how the template paclet's extensions are to be modified in-place when CreateDeveloperPaclet is invoked.
  • Placing a definition of ExtensionLayoutFunctions[pacletlayout] in the file pacletlayoutlocation/pacletlayout/"ExtensionLayoutFunctions.wl" ensures that it is automatically accessed when needed.
  • The number of files and subdirectories layout in Kernel, Documentation and TestFiles folders can differ depending on the setting of the "PacletLayout" option.
  • CreateDeveloperPaclet <-> PacletBuildInstall <-> PacletDeploy defines an Onsoc- recommended paclet-workflow.

Examples

Basic Examples  (1)

Ensure that developer mode is entered and that all new paclets are created in $DeveloperDirectory.

Create a new paclet named MyPaclet that includes a new package MyPackage containing exported functions, FooA and FooB.

The created paclet contains templated entries Kernel, Documentation and TestFiles directories for a first iteration of an implemented, documented and tested MyPackage with exported functions FooA and FooB.

Load the package.

The functions FooA and FooB have been added to the current namespace

Various test files associated with introduced functions FooA and FooB have been automatically created in corresponding folders in the TestFiles directory. For example, FooA.m contains canonical functionality for FooA, while files for ExceptionHandling and Documentation have also been automatically generated.

Run the "canonical" tests associated with FooA

or other tests covered in FooA's documentation

Following a paclet's creation, its functionality, documentation and test files can then be progressively added prior to the paclet's final installation and deployment.

The default "PacletLayout" is set to ClassicNotebook that creates package code from corresponding notebooks with initialization cells. A workflows that edits .wl files in external IDE's can be created via a Classic "PacletLayout".

Tech Notes
▪
  • Paclet Workflow
    • ▪
  • Testing that Scales