From RTSC-Pedia
 | [printable version] | offline version generated on 04-Aug-2010 21:08 UTC |    |
RTSC Packaging Primer/Lesson 1
Basic concepts — deploying the acme.utils package
To introduce the fundamentals of RTSC packaging, we'll begin by executing a rather elementary task from the content consumer's perspective—installing a single RTSC package named acme.utils. Though trivial to perform (just a few simple commands), we'll use this opportunity to examine the structure and organization of RTSC packages in general as well as the mechanisms used by the XDCtools to locate packages within your file-system.
Understanding just a few basic concepts will ultimately enable you to make intelligent choices in deploying RTSC packages—making their content readily available for consumption by individuals, by teams, or by entire companies.
Contents |
Different forms of a package
In general, RTSC packages will manifest themselves in several different forms; and we'll illustrate these using acme.utils as an example. Despite variations in its physical representation, however, the ultimate purpose behind a package such as acme.utils remains the same—to facilitate delivery of software content from producer to consumer.
In the case of acme.utils, this package just so happens to contain a RTSC module named Bench—one which we'll use later on within a sample application program presented in Lesson 3. (For anyone having read the RTSC Module Primer, you should know exactly what we're saying here; for the rest of you, we'll fill in some missing details when we present the program.)
Logical container. Independent of its physical form, a RTSC package logically serves as a standardized "box" that can hold just about any sort of software artifact—sources, binaries, scripts, docs, even other packages. As this logical container moves through its natural life-cycle—initially built and released by its producer and later installed and deployed by its consumer—a RTSC package will always remain as a unit so as not to compromise the overall integrity of its contents. As you'll soon come to appreciate, installing acme.utils doesn't really "open the box and remove its contents", but rather transforms the same logical package from one physical form to another.
Besides this important property of unity, each RTSC package also possesses an individual identity—which is to say, each of our conceptual software boxes will have a globally-unique label associated with it. With RTSC packages, this label takes the form of a hierarchic, multi-segment name—such as acme.utils in our example at hand. By convention, the first segment(s) of a RTSC package name will typically identify who produced the package; in our situation, the acme.utils package might have come from Acme Software who in turn might supply other RTSC packages, all with names of the form acme.rest-of-the-name.
For those of you familiar with Java—one of the first mainstream programming languages with package as a keyword—RTSC applies many of the same concepts within its own packaging architecture. As a case in point, Java developers routinely work with (re-usable) software elements partitioned across thousands of packages, each with a globally-unique muti-segment name that typically follows the reversed domain-name of the package supplier—com.ibm.*, org.eclipse.*, and so on.
File-system directory. When in use—by producer or consumer—each RTSC package physically manifests itself as a file-system directory whose relative path must mirror the full package name in an obvious manner; in the case of acme.utils, its contents must reside in a directory named acme/utils. It's that simple—and there's no exceptions!!
As you might have guessed, Java utilizes exactly the same physical design for its packages—a pattern that already scales across millions of producers/consumers: packages named com.ibm.* reside in directories named com/ibm/*; packages named org.eclipse.* reside in directories named org/eclipse/*; and so on. When in doubt, steal shamelessly from the success of others.
Looking inside what we'll term the package directory—here, acme/utils—you'd find a number of special files that not only confirm the identify of this directory as holding the contents of a particular RTSC package, but also track the state of this package as its advances through its natural life-cycle. Starting in Lesson 4, we'll explore these files in greater detail as you'll begin playing the role of package producer.
Regardless of its state, each RTSC package will always have a distinguished XDCspec source file named package.xdc in its corresponding package directory. If buildable using the XDCtools product, the package will also contain a special XDCscript source file named package.bld. Again, we'll revisit both of these files beginning in Lesson 4.
Once built by its producer—and hence usable by other clients, say for testing purposes—the package will also contain a special sub-directory named package that in turn contains a wealth of files generated by the XDCtools product. But ultimately, the producer would use the XDCtools to manufacture released forms of the package—identified through a generated package/package.rel.xml file—ready for delivery to package consumers.
Note that, by definition, all released packages are built packages; but a released package is not necessarily a buildable package—unless its original producer took explicit steps to make it so.
Archive file. Not surprising, producers deliver released RTSC packages in the form of a package archive file—typically a .zip file, though XDCtools supports tar.gz files as well—which can trivially recreate the structure and contents of a released package directory at the consumer's site. Returning to our example, you'll soon install the acme.utils package that presently resides in a package archive file named acme_utils.zip. Peeking inside, this archive preserves the acme/utils package directory along with the appropriate package* files illustrated above; and of course, this archive preserves the "real" content of acme.utils which we'll consume later on in Lesson 3.
Though not always obvious at first, the name of the package archive file need not precisely mirror the name of the package itself—though producers will typically choose archive names suggestive of their content. As it turns out, producers can manufacture multiple releases of the same package—say, one that contains buildable sources and another that only supports the Texas Instruments TMS320C64+ processor family—and will choose distinct file names for the corresponding package archives. We'll revisit this topic in Lesson 6.
The same holds true for Java .jar files, which typically coalesce multiple Java packages into a single archive. What really matters for programmers consuming Java content are the names of packages stored in the archive, and not the name of the archive itself.
Populating a package repository
As hinted above, a package archive file serves as an transient form of a RTSC package—one optimized for delivery by producers to consumers—that eventually must reconstitute itself as a released package directory somewhere in the consumer's file-system. The question now becomes one of where—in the case of acme.utils, where should we root the acme/utils package directory currently archived in acme_utils.zip. The answer is, "Anywhere you want"....
This rather direct response brings us to the next basic concept in RTSC packaging—package repositories, which are just ordinary directories within your file-system that we'll populate with package directories such as acme/utils. Whereas package directories must follow a canonical naming pattern, no such convention exists for package repositories; since you ultimately own and control the repository directories, name them whatever you wish.
So now, let's imagine a newly-created directory named myrepo rooted somewhere within your file-system, which we'll symbolically refer to as «local»/myrepo in the following examples. At this point, we could easily extract the contents of the acme_utils.zip package archive (found in «examples»/archives) into the empty «local»/myrepo package repository; the directory «local»/myrepo/acme/utils would then hold the contents of our acme.utils package.
Using repoman. Instead, we recommend performing this (trivial) installation step using a command-line tool known as xdc.tools.repoman—bundled with the XDCtools product you've already downloaded in Lesson 0. As the name suggests, repoman performs a variety of tasks related to managing package repositories; and you'll learn more about this handy tool in Lesson 2, where we'll populate multiple repositories with multiple packages.
For now, though, we'll just use a series of elementary repoman commands: 1 to first inventory our package archive; 2 to next extract its contents into our newly-created package repository; and 3 to finally inspect the results.
| 1 2 3 | %> xs xdc.tools.repoman -n «examples»/archives/acme_utils.zip acme.utils %> xs xdc.tools.repoman -x -v -r «local»/myrepo «examples»/archives/acme_utils.zip xdc.tools.repoman: extracting package(s)... xdc.tools.repoman: checking compatibility prior to extracting... xdc.tools.repoman: extracting acme.utils from «examples»/archives/acme_utils.zip xdc.tools.repoman: extracting «examples»/archives/acme_utils.zip to «local»/myrepo %> xs xdc.tools.repoman -n -p «local»/myrepo acme.utils |
Needless to say, the symbol «examples» seen here in the command input/output designates the actual directory where you've unpacked the examples back in Lesson 0; the symbol «local»/myrepo similarly refers to the location of our newly-created package repository.
Compared with using standard Windows or Linux tools to inspect the directory structure of acme/utils—whether archived inside acme_utils.zip or extracted into myrepo—the output of repoman -n at lines 1 and 3 enables you to view each RTSC package as a single logical entity rather than as a mass of physical files; you'll certainly come to appreciate this feature when managing multiple packages. Similarly, the output of repoman -x at line 2 hints at some of the extra steps taken by this tool beyond simply extacting acme_utils.zip; more to come in Lesson 2.
Locating packages in repositories
To review.... RTSC package contents must reside in a canonically-named package directory; but RTSC package directories can reside in arbitrarily-named package repositories. All of this then leads to the last of our basic concepts and the top of the RTSC packaging hierarchy—the package path, which is a list of package repositories ultimately used by the XDCtools to locate individual packages and to retrieve their contents for client application use.
And once again, RTSC defers to the Java classpath as a model for its own package location and retrieval mechanism.
Default package path. As it turns out, XDCtools will always define a package path—even if you've just installed the product as directed in Lesson 0. To verify, we'll use another command-line tool named xdc.tools.path to first display the (default) package path and then to list all RTSC packages currently found along this path.
|
|
Applying basic concepts we've already introduced, the output of the path -p command at line 1a suggests that the XDCtools product—installed in a directory we've referred to as «xdcroot»—itself incorporates a package repository named packages. The output of the path -n command at line 2a then alphabetically lists all of the RTSC packages found in this one repository alone—about 150 of them, if you've actually run the command yourself.
As a rule, the directory «xdcroot»/packages will always appear within the current package path—typically, at the end
Perhaps you're sensing a pattern here—virtually everything within the world of RTSC resides in some package, including hosted tools like xdc.tools.path and xdc.tools.repoman used to manage other RTSC packages. Written in XDCscript—the RTSC meta-language, which plays a central role for package producers and consumers alike—the special xs command located in «xdcroot» invokes these tools by locating their corresponding package directory which in turn holds the necessary XDCscript sources. The xs command forwards any remaining arguments after the package name to the application's main function. The application is the package, and vice versa.
Extending the package path. To quickly add our own package repository to the current package path—the final step in deploying the acme.utils package for use in client applications—simply assign the absolute directory name «local»/myrepo to the XDCPATH environment variable. To verify, re-run the earlier path -p and path -n commands.
|
|
As apparent from the output following line 1b, the special «xdcroot»/packages repository bundled with the XDCtools product itself appears after your own contribution(s) to the RTSC package path; the next Lesson explores some consequences of this ordering amongst the package repositories. And as apparent from the alphabetically-sorted output following line 2b, our acme.utils package has finally "made the list" in the eyes of the XDCtools product.
The XDCtools also include graphical variants of the command-line path and repoman tools, which you should eventually explore. As a first step, xs xdc.tools.path.sg will fire-up a GUI application—written in XDCscript, of course—that enables you to truly "see" all of the RTSC packages already found along the current package path. Enjoy!!
See also
| Managing the Package Path | Introduction to managing package paths |
| Command - xdc.tools.repoman | Repository management tool |
| Command - xdc.tools.path | Package path display tool |
| [printable version] | offline version generated on 04-Aug-2010 21:08 UTC | |
