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 1while still focusing upon the package path-repository-directory hierarchywe'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 bundlea 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 repositoriesand 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_71signifying, say, the MathSuite v2.71 product available from Charlie & Co. And while this top-level package may contain some important collateralsuch as release notesan 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 productsay, MathSuite v3.14as 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 compatibilitysame package name, same package contentdespite 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»/productsinto 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 foundincluding 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 applicationssuch 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 repositorythe one reported at line 4 of the last examplewe 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 applicationssuch as C language headers and librarieswithin 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_71a very real possibilitythe 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 indefinitelywith 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 dozensanother very real possibility.
As an alternative, we can leverage a fundamental property of each RTSC packageits globally-unique nameand consider merging multiple package repositories into one. With unique names like acme.utils and charlie.sqrtlib dictating correspondingly distinct directory pathsacme/utils and charlie/sqrtlibthese two packages could safely coexist within the same package repository. In theory, we could deploy all inbound packages within a single repositorysay, «local»/myrepowithout 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»/myrepothe 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 identicalwe'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 pathperhaps 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.sqrtlibthe version originally found in the «shared»/products/charlie/mathsuite_2_71/packages repositoryas 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»/myrepothe repository at the front of the package patheffectively 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 searchwhether the executable PATH, -I compiler flags, or the RTSC package path itselfultimately 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 productbundled 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 releasewith 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 toolor its GUI counterpart, the path.sg toolcan assist in locating duplicate packages found along the current package path as illustrated earlier. To remove any unwanted duplicateswhich would override access to a newer version of some packageuse 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 productwhich 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 packageswithout 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 manageableas well as to facilitate sharing amongst developersthe 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-systemincluding 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 patheach representing different combinations and permutations amongst multiple product bundlesone @«opt-file» can even reference another.
See also
TODO: write it
[printable version] | offline version generated on 04-Aug-2010 21:08 UTC |