Creating Configurable Content

From RTSC-Pedia

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

Creating Configurable Content

How to leverage the configuration process



During the configuration process, the RTSC configuration framework invokes specific package functions in response to commands in the user's script and the commands in loaded packages. As a result, it's important to understand which meta-domain package and module functions are invoked by the RTSC configuration framework, when these functions are called, and the context that exists when they are called. The sections below provide the details necessary for the content producer to fully leverage the RTSC configuration framework.

Configuration Process

The configuration process proceeds in a sequence of "phases":

  1. object model initialization
  2. user's configuration script runs
  3. all loaded packages are closed
  4. module state initialization is run for all "used" modules
  5. instance state initialization is run for all created instances
  6. config model validation is run for all loaded packages
  7. C code generation is run for all "used" modules

In each phase, meta-only XDCscript code defined by the user or the loaded packages is invoked. This script code manipulates a "configuration object model" which is ultimately used to generate a C source file and a linker command file that are integrated into an application's final build.

Package Functions

The following package functions are called during the configuration process and are optionally defined in the package's package.xs file:

  • init() — package initialization occurs when a package is loaded, before a user or any other package can read or write package's configuration parameters
  • close() — after the user's script is run, each package can act upon the current state of the configuration and make changes in the configuration
  • validate() — after all packages and module methods finish modifying the model, the model is "sealed" (made unmodifiable) and then each package can validate the configuration and possibly abort it, but nothing in the model can be changed at this point
  • getLibs() — if validation completes without any errors, getLibs() is called to get the libraries necessary to use this package
  • getSects() — if all of the libraries specified by getLibs() exist, getSects() is called to get package-specific linker section data which is placed in the generated linker command file along with the list of libraries specified by getLibs()

If you don't define one of these functions, a default implementation will be used instead. For detailed documentation of these functions see xdc.IPackage.


Module Functions

The following functions are optionally defined in each module's .xs file:

  • module$meta$init() — called right before the package's init() function, so its purpose is similar, but module specific initialization should be here.
  • module$use() — called after user's script, as a consequence of an xdc.useModule() call on the module. In most cases, the function module$use does not execute immediately within the xdc.useModule() call. The execution of module$use is delayed until the module's package is closing. However, an exception is made for modules whose packages are already closed at the time xdc.useModule() is called on them. In such cases, module$use executes immediately and it executes after the module's package close function is called. Changes in configuration parameters are allowed in module$use.
  • module$static$init() — target object for the module is initialized; no changes in configuration parameters are allowed here and is only called for target modules.
  • module$validate() — called for all modules in a package, before the package's validate() function; can be used to verify the consistency of values assigned to configuration parameters, but no changes in parameters are allowed. This function is only called if the module is used.
  • instance$meta$init() — invoked whenever create() is called, configuration can be changed.
  • instance$static$init() — invoked after closing to initialize instance object, no changes in configuration parameters are allowed; called only for instances of target modules.

For detailed documentation of these functions see the XDCscript Language Reference.

Order of Evaluation

The table below summarizes the order of evaluation of the methods optionally supplied by a package. Within a package, a module or an instance, these methods are guaranteed to be evaluated in top to bottom order, so package.init() for a particular package always runs before package.close() for the same package. In the same way module$meta$init() for a module always runs before module$use() for that module. When two methods appear in the same row, as is the case for package.close() and module$use(), no order is guaranteed even for package.close() and module$use() from the same package.

Each method name is followed by the id(s) of the phases in which it can be run. A method whose largest phase id is less than the minimum phase id of another method is guaranteed to run first. For example, all package validate() methods run after all instance$meta$init() calls.

Id Phase Package Module Instance
2 user's script module$meta$init [2-3]
init [2-3]
instance$meta$init [2-5]
3 package close close [3] module$use [3] instance$meta$init [2-5]
4 module init module$static$init [4] instance$meta$init [2-5]
5 instance init instance$static$init [5]
6 validation module$validate [6]
validate [6]
7 generation module templates [7]

Order of evaluation between packages is deterministic only to the extent that if package A references package B in any of its XDC spec files, or in any of the functions that can run in Phase 2, package A's module$use() and package.close() functions will be invoked first. If there are no references established before Phase 3, these two packages can be closed in any order. Note that if a reference is established in module$use(), it's too late to affect ordering because package.close() for B may have already run by the time module$use() in package A makes a reference to package B.

Ordering of phases also determines which xdc methods can and cannot be called within a particular phase. Any calls that would require going backwards to an already completed phase are not allowed. For example, module$static$init() functions invoked in the phase 4 cannot call xdc.loadPackage() on any new packages because the package's init() function, which can be called only in phases 2 and 3, would have to be called for those packages. Here is a summary of such limitations:

  • After the phase 3, all configuration parameters are sealed and cannot be changed
  • xdc.loadPackage() and xdc.useModule() can be called only in the first 3 phases
  • xdc.module() can always be called for modules in previously loaded packages, but only in the first 3 phases for modules from packages not being already loaded
  • Mod.create() can be called only in the first 5 phases
[printable version]  [offline version]offline version generated on 18-Aug-2017 00:08 UTC
Copyright © 2008 The Eclipse Foundation. All Rights Reserved
Personal tools
package reference