From RTSC-Pedia
 | [printable version] [offline version] | offline version generated on 04-Aug-2010 21:08 UTC |  |
Managing the Package Path
Introduction to managing package paths
Contents |
The Package Path
Source code often needs to reference files contained in packages. Files contained in a package are always found along the "Package Path", which is simply a semicolon-separated list of package "repositories". A repository is just a directory that contains installed packages. The Package Path is always defined as follows:
| Package Path | |
| | «XDCPATH»;«XDCROOT»/packages;^ |
In this definition, «XDCPATH» is a semicolon-separated set of repositories specified by the user (either on the command line, within an IDE project's settings, or via an environment variable named XDCPATH). «XDCROOT»/packages is the repository of packages included with the XDCtools product. The '^' character denotes the current package's repository (if there is a current package). For most tools, the current package is defined as the package named by a package.xdc file in the current working directory. If no such file exists, then any repository name containing the '^' character expands to the empty string "".
For example, when no current package exists, a package path defined with «XDCPATH» set to "^/../imports" is just «XDCROOT»/packages. On the other hand, if there is a current package and its repository is /home/me/work/src then the package path is /home/me/work/imports;«XDCROOT»/packages;/home/me/work/src.
| «XDCPATH» = ^/../imports | |
|---|---|
| Package Path (no current package) | Package Path (current package repository = /home/me/work/src) |
| «XDCROOT»/packages | /home/me/work/imports;«XDCROOT»/packages;/home/me/work/src |
Because «XDCROOT»/packages is always part of the package path, XDCtools can automatically find its own packages. However, if you have other products that are delivered as a packages (such as DSP/BIOS), you need to set the «XDCPATH» to include the repositories containing packages you require.
You may be wondering why the definition of the Package Path puts the XDCtools packages repository in front of the current package's repository rather than the reverse. By placing «XDCROOT»/packages ahead of the current package's repository, you can't "override" any of the packages necessary for the proper operation of XDCtools by inadvertently creating a package with the same name as one in «XDCROOT»/packages. Moreover, if you ever need to switch the order this can be done by simply setting «XDCPATH» to "^".
All source files, whether they are part of a package or your application, should always reference files contained in a package by prefixing the file name with the package's directory name. For example, to include the Task.h header in the ti.sysbios.knl package, your source files should #include <ti/sysbios/knl/Task.h>.
When compiling your sources, you should add a -I option for each repository named in the Package Path in the same order that they appear in the Package Path. Following this pattern allows you to easily add/remove/override packages without having to update your build system. You can simply install (or remove) a package into one of the repositories, add (or remove) the reference from your sources, and rebuild.
Since virtually all build tools support an option similar to -I, this pattern works for linker command files, assembly language files, scripts, and even makefiles.
The XDCPATH prefix
XDCPATH syntax
XDCPATH syntax. In the Package Path, you control the XDCPATH portion. This prefix is a string of ';' separated directories (repositories) that contain packages.
All directories referenced in XDCPATH must use forward slashes (/) as separators instead of the Windows-standard backslash (\). For example, use "c:/os;c:/drivers;c:/framework".
XDCPATH contents
XDCPATH contents. The definition of XDCPATH, like that of your PATH command shell environment variable, usually names a sequence of absolute directory paths. This enables your source files to avoid the use of absolute paths when referencing files contained in packages and, as a result, keeps your sources "portable" to other development environments. This is especially useful when exchanging packages between different developers.
It is usually a mistake to use a relative path in the XDCPATH prefix. Relative paths in XDCPATH reference directories relative to the current working directory but package names often have differing number of levels; e.g., xdc and xdc.runtime. Thus, a fixed relative path refers to a different repository when working with different packages that are installed in the same repository.
To avoid this problem, you should use the '^' character in the XDCPATH definition to refer to the "current package's" repository. Using the "^" character allows you to specify path that are relative to the current package's repository rather than the current working directory. So, if you have a repository that is always in a fixed location relative to all of your package's repositories, it's possible to create a single XDCPATH setting that works for all your packages and does not include any absolute paths.
Suppose, for example, that your build system places all prerequisite packages in an "imports" repository prior to building the packages in a "src" repository and the imports and src repositories are sibling directories in the file system. The following XDCPATH setting is sufficient to build all packages in the src repository.
| | set XDCPATH=^/../imports |
Defining XDCPATH
Defining XDCPATH. Since the Package Path is central to the operation of package-based tools and the XDCPATH prefix is how you control the Package Path, there are several ways to define XDPATH so as to make it easy to control XDCPATH from virtually any development environment. XDCPATH can be defined by
- an environment variable;
- the --xdcpath option of any command-line tool; or
- within a command-line option file
If XDCPATH is specified on the command-line and as an environment variable, the command line definition always takes precedence.
Examples
Examples. XDCPATH can be defined by simply setting an environment variable named XDCPATH.
| | set XDCPATH="^/../imports;/usr/local/packages" |
If you do not want to specify XDCPATH using and environment variable, you can use the --xdcpath option for any command-line tool. Again, specifiying --xdcpath on the command line overrides any definition in the environment.
| | xdc --xdcpath="^/../imports;/usr/local/packages" |
Alternately, you can place the --xdcpath command-line option in a text file, say mysettings.txt, and specify the file on the command line of the xs and xdc commands. This is useful in makefiles, which can define a dependency on the text file so that the appropriate files are properly rebuilt whenever the package path changes. Consider the following command-line option file.
| mysettings.txt | |
| | --xdcpath ^/../imports;/usr/local/packages |
The xs command line would reference this file as shown below.
| | xs @mysettings.txt |
Similarly, the xdc command also accepts command-line option files.
| | xdc @mysettings.txt |
Managing multiple versions of the same package
Multiple versions of the same package can appear along the Package Path. The Package Path can name multiple repositories that can contain a package directory with the same name. When searching for a package, the first repository that contains a directory matching the package's name is used. Thus, even if two packages with the same name appear in the package path, only one will ever be found-the first one in the order specified in the package path.
Thus, it is possible to quickly update selected packages by adding an "updates" repository at the front of XDCPATH. If the updates are successful, you can "permanently" remove the old versions; otherwise you can quickly revert to the previous versions by simply removing the updates repository from XDCPATH.
| [printable version] [offline version] | offline version generated on 04-Aug-2010 21:08 UTC | |
