CodeAssurance`
CodeAssurance`

CreateDeveloperPaclet

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

creates a paclet called name containing package with its own exports fni.

Details and Options

  • By default, the paclet is created in $DeveloperDirectory.
  • The newly created paclet contains a corresponding PacletInfo.wl.
  • The following options are supported:
  • "KernelLayout""ClassicNotebook"the layout used in creating the kernel extension
    "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
    "Description"Automaticshort description of the paclet
    "DeveloperDirectory"$DeveloperDirectorythe directory into which the created paclet is placed
    "EnterDeveloperMode"Truewhether or not to enter developer mode following the paclet's creation.
  • Possible settings for "KernelLayout" 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
  • CreateDeveloperPaclet automatically creates extensions Kernel, Documentation and TestFiles as minimal requirements for subsequent applications of PacletDeploy.
  • The number of files and subdirectories layout in the Kernel extension can differ depending on the option setting of "KernelLayout".
  • In CreateDeveloperPaclet[…, "DeveloperDirectory"dir, "EnterDeveloperMode"True], following the paclet's successful creation PacletDirectoryLoad[dir] is automatically evaluated.
  • CreateDeveloperPaclet creates a "developer" paclet that is designed to undergo continual refinement in concert with subsequent applications of PacletDeploy prior to a final, release deployment.

Examples

open allclose all

Basic Examples  (1)

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

The created paclet contains folders Kernel, Documentation and TestFiles with MyPackage containing the file MyPackage.nb with initialization cells whose contents are saved into MyPackage.m.

Load MyPackage from the created paclet.

The functions FooA and FooB initially contain the initial toy functionality of adding 1.

CodeAssurance provides capabilities for creating, managing and running of tests that have been suitably placed within a paclet's TestFiles directory. Test files corresponding to the functions specified in CreateDeveloperPaclet are automatically generated. In MyPaclet, for example, test files have been automatically generated for functions FooA and FooB in itsTestFiles directory.

The tests themselves have been divided into three categories each defining starting points for developing a sound testing practice. Core.nb is designed to contain tests defining a function's core functionality; Documentation.nb is designed to contain any remaining tests that capture examples in the function's documentation while finally, ExceptionHandling.nb is designed to contain tests describing how the function handles exceptions.

Note that each file-based categorization comes in two flavours, a .nb file and its .wlt derivation, a separation that is useful for creating and running of tests. With this layout in place granulated testing is available.

Run and summarize all six tests created for FooA.

Perform a more targeted testing only core tests.

Following a paclet's creation, its functionality, documentation and test files are designed to be progressively edited prior to the paclet's eventual deployment.

Delete this toy developer paclet.

The default "KernelLayout"->"ClassicNotebook" sets up a workflow whereby package code is automatically generated from initialization cells in corresponding notebooks that are themselves progressively edited. An alternative workflow is to directly edit .wl files (in any editor) which is set up by the option setting, "PacletLayout"->"Classic".

As we are already in developer mode this paclet's package is immediately available.

Along with the package's functionality.

Delete this toy developer paclet.

Possible Issues  (1)

In addition to creating a paclet, by default, CreateDeveloperPaclet also causes the current session to enter development mode. This is usually convenient since it makes the created developer paclet immediately available in the current session. It does however, introduce a side-effect that can be antithetical to expectations surrounding a functional-like language. Restoring this no-side-effect expectation however, is readily implemented by setting the option "EnterDeveloperMode"->False.

Eliminate the side effect of entering developer mode.

If not in developer mode the paclet remains unavailable

To make the paclet available, enter developer mode

View the newly available paclet

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