From RTSC-Pedia
 | [printable version] | offline version generated on 04-Aug-2010 21:08 UTC |    |
RTSC Packaging Primer/Lesson 4
Elementary Packages — producing charlie.sqrtlib.samples
From this point forward, we'll explore RTSC packaging from the perspective of the producer—a content supplier looking to deliver collections of software artifacts housed within individual RTSC packages, ready for consumption by multiple clients using the tools and techniques illustrated in the last three lessons. With charlie.sqrtlib.samples serving as our first exemplar, we'll mainly focus upon the release phase of the package life-cycle—the process of manufacturing package archive files once the producer has built the package's contents.
You'll recall that charlie.sqrtlib.samples contains some source files used in the client application presented in Lesson 3; from the package producer's perspective, however, "building" the contents of this particular package becomes trivial.
Despite their overt simplicity, examining elementary packages like charlie.sqrtlib.samples reveals structural traits common to all RTSC packages—whether delivered independently or bundled as part of a larger product offering, or whether containing full-fledged RTSC modules built for multiple targets or just a handful of sample source files.
Contents |
Specifying the package
As shown pictorially back in Lesson 1, a RTSC package must contain a distinguished XDCspec source file named package.xdc within its corresponding package directory. While other special files and directories described shortly will potentially come and go as the package progresses through its natural life-cycle, both the presence and contents of package.xdc remain invariant—a trait shared by all RTSC packages, as they journey from producer to consumer.
In general, package.xdc specification files will define a number of high-level, client-visible features of the package at hand—including its mandatory globally-unique name. In the case of charlie.sqrtlib.samples, its package.xdc file actually contains very little beyond the bare minimum:
| charlie/sqrtlib/samples/package.xdc | |
| 1 2 | /*! Sample programs using charlie.sqrtlib */ package charlie.sqrtlib.samples { /* no module declarations */ } |
Before we talk about the all-important package declaration, however, a few words about the comment preceding it at line 1: Most modern programming languages offer direct support for special documentation comments that you can embed within source files—Java offers "JavaDoc", Perl offers "PerlDoc", and so forth; integrated tooling then automatically generates appropriate user (client) documentation that in turn includes these comments. The XDCspec language follows suit, enabling content producers to embedded "XDoc" comments within .xdc specification files; utilities like xdc.tools.cdoc.sg in turn synthesize documentation for the content consumer.
In general, XDoc comments follow conventions already familiar to users of doxygen, a popular tool amongst C programmers for annotating headers files with a similar style of commentary—one coincidently rooted in the look-and-feel of JavaDoc. But setting syntax aside, don't forget the real purpose behind embedding XDoc comments in .xdc source files: to define a programmatic contract between client and supplier, which realistically requires a mixture of formal XDCspec declarations amplified with informal textual commentary.
Using a notation suggestive of a C struct, the XDCspec package declaration at line 2 should remind you that charlie.sqrtlib.samples ultimately represents a programmatic namespace that scopes all of the software artifacts contained within this package—just as C structures would scope individually named fields declared therein. And while this package contains no modules—unlike charlie.sqrtlib, which we'll explore in later lessons—the corresponding charlie/sqrtlib/samples package directory nevertheless serves as a kind of "protective domain" for the sample files delivered with this package.
Clearly, this package declaration tells us nothing about these sample files—their names, how to build them, where to modify them, and so forth. In practice, more XDCspec documentation comments could surely help here, yielding a concise yet complete reference page for clients consuming this package. To see what's possible, fire-up xdc.tools.cdoc.sg and browse to (say) the xdc.runtime package; there, you'll find a link to a viewable form of the xdc/runtime/package.xdc file that originally sourced this material (click on the text "sourced in xdc/runtime/package.xdc".)
Scripting package production
If we think of package.xdc as publicizing the external (client-visible) face of a RTSC package, the other special file depicted in the original figure from Lesson 1—namely package.bld—generally plays a more internal (supplier-centric) role in orchestrating package production. Unless suppliers make explicit provisions when releasing packages—that is, when manufacturing package archive files for delivery to clients—the special package.bld file generally stays behind.
Another difference between package.xdc and package.bld mirrors some distinct characteristics of the eXpanDed C languages respectively used to source their contents:
- package.xdc files (written in the XDCspec specification language) will seem very declarative in nature, playing a role not unlike a C header file though on a somewhat grander scale; whereas
- package.bld files (written in the XDCscript meta-language) will look more like an executable program that "does something", albeit expressed in a somewhat higher-level manner than possible with C.
Illustrating this point with a concrete example, we'll turn to the rather sparse package.bld script that actually drives production of the charlie.sqrtlib.samples package—which, if you recall, just contains a few sample files.
| charlie/sqrtlib/samples/package.bld | |
| 1 2 3 | var Pkg = xdc.useModule('xdc.bld.PackageContents'); Pkg.attrs.archiver = "zip"; Pkg.otherFiles = ["makefile", "prog.c", "prog.cfg"]; |
Details aside, the programming idioms used in this package.bld script in fact mimic what you've already seen in the prog.cfg meta-program presented in Lesson 3—another example of some XDCscript code that "does something". Back to package.bld, execution of this script effectively assigns some parameters of xdc.bld.PackageContents—a special meta-module bundled with XDCtools—much as prog.cfg assigned Bench.enable and Settings.optimize.
For C programmers unfamiliar with the "object-oriented" syntax of JavaScript—and hence XDCscript—the «object».«property» idiom at lines 2 or 3 are not unlike accessing a struct field in C. The root object here—held in a (local) variable named Pkg for brevity—results from a call to the useModule property of a special (global) object named xdc on line 1. The «object».«property» idiom is in fact more general than a simple field access, and also subsumes function calls of the form «object».«function»( «args» ); object-oriented languages often term functions invoked in this manner as methods.
After importing the PackageContents module at line 1, the assignment at line 2 selects which archive format to generate here—overriding the default value of "tar". The statement at line 3 then names an array of files (all found in the charlie/sqrtlib/samples package directory) to include within the generated package archive.
The array of otherFiles assigned at line 3 can in general name any sort of artifact rooted in the current package directory—source files, binary files, even other directories. Using the package.xdc spec and package.bld script listed here as templates—any collection of legacy content can become an elementary RTSC package.... It's just that simple!!
Barring any further assignments to the (many!) parameters of PackageContents, the package.bld script as it now stands prescribes that the charlie.sqrtlib.samples package will release a package archive named (by default) charlie_sqrtlib_samples.zip.
To appreciate its richness, fire-up xdc.tools.cdoc.sg and browse to the PackageContents module within the xdc.bld package; or alternatively visit rtsc.eclipse.org and browse through the set of statically-generated HTML pages found there—generated, incidentally, using a companion command-line utility know as xdc.tools.cdoc.
Using the xdc command
With the necessary package.xdc and package.bld files for charlie.sqrtlib.samples now in place, we'll proceed to build and release the package using another special command bundled with XDCtools. Appropriately named xdc, this command fundamentally performs the following sequence of steps when invoked from within a package directory:
- parses the package.xdc file, which specifies many top-level features of the package at hand;
- executes the package.bld script, the final state of which prescribes "what to produce"; and
- generates package.mak, a standard GNU makefile which then controls the rest of the process.
If you're "playing along" and want to try running the xdc command, you'll first have to re-define the current package path (say, by setting the XDCPATH environment variable) to only contain the «examples» directory created back in Lesson 0. Unlike the released forms of the charlie.* packages consumed in the previous lessons, the «examples» repository holds buildable forms of these packages as evidenced by their supplier-centric package.bld files—a necessary requirement for using the xdc command.
The xdc command operates very much like gmake used in Lesson 3, in that both commands take "goals" as their arguments to designate a particular end-result. For example, invoking xdc clean from within any package directory (in our case, «examples»/charlie/sqrtlib/samples) would remove all generated files resulting from any prior use of the xdc command—such as package.mak as well as the special package/ sub-directory.
Similarly, invoking xdc release would build and release the contents of the current package according to the prescription laid out in package.bld, yielding the following output for this example:
| 1 2 3 | %> xdc release
making package.mak (because of package.bld) ...
generating interfaces for package charlie.sqrtlib.samples (because ... ) ...
all files complete.
generating schema include file list ...
generating external package references package/package.ext.xml ...
generating package references graph package/package.rel.dot ...
making release file charlie_sqrtlib_samples.zip (because ... ) ... |
Dissecting the output, line 1 confirms generation of the package.mak file—which only occurs when necessary, such as after editing package.bld. The output leading up to line 2 then reflects all of the steps actually needed to build the contents of the package—which here boils down to just creating and populating a special package sub-directory that holds additional generated files; for packages like charlie.sqrtlib, compilation of C source code into function libraries for one or more RTSC targets would happen at this point in the flow. Invoking xdc all (or just xdc by itself), drives the process to this juncture—yielding a built package.
Once built, the output leading up to line 3 reflects the release phase of the package life-cycle, culminating here with production of a single package archive file ready for delivery to any prospective client(s). The archive itself contains many (but by no means all) of the generated files placed in the special package sub-directory along the way. More important, perhaps, the package archive does contain the mandatory package/package.rel.xml file—which not only distinguishes a released package, but also contains a wealth of information accessed by hosted utilities such as xdc.tools.repoman and xdc.tools.path.
For all intent and purposes, the xdc command is gmake—invoking xdc will quickly transfer control in a very precise manner to a specific version of gmake bundled with the XDCtools product. But unlike our earlier example from Lesson 3 which contained a hand-crafted makefile, the xdc command instructs gmake to operate on the generated package.mak file found in all RTSC packages; and through the magic of gmake (evidenced by line 1 in the earlier output), package.mak will itself be (re-)generated from package.bld only when absolutely necessary. The xdc command handles (re-)parsing of the package.xdc spec file in a similar way.
See also
| Command - xdc | eXpanDed C package build command |
| xdc.bld.PackageContents | Client documentation for xdc.bld.PackageContents |
| xdc.tools.cdoc.Markup | Client documentation for xdc.tools.cdoc.Markup |
| [printable version] | offline version generated on 04-Aug-2010 21:08 UTC | |
