From RTSC-Pedia

[printable version]

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

RTSC Packaging Primer/Lesson 6

Package Release — manufacturing charlie.sqrtlib archives

Having finally built charlie.sqrtlib, we'll return again to the process of creating deliverable archives during the release phase of package production. Using charlie.sqrtlib as illustrative of a "typical" RTSC package that houses target content, we'll now explore some more advanced capabilities of the xdc.bld meta-modules which ultimately give the package producer greater control at the tail-end of RTSC build flow.

Releasing multiple archives

The basic xdc.bld mechanisms first introduced in Lesson 4 for defining the contents of the (default) package archive file can in fact scale to handle scenarios when a single package yields multiple archives. As an example, let's assume the supplier of charlie.sqrtlib wants to manufacture three distinctly named package archives:

• charlie_sqrtlib.zip, which delivers (binary) libraries compiled for all RTSC targets;
• charlie_sqrtlib-DSP.zip, which delivers (binary) libraries compiled only for one target; and
• charlie_sqrtlib-SRC.zip, which delivers a buildable (source) form of the original package.

To illustrate the technique, we'll now complete the package.bld script for charlie.sqrtlib begun in the last lesson—filling in the details of what to release as well as what to build.

var Build = xdc.useModule('xdc.bld.BuildEnvironment');
var Pkg = xdc.useModule('xdc.bld.PackageContents');
 
/* ---- what to build ---- */
 
for each (var targ in Build.targets) {
    Pkg.addLibrary("lib/isqrt_loop", targ).addObjects(["isqrt_loop.c"]);
    Pkg.addLibrary("lib/isqrt_unroll", targ).addObjects(["isqrt_unroll.c"]);
}
 
/* ---- what to release ---- */
 
Pkg.attrs.archiver = "zip";
Pkg.otherFiles = ["isqrt.h"];
 
var relDSP = Pkg.addRelease("charlie_sqrtlib-DSP");
relDSP.otherFiles = ["lib/isqrt_loop.a64P", "lib/isqrt_unroll.a64P"];
relDSP.attrs.label = "DSP";
 
var relSRC = Pkg.addRelease("charlie_sqrtlib-SRC");
relSRC.attrs.exportAll = true;
relSRC.attrs.label = "SRC";
relSRC.attrs.relScript = "./copyright.rel";

With multiple releases defined here, the pair of assignments at line 2 in fact prescribe characteristics common to all archives produced by this package—not just the package's "default" archive (automatically added under the name "charlie_sqrtlib" and labeled as "default"). In this example, all package releases would use .zip files; and all package releases would include the isqrt.h header.

Explicit calls to the addRelease meta-function at lines 3 and 4 then return new XDCscript objects with an analogous set of assignable properties, selectively updated to override or else extend default values taken from the PackageContents module itself. Looking closer at the DSP-only release defined after line 3, the assignment here to otherFiles effectively adds these two libraries to the array of files already common to all releases—just isqrt.h in our case; the assignment of "DSP" to attrs.label, by contrast, replaces its original "default" value.

In the case of the source-code release defined after line 4, setting attrs.exportAll effectively adds all of the files not generated during package build to this particular archive—including the package.bld file itself. As a further consequence of the addLibrary calls after line 1, this set includes the C source files directly used when generating the lib/isqrt_loop and lib/isqrt_unroll libraries.

Filtering released content

Besides prescribing the file-level contents of individual archives manufactured during package release, more advanced mechanisms exist that allow you to filter individual files as well—programmatically transforming a copy of the file itself just before adding it to one of the released package archives. As a motivating (and not uncommon) example, let's assume the supplier of charlie.sqrtlib wants to add a special comment of the form /* Copyright Charlie & Co. */ at the top of each .c file included in this package's source-code release.

The assignment to attrs.relScript at line 5 of the package.bld script presented above already sets the stage, naming yet another XDCscript source file which then organizes and performs the filtering per se. As evidenced from the form of its name, the ./copyright.rel file presumably exists within the charlie/sqrtlib package directory.

var Manifest = xdc.useModule('xdc.bld.Manifest');
 
for each (var fname in Manifest.files) {
    if (!fname.match(/[\/]package[\/]/) && fname.match(/[\.]c$/)) {
        var filter = new Manifest.Filter();
        filter.operation = addComment;
        Manifest.filterMap[fname] = filter;
    }
}
 
var COPYRIGHT_COMMENT = "/* Copyright Charlie & Co. */\n\n";
 
function addComment( filter, src, dst, base )
{
    print("copyrighting " + base + " ...");
 
    var infile = new java.io.BufferedReader(new java.io.FileReader(src));
    var outfile = new java.io.BufferedWriter(new java.io.FileWriter(dst));
 
    outfile.write(COPYRIGHT_COMMENT);
 
    var line;
    while ((line = infile.readLine()) != null) {
        outfile.write(line);
    }
 
    infile.close();
    outfile.close();
}

Similar to how package.bld manipulates PackageContents, this script works with parameters of the special Manifest meta-module imported at line 1—likewise found in the xdc.bld package bundled with XDCtools. The main portion of this script iterates over each file name contained in the Manifest.files array, beginning at line 2. Using a built-in XDCscript method for matching character strings against regular expressions (courtesy of the underlying JavaScript engine), files not found within the special package/ sub-directory and whose names end with .c become entries in the Manifest.filterMap at line 4.

Each entry in Manifest.filterMap—an XDCscript hash-table keyed by the names of individual files—itself represents another XDCscript object of type Manifest.Filter, newly-created back at line 3. The value then assigned to this object's operation property further identifies an XDCscript function called addComment, also defined inside of copyright.rel beginning at line 5.

Turning now to the body of addComment—which may even surprise some readers already familiar with JavaScript—this function basically writes the COPYRIGHT_COMMENT string to the output file (named dst) [7] followed then with each successive line read from the input file (named src) [8]. Note that while dst will generally reference a temporary directory used in manufacturing package archives, the base argument to addComment printed at the outset [6] mirrors the original file name contained in the Manifest.files arrays searched back at line 2; for completeness, the filter argument to addComment tracks the Manifest.Filter instance object originally created back at line 3.

Using the xdc command

Invoking the xdc release command—first illustrated back in Lesson 4—would here manufacture all three of the package archives prescribed in the package.bld script for charlie.sqrtlib. Alternatively, you can manufacture just one of these package archives by invoking (say) xdc release,charlie_sqrtlib-SRC from within the package directory.

%> xdc release,charlie_sqrtlib-SRC
all files complete.
making release file charlie_sqrtlib-SRC.zip (because of ...) ...
copyrighting charlie/sqrtlib/isqrt_loop.c ...
copyrighting charlie/sqrtlib/isqrt_unroll.c ...

The output at line 1 reflects the fact that we've already built this package; otherwise, you'd see output commensurate with invoking xdc all immediately before running this command. As you'd expect from any flow based on gmake, the generated package.mak file for this package enforces this dependency and re-builds when necessary.

The output at line 2 tracks the print statement at line 6 of copyright.rel—not only confirming that we've extracted the correct files from the Manifest.files array beginning at line 2 of the same file, but also reinforcing the fact that copyright.rel executes near the end of the RTSC build flow.

See also

TODO:  write it

[printable version]

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