xdc命令注解

最近一直在学习TI达芬奇芯片codec engine这一块,编译借助的命令是xdc,所以很有必要对xdc命令做一个详细的了解。

TI网站关于xdc命令解释

http://rtsc.eclipse.org/docs-tip/Command_-_xdc#Running_tests_in_multiple_packages



目录

  • Synopsis
  • Description
  • Options
  • Usage
  • Examples
  • Building a package
  • Building specific files
  • Running package tests
  • Building multiple packages
  • Running tests in multiple packages
  • Building and running for a particular target
  • Environment Variables
  • Exit Status
  • Files

Synopsis

xdc [-n] [-h] [-k] [-r[a]] [@opts-file] [goal ...] [-P[rRD] pkg-dir ...]

Description

The xdc command is used to build packages and executables that use packages. In its current implementation, xdc is nothing more than a command shell that invokes the GNU make utility with makefiles that are either part of XDCtools or generated as part of processing a package's build script (package.bld). As a result, any command line option supported by GNU make is also supported by the xdc command and integration of the xdc command into make based environments is particularly straightforward.

注:

Xdc命令是通过打包方式来编译包和可执行程序。

在目前的应用中,xdc通过makefile来编译程序代码,我们只需在终端上敲一下make就行。所以GNU make支持的任何命令选项同样被xdc 命令支持,一系列的xdc命令整合到一起就比较容易了。


In order to ensure that the xdc command can be used identically on any host platform, prior to executing GNU make, xdc defines two variables:

HOSTOS — the name of the host operating system ("Linux", "Windows", or "Solaris"), and
XDCROOT — the installation directory of the XDCtools containing the xdc command itself
To see the exact command that xdc will run, use the -n option.
 
% xdc -n
set PATH=«xdcroot»/bin:...
«xdcroot»/gmake -r -R HOSTOS=Linux XDCROOT=«xdcroot» -f «xdcroot»/packages/xdc/bld/xdc.mak

注:为了确保xdc命令能在不同的平台上一样应用,在执行GNU make 之前,xdc定义了两种变量

HOSTOS — 操作系统类型,比如:"Linux", "Windows", "Solaris"。

XDCROOT —XDCtools包含xdc命令的安装目录

Options

In addition to the options listed below, virtually any command line option supported by GNU make is also supported by the xdc command. See the GNU Make Options Summary section of the GNU make manual for the details of these options.


-h
display usage help and exit
-k

if an error occurs during a build, do not stop (keep building as much as possible)

-n

show the make command but don't execute it

-r[a]

Remake the specified package (or packages) using the XDCPATH and XDCROOT values that were used the last time the package(s) was built -- ignoring any values that may be present in the environment. If -ra is specified, rebuild using previous values of XDCARGS, XDCBUILDCFG, XDCPATH, XDCROOT, and XDCTARGETS; i.e, ignore any changes to environment variables that would normally trigger the package to be rebuilt.

-P[rRD] pkg ...

Build specified goal(s) in all directories named after -P that contain a build script (i.e., package.bld); if -PR is specified, xdc recursively descends into all specified directories and builds in any package directory that contains a build script; if -PD is specified, xdc builds in the specified package directories and the package directories of all other packages "required" by these packages; if -Pr is specified, xdc recursively descends into all specified directories and builds any package whose repository is one of the named directories.

--xdcpath=path

Set the XDCPATH environment variable to path. See Environment Variables for a complete description of this variable. This option is equivalent to passing "XDCPATH=path" on the command line.

@<opts-file>

read the specified options file, <opts-file>, and include its contents as arguments to xdc. Each line in the file corresponds to exactly on argument passed to to xdc. No interpretation of the line is done unless the line is another @<file>; in this case, the line is (recursively) replaced with the lines from <file>.

注:

除了下面列出的,几乎所有的GNU make的命令行选项支持选项XDC命令也支持。

请参阅GNU手册里对GNU选项部分的细节。

-h

显示使用帮助并退出

-k

在编译过程中出现错误,尽量保持继续编译,不要停下来

-n

显示make时的命令,但并没有执行

-r[a]

XDCPATH和XDCROOT变量值指定的包由于新生成的就会被重新make—忽略在环境中任何出现的值。如果-ra被指定,将根据之前XDCARGS, XDCBUILDCFG, XDCPATH, XDCROOT, 和 XDCTARGETS各个值重编译;例如,忽略任何对环境变量值的改变,这些值有可能会是包重新生成。

-P[rRD] pkg ...

如果有-P选项的话,将编译所有指定的目录。

如果选项是-PR,xdc将递归下降到指定的目录,根据构建脚本建立起包。

-PD: xdc编译指定的目录和所有其它包的包目录(所有其它包是那些包所需要的)

-Pr: xdc将将递归下降到所有指定的目录并编译任何包,那些包是指定的目录之一。

--xdcpath=path

设置XDCPATH环境变量可以指定包含的路径。看这个环境变量的详细描述。这个选项在命令行上以"XDCPATH=path"出现。

@<opts-file>

读取指定的选项文件,即<opts-file>,作为xdc的参数。

文件中每一行的参数对应准确地传递给xdc。

除非这一行是另外一个文件,否则这一行将不会被解析。

在这种情况下,多行替代了一行。

Usage

Any option passed on the xdc command line that is not listed above is passed directly to the underlying invocation of GNU make. In this way, one can control the build process with as much flexibility as a normal GNU make. In particular, the goals specified on the command line may be any file that make knows how to build.

Although it is always possible to name one or more specific buildable files on the xdc command line, it is often desirable to build collections of executables or libraries or run collections of tests. For example, building a test suite consisting of hundreds of executables would be difficult if each program had to be explicitly named on an xdc command line.

The xdc command supports a number of build goals that facilitate the building of collections of files. The following table summarizes some standard build goals supported by the xdc command.

Goal Description
  • all builds all package files and all executables; this is the default goal if no goals are specified on the command line.
  • clean removes all generated files
  • release create the default release; an archive (tar or zip) containing all files that are to be distributed to a consumer of the package.
  • test runs all package tests declared in the package's build script
  • .make builds the generated makefiles only
  • .libraries builds all libraries exported by this package
  • .executables builds all executables declared in the package's build script
  • .interfaces builds the package's schema and generates all header files for interfaces exported by the package
In addition to the target independent goals above, target specific goals are also supported. These goals allow one to restrict a build to just the libraries for a particular target, for example. In addition, these goals are used internally to prevent unnecessarily building libraries for all targets before building a specific executable. The following table summarizes the target specific goals currently supported.

Goal Description
  • all,trg builds all libraries and all executables for the target whose suffix is trg.
  • clean,trg removes all generated files for the target whose suffix is trg.
  • release,name create the release named name.
  • test,trg run all tests for all executables built using the target whose suffix is trg.
  • .libraries,trg builds all libraries for the target whose suffix is trg
  • .executables,trg builds all executables for the target whose suffix is trg
The -P, -PR, and -Pr options are useful when working with multiple packages. Not only do they allow one to avoid building each package using a separate command, they also automatically handle any package inter-dependencies. A package may depend on another package; for example, any package that contains a program depends on at least one platform package. If two or more dependent packages are under development at the same time, it is important that the interfaces for the packages referenced are built before any libraries referencing these packages are built and that any libraries referenced are built before linking any executable. Thus, when building multiple packages, the xdc command builds the packages in several "phases"; it first builds all interfaces for all packages, then all libraries for all packages, and finally, all executables for all packages. By making several passes over the packages, it is possible to simultaneously develop multiple packages without having to worry about package build order due to inter-package references (which are subject to change).

Examples

Building a package. 

 The following command will remove all generated files from the package located in the current working directory.
% xdc clean
注:在当前工作目录里,下面命令将移除所有生成的包


To build all files for the package in the current working directory:
% xdc

注:在当前工作目录里,编译所有文件生成包

Although the command above builds the files necessary for the package producer to use it in their build environment, it does not build the files necessary for clients of the package to install and maintain multiple releases of the package. The following command builds a releasable form of the package containing all necessary dependency and compatibility information needed by "outside" clients of the package:
% xdc release

注:虽然上面的命令编译文件(包生成者有必要在编译环境中使用这个命令),不过这个命令不会编译文件(包的客户端需要安装和维护多个版本的包)

 下面的命令建立一个发布的包,该包包含所有必要的依赖和兼容性信息是其它包客户端所需要的

Building specific files.  While it is valuable to (re)build a package in its entirety, during development, it is often more convenient to build a specific file. The xdc command allows one to specify any generated file as the goal to be built. For example, the following command will build the program Hello.x62 and files unrelated to this program will not be built.
% xdc Hello.x62

注:编译生成可执行的Hello.x62,其它不相关的将不会被生成


It is also possible to name several goals and, again, xdc will only build the files required to create the build goals named. For example, the following command will build both executables Hello.x62 and Hello.x62e.
% xdc Hello.x62 Hello.x62e

注:下面的命令将建立既的可执行Hello.x62和Hello.x62e。

Running package tests.  The RTSC build environment supports the ability to not only build executables and packages but also run executables. The RTSC environment defines a test as an executable and a set of command line arguments for the executable. Tests may be specified in the package's build script and every program defined in a package has one implicitly created test; the executable with no command line arguments. The xdc command allows one to easily run a package's tests.

The following command runs all tests defined by the package in the current working directory. 
% xdc test

As with building individual files, it is often desirable to run individual tests. The following command runs the implicitly created test for the Hello.x62 executable.
% xdc Hello.x62.test

Building multiple packages.  The following command will remove all generated files from the packages pkg1, pkg2, and pkg3 located in the current working directory.
% xdc clean -P pkg1 pkg2 pkg3

To build all files in multiple packages:
% xdc all -P pkg1 pkg2 pkg3

Because the build goal all is the default goal, the following command is equivalent to the one above.
% xdc -P pkg1 pkg2 pkg3

Note that the xdc command will silently ignore directories that do not contain a package build script (package.bld). Thus, even if a directory contains sub-directories that are not package directories it is possible to build all packages contained in this directory using a wildcard. Suppose, for instance, that the directory named examples contains multiple sub-directories and only some are package directories. It is possible to build all packages in the examples directory with the following command.

% xdc -P examples/*
Since a package's name must match the directory names containing the package, it is not uncommon for packages to be located at different levels of a directory tree or even inside other packages. In these cases, it is desirable to be able to build all packages contained under a specified root directory. The following command builds all packages located under the examples directory.

% xdc -PR examples
In some situations you may want to limit the packages built to only those whose repository is a specific directory. Suppose, for example, you have a package named bundle that, as part of its build, creates a "temporary" package or installs another package in a sub-directory of bundle. In this case, using "xdc -PR" might not be feasible because the "temporary" package will be found and built (or cleaned) by the top level build and this will likely conflict with bundle's manipulation of this "temporary" package. The following command builds all packages located under the examples directory whose repository is also examples.

% xdc -Pr examples
Rather than build all packages found at or below a specified directory, it is sometimes more efficient to build a specified package and (recursively) any of its prerequisites. The following command builds the package in the specified directory and any prerequisite packages declared by the "requires" statement in the package's specification file (i.e., package.xdc).

% xdc -PD examples/basic/vers/app
By default, if an error occurs during the build of any package the xdc command will terminate the build and not attempt to build other packages. While this is convenient during interactive builds, during an overnight build of many packages it is preferable to continue building as much as possible. In the morning, one can correct the errors and re-execute the command. Only goals that failed to build or those that depend on the fixed files will be rebuilt.


To prevent xdc from stopping on the first error in the example above, use the -k option.
% xdc -k -PR examples


Running tests in multiple packages.  In addition to building multiple packages at a time, it is also valuable to run all tests for multiple packages using a single command. A regression test suite can be structured as a collection of packages, for example. The following command runs all tests for the packages pkg1, pkg2, and pkg3 located in the current working directory.
% xdc test -P pkg1 pkg2 pkg3


Since tests have a tendency to fail (otherwise they are not good tests), it is often valuable to continue running all tests even if a test fails. This is especially true when running over-night regression test suites containing hundreds of tests. The following command runs all tests and continues even if one or more tests fail.
% xdc -k test -P pkg1 pkg2 pkg3


Building and running for a particular target.  In the examples above, we built and ran executables for all targets. Recall a target defines a CPU ISA and a compiler runtime model (big endian, little endian, near, far, etc.). Since packages often need to support multiple targets, it is often desirable to restrict a build or a test to a particular target. The xdc command supports target specific versions of the build goals all, clean, test, .libraries, and .executables.
The following command runs only the tests for the target whose suffix is "62" for all packages in the examples directory and tries to run each test even if a test fails.
% xdc -k test,62 -P examples/*


The following command removes all generated files related to the target whose suffix is "62" for all packages in the examples directory.
% xdc clean,62 -P examples/*


The following command builds all generated files related to the target whose suffix is "62" for all packages in the examples directory.
% xdc all,62 -P examples/*

Environment Variables

In addition to the command line options, the xdc command also uses the following environment variables to control its behavior. Except for XDCPATH, XDCARGS, and XDCBUILDCFG, no environment variable changes the contents of any goal produced by xdc; the results of a build are unaffected by environment variables (unless a user-specified tool invoked by xdc is affected by an environment variable).

注: 除了options影响xdc命令编译,还有环境变量也会产生影响,包括XDCPATH, XDCARGS, 和 XDCBUILDCFG


XDCARGS
this variable names arguments that are passed to the package's build script, package.bld. The package's build script references the arguments from the global array arguments. For example, the command
xdc XDCARGS="foo bar"
causes the arguments array (in the package build script) to be initialized as follows:
arguments[0] = "foo";
arguments[1] = "bar";

注: XDCARGS和package.bld文件有关,指定了编译参数

XDCBUILDCFG
if defined and the file "./config.bld" does not exist, this variable names a file that will be used in-lieu of the config.bld file found along the "import" path (i.e., ".;$(XDCPATH);xdcroot;xdcroot/etc") to configure the build environment prior to running a build script.
However, if XDCBUILDCFG is specified in the command line, any package specific "./config.bld" will be ignored. Thus, with respect to specifying which config.bld to use, the package has precedence over the environment variable but the command line has precedence over the package.
Why distinguish between setting XDCBUILDCFG on the command line versus setting it in the environment? Some packages need to override the setting of XDCBUILDCFG; e.g., in order to clean and rebuild a package of targets (which may be referenced by the file named by the environment variable XDCBUILDCFG), the package may define a "local" config.bld that does not reference any targets.

注: XDCBUILDCFG和config.bld文件有关,config.bld文件要放在xdc编译的同一工作目录里。

XDCOPTIONS
string of options that affect the messages displayed by xdc while it runs. Only four options are currently supported: "g", "v", "q", and "t".
If this string contains "-g" or "g", an interactive debugger is started allowing you to single step debug your package's build scripts
If this string contains "-v" or "v", each command executed by xdc is displayed before execution. This makes it easy to create "shell scripts" that re-create the build without the need for the xdc command or make.
If this string contains "-q" or "q", banners normally displayed during multi-package builds are not displayed. Since the banners contain date and time information, this option is useful when the output from the xdc command must not vary between successive builds; e.g., when running regression tests.
If this string contains "-t" or "t", banners are displayed during multi-package builds but no dates or times are displayed. This option is useful when running regression tests on a fixed set of packages; when an error occurs, the banners make it easy to tell which package(s) failed.

注: XDCOPTIONS = v 这个参数用的比较多,用于显示编译的过程

XDCPATH
a string of ";" separated directories that contain packages. This path is used to locate packages that are used by the package being built.
It is usually a mistake to put a relative path in the XDCPATH environment variable. Relative paths in XDCPATH reference directories relative to the package being built rather than the directory where the xdc command was invoked. Thus, a relative path will refer to a different repository for each package being built.
It is possible, however, to use the "^" character in the XDCPATH definition to refer to the current package's repository. So, if you have a repository that is always in a fixed location relative to all of your packages repositories, it is possible to create a single XDCPATH setting that 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
Note that multiple versions of the same package can appear along the XDCPATH. The package path can name multiple "package repositories" which 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 will be used. Thus, even if two packages with the same name appear in the package path, only one will ever be found; i.e., the first one in the order specified in the package path.


XDCTARGETS
a string of white space separated target names that name all supported build targets. Each name is interpreted as a regular expression and is used to select from the set of all available targets included in the build "startup" script (see config.bld in the Files section below). This environment variable can be used to re-build packages with a subset of the available targets. The current set of targets include the following:

  • ti.targets.C54, ti.targets.C54_far
  • ti.targets.C55, ti.targets.C55_large
  • ti.targets.C28_large
  • ti.targets.C62
  • ti.targets.C62_big_endian
  • ti.targets.C64
  • ti.targets.C64_big_endian
If a specified target name does not match any available target, the prefix "ti.targets." is added and the match is retried. If no match occurs, a warning is displayed and processing continues uninterrupted. Thus, the target "ti.targets.C62" may be abbreviated to just "C62"
Any change to an environment variable that may affect the results of the build will trigger a rebuild of the goals that may be affected (as well as some that may not be affected).


Note that these environment variables may be specified on the xdc command line. In this case, the value specified on the command overrides any value in the environment. For example, the following command causes the package in the current working directory to be built for just the C62 and C54 targets.
xdc XDCTARGETS="C62 C54"

Exit Status

The exit status of the xdc command is the exit status of the underlying make command whenever make is executed; otherwise, the following exit values are returned:

0 Successful completion.
1 An error occurred.

Files

config.bld
The build model "startup" script; this script, located along the import path ".;$(XDCPATH);xdcroot;xdcroot/etc", configures the build model's modules so that common settings can be shared among multiple package build scripts. It is possible to override this behavior using the XDCBUILDCFG environment variable.
package.bld
The package's build script; this script, located in the package's working directory, specifies all of the physical files (libraries, executables, etc.) that are part of the package.
.xdcenv.mak
This file is a generated file that captures the environment setting that can affect the contents of the generated makefile; changes to this file trigger a re-build of the makefile.









评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值