From RTSC-Pedia
 | [printable version] | offline version generated on 04-Aug-2010 21:08 UTC |    |
RTSC Packaging Primer/Lesson 2
Repository management — deploying charlie_mathsuite_2_71
Building upon the basic concepts of RTSC packaging introduced in Lesson 1—while still focusing upon the package path-repository-directory hierarchy—we'll once again install an inbound package archive and then deploy its contents for use within the sample application covered in Lesson 3. Unlike acme.utils, however, the (somewhat oddly-named) charlie_mathsuite_2_71 package actually constitutes what RTSC informally terms a product bundle—a top-level "wrapper" package whose contents in turn include a repository pre-populated with other RTSC packages.
Though seemingly still a "toy" example, deploying the charlie_mathsuite_2_71 product bundle illustrates most of the common practices followed by content consumers when managing multiple packages installed across multiple repositories—and even multiple variants of the package path composed from distinct sets of package repositories.
Contents |
Working with product bundles
To gain some more insight into its internal organization, we'll once again invoke the repoman -n command to now inspect the charlie_mathsuite_2_71.zip package archive file found in «examples»/archives.
| 1 2 | %> xs xdc.tools.repoman -n «examples»/archives/charlie_mathsuite_2_71.zip
charlie_mathsuite_2_71
packages/
charlie.sqrtlib
charlie.sqrtlib.samples |
As you might have guessed, the output at line 1 confirms the presence of a RTSC package with the (somewhat odd) name of charlie_mathsuite_2_71—signifying, say, the MathSuite v2.71 product available from Charlie & Co. And while this top-level package may contain some important collateral—such as release notes—an internal packages repository flagged at line 2 appears to hold the "real" product content within other charlie.* packages.
Taking this scheme one step further, Charlie & Co. would deliver a future version of this product—say, MathSuite v3.14—as a (different) RTSC product bundle named charlie_mathsuite_3_14, though internally structured along similar lines. In effect, a top-level product "wrapper" package like charlie_mathsuite_2_71 becomes a one-shot, never re-released under the same name by its supplier; by contrast, "bundled" packages like charlie.sqrtlib would hopefully maintain backward compatibility—same package name, same package content—despite any enhancements from one product version to the next. More on this topic in Lesson 9.
Following a similar progression in how we handled acme.utils in the last lesson, let's imagine a (different) package repository—«shared»/products—into which we'll install charlie_mathsuite_2_71 using the repoman -x command.
| 3 | %> xs xdc.tools.repoman -x -v -r «shared»/products «examples»/archives/charlie_mathsuite_2_71.zip xdc.tools.repoman: extracting package(s)... xdc.tools.repoman: checking compatibility prior to extracting... xdc.tools.repoman: extracting charlie_mathsuite_2_71 from «examples»/archives/charlie_mathsuite_2_71.zip xdc.tools.repoman: extracting «examples»/archives/charlie_mathsuite_2_71.zip to «shared»/products %> xs xdc.tools.repoman -n -p «shared»/products charlie_mathsuite_2_71 |
The output of the repoman -n command at line 3 appears to have omitted the internal packages repository reported earlier at line 2, where we inspected the charlie_mathsuite_2_71.zip archive prior to installation. But now let's stop and think about it: the other charlie.* packages aren't rooted within «shared»/products at all, but rather in a different repository found at «shared»/products/charlie/mathsuite_2_71/packages.
Using a different form of the path command from what we'd illustrated in the previous lesson, we can discover "interior" packages such as charlie.sqrtlib by recursively searching arbitrary directories and then displaying a full slate of information about each package found—including the full path to its parent repository.
| 4 | %> xs xdc.tools.path -PR «shared»/products Package Name: charlie_mathsuite_2_71 Repository: «shared»/products .... Package Name: charlie.sqrtlib Repository: «shared»/products/charlie/mathsuite_2_71/packages .... Package Name: charlie.sqrtlib.samples Repository: «shared»/products/charlie/mathsuite_2_71/packages .... |
Adding versus merging repositories
To complete the task, we'll now deploy the charlie_mathsuite_2_71 product for use within client applications—such as the program we'll develop in the next lesson, which happens to depend upon the contents of the charlie.sqrtlib package as well as acme.utils. Since charlie.sqrtlib already resides within a package repository—the one reported at line 4 of the last example—we can simply append this directory to the XDCPATH environment variable and inspect the results by invoking path -p and path -n commands.
| 1a 2a | %> xs xdc.tools.path -p «local»/myrepo;«shared»/products/charlie_mathsuite_2_71/packages;«xdcroot»/packages; %> xs xdc.tools.path -n acme.utils charlie.sqrtlib charlie.sqrtlib.samples gnu.gdb.jserver gnu.targets.arm ... xdc.utils |
Note that the current package path echoed after line 1a does not include the «shared»/products package repository, hence charlie_mathsuite_2_71 itself does not appear amongst the currently deployed packages listed after line 2a. As suggested earlier, you'd typically find programming artifacts needed by client applications—such as C language headers and libraries—within a "bundled" package such as charlie.sqrtlib in lieu of top-level "wrapper" packages crafted for a particular product version.
Scaling the pattern. Should you ever obtain additional product packages from others structured along lines similar to charlie_mathsuite_2_71—a very real possibility—the process of deployment could take a fairly predictable course:
- extract the new product package archive into the existing «shared»/products directory;
- locate the "interesting" package repository(s) bundled with the product; and
- append these additional repository locations to the current package path.
In theory, this pattern scales indefinitely—with the advantage that the package path naturally reflects the present roster of product releases through repository filenames like «products»/charlie/mathsuite_2_71/packages. In practice, though, the sheer length of the RTSC package path might become a limiting factor in your development environment as the number of product bundles reaches into the dozens—another very real possibility.
As an alternative, we can leverage a fundamental property of each RTSC package—its globally-unique name—and consider merging multiple package repositories into one. With unique names like acme.utils and charlie.sqrtlib dictating correspondingly distinct directory paths—acme/utils and charlie/sqrtlib—these two packages could safely coexist within the same package repository. In theory, we could deploy all inbound packages within a single repository—say, «local»/myrepo—without conflict; and we'd certainly have a shorter package path.
To illustrate, let's first invoke a repoman -c command variant to copy all of the charlie.* packages into the «local»/myrepo—the only repository we'd then have to include on the package path.
| | %> xs xdc.tools.repoman -c -v -r «local»/myrepo -p «shared»/products/charlie_mathsu.../packages charlie.* xdc.tools.repoman: copying charlie.sqrtlib from «shared»/products/cha.../packages to «local»/myrepo xdc.tools.repoman: copying charlie.sqrtlib.samples from «shared»/products/cha.../packages to «local»/myrepo |
Next, let's invoke the same forms of the path command used earlier and then compare the results.
| 1b 2b | %> xs xdc.tools.path -p «local»/myrepo;«xdcroot»/packages; %> xs xdc.tools.path -n acme.utils charlie.sqrtlib charlie.sqrtlib.samples gnu.gdb.jserver gnu.targets.arm ... xdc.utils |
Despite a shorter package path reported at line 1b compared with line 1a above, the deployed packages listed after lines 2a and 2b remain identical—we'd successfully deploy acme.utils and charlie.sqrtlib using either scheme.
Similar tradeoffs occur when managing executable programs on your host computer, assuming these programs have distinct names: do we deploy most if not all programs in a single directory already in your search PATH; or do we maintain separate directories for distinct groups of programs organized (say) along product lines, but then continually expand the search PATH with each new set of programs.
Handling per-package updates
Though inconsequential so far, you should understand that the XDCtools perform an ordered search of the package path when locating individual packages. Returning to the original deployment scenario at line 1a of the earlier example, consider what might happen if (say) a version of charlie.sqrtlib exists in more than one repository on the package path—perhaps Charlie & Co sent you a "new-and-improved" charlie.sqrtlib package in a standalone form, which you'd install into «local»/myrepo following the same procedure used with acme.bench.
To help manage cases when updates arrive on a per-package basis, the unabridged output of the path command would here draw attention to the second occurrence of charlie.sqrtlib—the version originally found in the «shared»/products/charlie/mathsuite_2_71/packages repository—as a "duplicate" worthy of closer inspection.
| 1 2 | %> xs xdc.tools.path Package Name: acme.utils Repository: «local»/myrepo .... Package Name: charlie.sqrtlib Repository: «local»/myrepo Release Name: charlie_sqrtlib Label: default Compatibility Key: 1, 0, 4, 3 Date: 08/08/2008 08:08 Package Name: charlie.sqrtlib Repository: «shared»/products/charlie/mathsuite_2_71/packages Release Name: charlie_sqrtlib Label: default Compatibility Key: 1, 0, 2, 6 Date: 07/07/2007 07:07 .... |
Beginning in Lesson 4, we'll have more to say about the attributes reported here (Release Name, Label, Compatibility Key) and how package producers can effect their respective values. Suffice it to say, the version of charlie.sqrtlib reported at line 1 does indeed appears "more recent" than the version bundled with charlie_mathsuite_2_71 and reported at line 2.
In this particular deployment, client application programs requiring C language headers and libraries logically contained inside of the charlie.sqrtlib package would find these under the charlie/sqrtlib package directory rooted in «local»/myrepo—the repository at the front of the package path—effectively overriding the (older) original version under «shared»/products co-located with the rest of the charlie_mathsuite_2_71 product bundle.
Any manner of ordered directory search—whether the executable PATH, -I compiler flags, or the RTSC package path itself—ultimately gives you the flexibility to supersede a "shared" artifact seen by many (whether a program, a header, or a package) with a "local" artifact of the same name. Our use of «local»/myrepo as a staging ground for deploying product patches alongside standalone packages proves invaluable for this task; anyone working with RTSC should likewise maintain their own private repository at the front of the package path.
Defining alternate package paths
Suppose, now, Charlie & Co delivered a new release of their MathSuite product—bundled as charlie_mathsuite_3_14 and perhaps containing versions of charlie.sqrtlib with expanded functionality as well as entirely new packages not offered before. Following protocol, we'd extract the corresponding package archive file into the same «shared»/products directory already holding the current product release—with no conflict here, since the top-level "wrapper" packages have distinct names tied to MathSuite v2.71 versus MathSuite v3.14.
Deploying the latest MathSuite product then requires us to alter the current package path, replacing repositories rooted under «shared»/products/charlie_mathsuite_2_71 with alternates under .../charlie_mathsuite_3_14. We'd also need to remove any isolated updates to packages like charlie.sqrtlib which might currently reside in other repositories like «local»/myrepo and inadvertently preempt an even more recent version of this package bundled with the latest product.
The path tool—or its GUI counterpart, the path.sg tool—can assist in locating duplicate packages found along the current package path as illustrated earlier. To remove any unwanted duplicates—which would override access to a newer version of some package—use the repoman -d command whose additional arguments name the repository and the package(s).
But after making all of these adjustments to the package path (enabling us to start working with MathSuite v3.14) the challenge now becomes one of simultaneously supporting existing applications tied to the earlier MathSuite v2.71 product—which requires the previous form of the package path, prior to making any changes. Clearly, the XDCtools can only see one package path at a time; but can we at least streamline the task of "switching context"—changing the set of currently deployed packages—without having to constantly update the XDCPATH environment variable.
As it turns out, the underlying xs command we've used all along to launch tools like path or repoman supports a special --xdcpath option enabling us to explicitly enumerate the package repositories comprising the current package path; if present on the command-line, the --xdcpath option would override the current XDCPATH environment variable.
To keep command-line input manageable—as well as to facilitate sharing amongst developers—the xs command also accepts an @«opts-file» argument. For example, we can first populate oldpath.opts and newpath.opts with different settings for the package path and then invoke xdc.tools.path with each.
| oldpath.opts | |
| | --xdcpath=«local»/myrepo;«shared»/products/charlie_mathsuite_2_71/packages |
| newpath.opts | |
| | --xdcpath=«local»/myrepo;«shared»/products/charlie_mathsuite_3_14/packages |
| 1 2 | %> xs @oldpath.opts xdc.tools.path acme.utils charlie.sqrtlib charlie.sqrtlib.samples ... xdc.utils %> xs @newpath.opts xdc.tools.path acme.utils charlie.sqrtlib charlie.sqrtlib.samples charlie.triglib ... xdc.utils |
Needless to say, these *.opts files can reside anywhere within your file-system—including centrally-managed project-wide directories like «shared» where judicious use can ensure consistent package deployment across of team of software developers. To handle even more complex variations of the package path—each representing different combinations and permutations amongst multiple product bundles—one @«opt-file» can even reference another.
See also
TODO: write it
| [printable version] | offline version generated on 04-Aug-2010 21:08 UTC | |
