XDCscript - Package-Type.$patch

From RTSC-Pedia

Jump to: navigation, search
revision tip
—— LANDSCAPE orientation
[printable version]  [offline version]offline version generated on 18-Nov-2017 00:11 UTC

XDCscript - Package-Type.$patch

Patch a package method

Contents

Synopsis

 
 
var pkgType = xdc.om["«pkgName».Package"]; /* get «pkgName»'s type object */
pkgType.$patch(methodName, patchFxn);      /* replace «pkgName».methodName with patchFxn */

Parameters

methodName
a string that names a method in the xdc.IPackage interface; e.g., "getLibs".
patchFxn
an XDCscript function that is compatible with the method named by methodName; i.e., accepts the same parameters and returns an appropriate result.

Description

The $patch() function of a package's type object allows you to replace the package's implementation of any meta-domain method defined by the xdc.IPackage interface. This is done either to "patch" a broken implementation of a method (without having to update or change the existing package) or to add new functionality to a good implementation.

Since

This method was introduced in XDCtools release 3.15.

Examples

Patching broken methods.  In some cases it is necessary to manually fix a "broken" package. Although it is often easier to make the change directly in the broken package, $patch makes it possible to create a "patch" for a package that can be delivered independently and that does not change the broken package. For example, suppose you are using an old package whose getLibs() method is expecting an obsolete value from the target's isa property. You can create a package (say, patch), re-implement a function that can replace the broken getLibs(), and replace the broken method with this new function in the patch package's validate() method. This only requires three files (shown below):

  • package.xdc to define the patch package,
  • package.xs to implement both the new getLibs() method and the patch package's validate() method, and finally
  • package.bld to specify what to include in the patch package (in this case, nothing beyond the required files is necessary so package.bld is empty).

package.xs
 
 
 
 
 
 
 
 
 
 
 
 
function validate()
{
    var pkgType = xdc.om["some.broken.pkg.Package"];
    if (pkgType != null) {
        pkgType.$patch('getLibs', newGetLibs);
    }
}
function newGetLibs(prog)
{
    var libs = ...;    /* compute correct library to link with */
    return (libs);
}
package.xdc
 
package patch {}
package.bld
 
/* intentionally empty */

We patch the broken package in the patch package's validate() method because, when validate() is called, all packages that are part of a configuration are loaded and configured and no calls to getLibs() have yet been made.

To apply this "patch", clients simply load the patch package in their configuration script.

app.cfg
 
 
xdc.loadPackage('patch');
    :    /* rest of config script */

Hooking existing functions.  The $patch() function can also be used to monitor the return values of all getLibs() functions in a configuration. As we did in the example above, create a package named trace and implement the validate() function as shown below.

package.xs
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
function validate()
{
    for each (var pkg in xdc.om.$packages) {
        var pkgType = xdc.om[pkg + ".Package"];
        pkgType.$patch('getLibs', trace);
    }
}
function trace(prog)
{
    var libs = this.$oldFxn(prog); /* call previous getLibs() function */
    if (libs != null) {
        print("    will link: " + libs + " (from " + this.$name + ")");
    }
    return (libs);                 /* return the old getLibs() result */
}
package.xdc
 
package trace {}
package.bld
 
/* intentionally empty */

In this case, however, we need to be able to invoke the original getLibs() method and return its result. This is accomplished by first retrieving the previous getLibs() methods via the $oldFxn property which has been temporarily added to the this object for the duration of the call to trace().

The this object is the package object for the patched package, not the package that contains the trace() function.

As before, to apply this "patch", clients simply load the trace package in their configuration script.

app.cfg
 
 
xdc.loadPackage('trace');
    :    /* rest of config script */
[printable version]  [offline version]offline version generated on 18-Nov-2017 00:11 UTC
Copyright © 2008 The Eclipse Foundation. All Rights Reserved
Personal tools
package reference