From RTSC-Pedia

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC

RTSC Packaging Primer/Lesson 7

Program Configuration — selecting charlie.sqrtlib libraries

Having finally built and released the charlie.sqrtlib function libraries—one pair per RTSC target—we'll turn now to the task of selecting the appropriate library from this set during program configuration at the client's site. While the configuration process in general affords packages many opportunities to become active participants in building client applications—which we'll highlight towards the end of this lesson—selecting the appropriate function libraries that satisfy a particular set of program requirements becomes another "sweet spot" of RTSC packaging.

Specifying the Settings module

From the very outset, we've exposed you to a wide range of RTSC modules used in a variety of contexts:

• acme.utils.Bench, with its begin and end functions and its enable configuration parameter;
• xdc.bld.PackageContents, with its addLibrary function and otherFiles parameter;
• ti.targets.C64 and gnu.targets.Mingw, with their rootDir parameters; and now
• charlie.sqrtlib.Settings, with its optimize configuration parameter.

As a rule, content suppliers will explicitly declare the public (client-visible) features of a RTSC module—its constants, types, parameters, functions—through a separate XDCspec source file found in the corresponding package directory. Applying a simple physical design pattern borrowed from Java, the specification for the charlie.sqrtlib.Settings module must reside in a file named Settings.xdc housed in the charlie/sqrtlib package directory.

/*! Library of square-root functions */
package charlie.sqrtlib {
    module Settings;
}

/*! Controls library selection during program configuration */
metaonly module Settings {
 
    enum OptType {
        OPTIMIZE_FOR_SPACE,
        OPTIMIZE_FOR_TIME
    };
 
    config OptType optimize = OPTIMIZE_FOR_TIME;
}

Even more suggestive of a header file—but clearly expressed in a higher-level language than C—Settings.xdc like package.xdc before it defines its own namespace that in turns scopes other programmatic identifiers. In the case of the module declaration beginning at line 2—again, using a notation suggestive of a C struct—we've then introduced OptType and optimize within the scope of Settings itself.

The enum declaration at line 3 mirrors the syntax and semantics of C, and merits no further explanation at this point. As for the config declaration at line 4—a new keyword to match a new construct—suffice it to say that optimize becomes a property of the XDCscript object representing the Settings module with the client's prog.cfg file, with OPTIMIZE_FOR_TIME serving as its initial (default) value. Not unlike variables or fields in C, config declarations will effectively constrain the type of values this parameter can receive during assignment.

Implementation domain.  Whereas all RTSC modules will uniformly define their public client-visible features through a corresponding XDCspec source file—invariably found within the containing package directory, and viewable through client documentation utilities such as xdc.tools.cdoc.sg—internal implementation strategies can vary considerably from one module to the next:

• acme.utils.Bench has C-based implementations for its begin and end functions, callable from within executable target programs at runtime; whereas

• xdc.bld.PackageContents has an XDCscript-based implementation for its addLibrary function, callable from within hosted scripts generally running in a very specific context.

Our charlie.sqrtlib.Settings module of course has no functions at all, just a configuration parameter plus some supporting types and constants; practically speaking, the module does not require a private implementation in either programming language. Still, to reinforce the fact that its features remain limited to the client's configuration meta-program—as opposed to also having a presence in the client's executable target-program—we've qualified the declaration back at line 2 with the metaonly keyword.

Implementing the getLibs function

Back to the task at hand—selecting the appropriate set of libraries during program configuration—RTSC packages can explicitly participate at this stage of the process by implementing a special meta-function named getLibs. Sourced in XDCscript and found in a special file named package.xs within the corresponding package directory, the getLibs function returns a string naming each library actually used further downstream when linking the current program.

function getLibs( prog )
{
    var pkg = this;
    var Settings = pkg.Settings;
 
    var suffix = prog.build.target.findSuffix(pkg);
    var name;
 
    switch (Settings.optimize) {
        case Settings.OPTIMIZE_FOR_SPACE:
            name = "isqrt_loop";
            break;
        case Settings.OPTIMIZE_FOR_TIME:
            name = "isqrt_unroll";
            break;
    }
 
    if (suffix && name) {
        return "lib/" + name + ".a" + suffix;
    }
    else {
        return null;
    }
}

Automatically invoked during the final stages of RTSC configuration—well after first executing the client's prog.cfg script—the getLibs function has access to two important XDCscript objects used when constructing the list of libraries contributed by this package:

• prog (an explicitly named argument to getLibs) references an object whose properties characterize the program as a whole—including information about the current target extracted at line 3; and

• this (an implicit argument to getLibs) references an object representing the charlie.sqrtlib package per se—bound here to the local variable pkg at line 1 to improve readability.

Working backwards now, the string returned at line 5 relies on earlier assignments to suffix and name—which would here assume the values "isqrt_loop" and "64P" in light of our client application from Lesson 3. In general, the string returned by getLibs can name multiple libraries with ";" as a delimiter; and, in cases where a particular package has no libraries to contribute, getLibs can return an empty string "" or else the special value null.

Moving up the page, the switch statement beginning at line 4 discriminates amongst the set of possible values currently held by Settings.optimize—values of type OptType specified earlier at line 3 of Settings.xdc—and then appropriately assigns the local variable name. As for the binding of Settings at line 2 of getLibs, we've accessed the XDCscript object representing this module using a «package-object».«module-name» idiom, where pkg (alias this) here references the charlie.sqrtlib package object.

Completing the story now, the assignment to suffix at line 3 starts with the object bound to the prog argument of getLibs and then eventually navigates to a findSuffix function defined on targets; taking the current package object as its argument, findSuffix reflects on all targets used when building this package and returns the suffix "most compatible" with the target selected for this program configuration. Internally, findSuffix comprehends the rather rich backward-compatibility relationships that often exist amongst targets—for instance, "newer" targets (like ti.targets.C64P) can often link libraries compiled with "older" targets (like ti.targets.C62).

The xdc.IPackage interface

Besides getLibs, package producers can elect to implement other meta-functions in package.xs called at different points within the program configuration process—from when the package first enters the current configuration through final generation of the linker.cmd output file.

init

called upon importing this package into the current configuration, usually via xdc.useModule

close

called when the client's script completes its contribution to the current configuration

validate

called before generation of output files begins, giving the package one last opportunity to issue errors/warnings

exit

called after the current configuration has been successfully validated, immediately before generation

getSects

called during generation, to elicit contributions to linker.cmd beyond the libraries returned by getLibs

Like virtually everything within the world of RTSC, this set of functions ultimately belongs to a larger programmatic entity specified within an XDCspec source file—in this case, a RTSC interface named xdc.IPackage. Following the same pattern introduced earlier with the charlie.sqrtlib.Settings module, the special xdc package—bundled with the XDCtools product—indeed contains an XDCspec source file named IPackage.xdc.

package xdc {
    interface IPackage;
}

metaonly interface IPackage {
        ...
    function close();
    function exit();
    function getLibs(prog);
    function getSects();
    function init();
    function validate();
}

Similar to the modules we've already encountered, a RTSC interface defines a programmatic contract that aggregates a related set of constants, types, parameters, and functions. But unlike a RTSC module—which couples a client-visible specification with a distinct supplier-proprietary implementation at any point in time—a RTSC interface can simultaneously support multiple implementations. Said a little differently, any package producer can elect to furnish a specific implementation of the xdc.IPackage functions within their package.xs file—effectively superseding default implementations otherwise invoked during the program configuration process.

See also

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC