SCons 构建工具完整帮助手册

需积分: 9 12 浏览量更新于2024-06-30 收藏 1.99MB PDF 举报

"scons 帮助手册 pdf(全)" 是一份详尽的文档，主要针对SCons这一构建工具，适用于嵌入式开发环境，特别是与scons、rtt (Real-Time ThreadX) 和rtthread操作系统相关的项目。该手册包含了构建系统如何使用SCons进行编译、链接以及其他构建任务的详细指导。 SCons是一个开源的构建工具，用Python编写，它替代了传统的Makefile系统，提供了更加灵活和跨平台的构建解决方案。在嵌入式领域，SCons能够帮助开发者管理不同平台和工具链下的编译过程，确保代码在多种环境下的一致性。从给出的部分内容来看，手册涵盖了SCons在实际项目中的应用，例如： 1. `./src/agg_renderer.os` 和 `./agg/libagg.a` 暗示SCons可能在处理图形库如Anti-Grain Geometry (AGG) 的编译，这通常用于2D图形渲染。 2. `bindings/python` 目录下的文件表明SCons也涉及到了Python绑定，使得C++库如Mapnik可以与Python代码交互，这对于数据处理和地图渲染是常见的做法。 3. `./plugins/input/shape` 和 `./plugins/input/raster` 目录则涉及到输入插件，可能涉及到地理空间数据的读取，如ESRI Shapefile和栅格数据，这对于地理信息系统(GIS)开发非常重要。 4. `./src/... .os` 文件通常是编译后的对象文件，SCons负责管理和编译这些源代码文件。 5. `./src/... .o` 文件是GCC编译器产生的目标文件，SCons会管理这些目标文件，以便在链接阶段生成最终的可执行程序或库。 6. `./agg/include` 通常包含头文件，是编译时需要引用的，SCons会处理这些依赖关系。 7. `./plugins` 目录表明SCons支持对第三方插件的构建和管理，这是扩展功能或集成其他库的关键。通过这份手册，开发者可以学习到如何配置SCons脚本，管理依赖，设置编译选项，以及如何在复杂的项目结构中有效地利用SCons进行构建。此外，对于涉及嵌入式系统、GIS应用和Python绑定的项目，这份手册将提供宝贵的指导。SCons的灵活性和自动化能力使得它成为开发者在构建流程中不可或缺的工具。

status

Prints status information for each displayed node.

prune

Prunes the tree to avoid repeating dependency information for nodes that have already been displayed. Any

node that has already been displayed will have its name printed in [square brackets], as an indication that

the dependencies for that node can be found by searching for the relevant output higher up in the tree.

Multiple type choices may be specified, separated by commas:

# Prints only derived files, with status information:

scons --tree=derived,status

# Prints all dependencies of target, with status information

# and pruning dependencies of already-visited Nodes:

scons --tree=all,prune,status target

-u, --up, --search-up

Walks up the directory structure until an SConstruct, Sconstruct, sconstruct, SConstruct.py,

Sconstruct.py or sconstruct.py file is found, and uses that as the top of the directory tree. If no targets

are specified on the command line, only targets at or below the current directory will be built.

-U

Works exactly the same way as the -u option except for the way default targets are handled. When this option is

used and no targets are specified on the command line, all default targets that are defined in the SConscript(s) in

the current directory are built, regardless of what directory the resultant targets end up in.

-v, --version

Print the scons version, copyright information, list of authors, and any other relevant information. Then exit.

-w, --print-directory

Print a message containing the working directory before and after other processing.

--no-print-directory

Turn off -w, even if it was turned on implicitly.

--warn=type, --warn=no-type

Enable or disable (with the prefix "no-") warnings (--warning is a synonym). type specifies the type of

warnings to be enabled or disabled:

all

All warnings.

cache-version

Warnings about the derived-file cache directory specified by CacheDir not using the latest configuration

information. These warnings are enabled by default.

cache-write-error

Warnings about errors trying to write a copy of a built file to a specified derived-file cache specified by

CacheDir. These warnings are disabled by default.

corrupt-sconsign

Warnings about unfamiliar signature data in .sconsign files. These warnings are enabled by default.

dependency

Warnings about dependencies. These warnings are disabled by default.

deprecated

Warnings about use of currently deprecated features. These warnings are enabled by default. Not all

deprecation warnings can be disabled with the --warn=no-deprecated option as some deprecated

features which are late in the deprecation cycle may have been designated as mandatory warnings, and these

will still display. Warnings for certain deprecated features may also be enabled or disabled individually; see

below.

duplicate-environment

Warnings about attempts to specify a build of a target with two different construction environments that use

the same action. These warnings are enabled by default.

fortran-cxx-mix

Warnings about linking Fortran and C++ object files in a single executable, which can yield unpredictable

behavior with some compilers.

future-deprecated

Warnings about features that will be deprecated in the future. Such warnings are disabled by default. Enabling

future deprecation warnings is recommended for projects that redistribute SCons configurations for other

users to build, so that the project can be warned as soon as possible about to-be-deprecated features that may

require changes to the configuration.

link

Warnings about link steps.

misleading-keywords

Warnings about the use of two commonly misspelled keywords targets and sources to Builder calls.

The correct spelling is the singular form, even though target and source can themselves refer to lists

of names or nodes.

tool-qt-deprecated

Warnings about the qt tool being deprecated. These warnings are disabled by default for the first phase of

deprecation. Enable to be reminded about use of this tool module. Available since SCons 4.3.

missing-sconscript

Warnings about missing SConscript files. These warnings are enabled by default.

no-object-count

Warnings about the --debug=object feature not working when scons is run with the Python -O option

or from optimized Python (.pyo) modules.

no-parallel-support

Warnings about the version of Python not being able to support parallel builds when the -j option is used.

These warnings are enabled by default.

python-version

Warnings about running SCons with a deprecated version of Python. These warnings are enabled by default.

reserved-variable

Warnings about attempts to set the reserved construction variable names $CHANGED_SOURCES,

$CHANGED_TARGETS, $TARGET, $TARGETS, $SOURCE, $SOURCES, $UNCHANGED_SOURCES or

$UNCHANGED_TARGETS. These warnings are disabled by default.

stack-size

Warnings about requests to set the stack size that could not be honored. These warnings are enabled by default.

target_not_build

Warnings about a build rule not building the expected targets. These warnings are disabled by default.

-Y repository, --repository=repository, --srcdir=repository

Search the specified repository for any input and target files not found in the local directory hierarchy.

Multiple -Y options may be specified, in which case the repositories are searched in the order specified.

SCONSCRIPT FILE REFERENCE

SConscript Files

The build configuration is described by one or more files, known as SConscript files. There must be at least one file

for a valid build (scons will quit if it does not find one). scons by default looks for this file by the name SConstruct

in the directory from which you run scons, though if necessary, also looks for alternative file names Sconstruct,

sconstruct, SConstruct.py, Sconstruct.py and sconstruct.py in that order. A different file name

(which can include a pathname part) may be specified via the -f option. Except for the SConstruct file, these files

are not searched for automatically; you add additional configuration files to the build by calling the SConscript

function. This allows parts of the build to be conditionally included or excluded at run-time depending on how scons

is invoked.

Each SConscript file in a build configuration is invoked independently in a separate context. This provides necessary

isolation so that different parts of the build don't accidentally step on each other. You have to be explicit about sharing

information, by using the Export function or the exports argument to the SConscript function, as well as the

Return function in a called SConscript file, and comsume shared information by using the Import function.

The following sections describe the various SCons facilities that can be used in SConscript files. Quick links:

Construction Environments

Tools

Builder Methods

Methods and Functions to do Things

SConscript Variables

Construction Variables

Configure Contexts

Command-Line Construction Variables

Node Objects

Construction Environments

A Construction Environment is the basic means by which you communicate build information to SCons. A new

construction environment is created using the Environment function:

env = Environment()

Construction environment attributes called Construction Variables may be set either by specifying them as keyword

arguments when the object is created or by assigning them a value after the object is created. These two are nominally

equivalent:

env = Environment(FOO='foo')

env['FOO'] = 'foo'

Note that certain settings which affect tool detection are referenced only when the tools are initializided, so you either

need either to supply them as part of the call to Environment, or defer tool initialization. For example, initializing

the Microsoft Visual C++ version you wish to use:

# initializes msvc to v14.1

env = Environment(MSVC_VERSION="14.1")

env = Environment()

# msvc tool was initialized to default, does not reinitialize

env['MSVC_VERSION'] = "14.1"

env = Environment(tools=[])

env['MSVC_VERSION'] = "14.1"

# msvc tool initialization was deferred, so will pick up new value

env.Tool('default')

As a convenience, construction variables may also be set or modified by the parse_flags keyword argument during

object creation, which has the effect of the env.MergeFlags method being applied to the argument value after all

other processing is completed. This is useful either if the exact content of the flags is unknown (for example, read

from a control file) or if the flags need to be distributed to a number of construction variables. env.ParseFlags

describes how these arguments are distributed to construction variables.

env = Environment(parse_flags='-Iinclude -DEBUG -lm')

This example adds 'include' to the $CPPPATH construction variable, 'EBUG' to $CPPDEFINES, and 'm' to $LIBS.

An existing construction environment can be duplicated by calling the env.Clone method. Without arguments, it

will be a copy with the same settings. Otherwise, env.Clone takes the same arguments as Environment, and

uses the arguments to create a modified copy.

SCons provides a special construction environment called the Default Environment. The default environment is

used only for global functions, that is, construction activities called without the context of a regular construction

environment. See DefaultEnvironment for more information.

By default, a new construction environment is initialized with a set of builder methods and construction variables that

are appropriate for the current platform. The optional platform keyword argument may be used to specify that the

construction environment should be initialized for a different platform:

env = Environment(platform='cygwin')

Specifying a platform initializes the appropriate construction variables in the environment to use and generate file

names with prefixes and suffixes appropriate for that platform.

Note that the win32 platform adds the SystemDrive and SystemRoot variables from the user's external

environment to the construction environment's ENV dictionary. This is so that any executed commands that use sockets

to connect with other systems will work on Windows systems.

The platform argument may be a string value representing one of the pre-defined platforms (aix, cygwin,

darwin, hpux, irix, os2, posix, sunos or win32), or it may be be a callable platform object returned by a call

to Platform selecting a pre-defined platform, or it may be a user-supplied callable, in which case the Environment

method will call it to update the new construction environment:

def my_platform(env):

env['VAR'] = 'xyzzy'

env = Environment(platform=my_platform)

Note that supplying a non-default platform or custom fuction for initialization may bypass settings that should happen

for the host system and should be used with care. It is most useful in the case where the platform is an alternative for

the one that would be auto-detected, such as platform="cygwin" on a system which would otherwise identify

as win32.

The optional tools and toolpath keyword arguments affect the way tools available to the environment are

initialized. See the section called “Tools” for details.

The optional variables keyword argument allows passing a Variables object which will be used in the initialization

of the construction environment See the section called “Command-Line Construction Variables” for details.

Tools

SCons has a large number of predefined tool modules (more properly, tool specification modules) which are used to

help initialize the construction environment. An SCons tool is only responsible for setup. For example, if an SConscript

file declares the need to construct an object file from a C-language source file by calling the Object builder, then a

tool representing an available C compiler needs to have run first, to set up that builder and all the construction variables

it needs in the associated construction environment; the tool itself is not called in the process of the build. Normally

this happens invisibly as scons has per-platform lists of default tools, and it steps through those tools, calling the ones

which are actually applicable, skipping those where necessary programs are not installed on the build system, or other

preconditions are not met.

A specific set of tools with which to initialize an environment when creating it may be specified using the optional

keyword argument tools, which takes a list of tool names. This is useful to override the defaults, to specify non-

default built-in tools, and to supply added tools:

env = Environment(tools=['msvc', 'lex'])

Tools can also be directly called by using the Tool method (see below).

The tools argument overrides the default tool list, it does not add to it, so be sure to include all the tools you need.

For example if you are building a c/c++ program you must specify a tool for at least a compiler and a linker, as in

tools=['clang', 'link']. The tool name 'default' can be used to retain the default list.

If no tools argument is specified, or if tools includes 'default', then scons will auto-detect usable tools, using

the execution environment value of PATH (that is, env['ENV']['PATH'] - the external evironment PATH from

os.environ is not used) for looking up any backing programs, and the platform name in effect to determine the

default tools for that platform. Changing the PATH variable after the construction environment is constructed will not

cause the tools to be re-detected.

Additional tools can be added, see the Extending SCons section and specifically Tool Modules.

SCons supports the following tool specifications out of the box:

386asm

Sets construction variables for the 386ASM assembler for the Phar Lap ETS embedded operating system.

Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.

Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.

aixc++

Sets construction variables for the IMB xlc / Visual Age C++ compiler.

Sets: $CXX, $CXXVERSION, $SHCXX, $SHOBJSUFFIX.

剩余210页未读，继续阅读

arbotor

粉丝: 0
资源: 5

SCons 构建工具完整帮助手册

scons用户手册

Scons使用手册

scons 用户使用手册

Ubuntu下scons安装

rt-thread scons

scons用户指南中文版

scons: *** No SConstruct file found

centos7安装scons

scons环境变量的配置

python调用scons库

最新资源