Compiled Components

IntroductionCreating a Compiler-Based Paclet

Introduction

Compiled components represent collections of compiled functionality. This includes declarations that can be used in compiled code and installed functions that can be used in top-level code. Compiled components provide a framework for packaging and distributing this functionality.

Creating a Compiler-Based Paclet

Integration with the paclet system makes it possible to distribute a compiled component and its associated builds beyond a single kernel session. In this example, a compiled component is defined that exposes a few installed functions and that depends on an external library.

Defining the Paclet

To start, create a new paclet:
Modify the PacletInfo.wl file to include the "LibraryResources" extension, which will make it possible for the component system to locate the component build library later:
PacletObject[
    <|
        "Name" -> "ComponentPaclet",
        "Version" -> "0.0.1",
        "WolframVersion" -> "13.2+",
        "Extensions" -> {
                {"Kernel", "Root" -> "Kernel", "Context" -> "ComponentPaclet`"},
                {"LibraryResources"}
            }
    |>
]
Modify the source of the paclet to create and populate a compiled component:
BeginPackage["ComponentPaclet`"]

AddOne
RaiseToPower

Begin["`Private`"]

(* Declare compiler declarations *)
DeclareCompiledComponent["ExampleComponent", {
    LibraryFunctionDeclaration["addone", "compilerDemoBase", {"CInt"}->"CInt"],

    FunctionDeclaration[AddOne,
        Typed[{"CInt"} -> "CInt"]@
        Function[arg, LibraryFunction["addone"][arg]]
    ],

    FunctionDeclaration[RaiseToPower,
        Typed[{"MachineInteger","MachineInteger"} -> "MachineInteger"]@
        Function[{x,y}, x^y]
    ]
}];

(* Declare installed functions *)
DeclareCompiledComponent["ExampleComponent", "InstalledFunctions" -> {
    AddOne,
    RaiseToPower
}];

(* Declare library functions *)
DeclareCompiledComponent["ExampleComponent", "LibraryFunctions" -> <|
    "sqrt" -> Function[Typed[arg,"Real64"], Sqrt[arg]]
|>];

(* Declare external library dependencies *)
DeclareCompiledComponent["ExampleComponent", "ExternalLibraries" -> {
    "compilerDemoBase"
}];

End[] (* End `Private` *)

EndPackage[]

Loading the Paclet

Load the paclet:
Loading the paclet causes the component to be defined, which can then be used in compiled code:
Because the component has not yet been built, attempting to use its installed functions leads to errors:

Building the Component

Compiled components must be built in order to access compiled library functions and installed functions.

The component can be built with BuildCompiledComponent. By specifying the PacletObject as the destination for the build, the component library will be placed in the paclet:
The call to BuildCompiledComponent created and populated the LibraryResources directory in the paclet with a dynamic library containing all the functions specified by the component:

Loading the Component

Now that the component has been built, installed functions can be used.

The first time an installed function is invoked, it will attempt to automatically load the component library:

This uses FindLibrary to locate the component build, which will be found in the paclet because it was given the "LibraryResources" extension in the PacletInfo.wl file.

Alternatively, the component build can be loaded explicitly with LoadCompiledComponent, making it possible to access all properties of the build:
LoadCompiledComponent makes it possible to access the library functions specified in the component:

Now that it has been built, the "ComponentPaclet" paclet could be immediately used in a fresh kernel session without having to recompile its source. It could also be distributed to other machines, though the build will only be compatible with the platform on which it was built. To build a cross-platform component library, BuildCompiledComponent will need to be run on every target platform.