diff options
Diffstat (limited to 'scons.1')
| -rw-r--r-- | scons.1 | 284 |
1 files changed, 246 insertions, 38 deletions
@@ -3,11 +3,11 @@ .\" Author: Steven Knight .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/> .\" Date: <pubdate>2004 - 2015</pubdate> -.\" Manual: SCons 2.4.0 -.\" Source: SCons 2.4.0 version 2.4.0 +.\" Manual: SCons 2.4.1 +.\" Source: SCons 2.4.1 version 2.4.1 .\" Language: English .\" -.TH "SCONS" "1" "<pubdate>2004 - 2015</pubdate>" "SCons 2\&.4\&.0 version 2.4.0" "SCons 2\&.4\&.0" +.TH "SCONS" "1" "<pubdate>2004 - 2015</pubdate>" "SCons 2\&.4\&.1 version 2.4.1" "SCons 2\&.4\&.1" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -1709,6 +1709,26 @@ Uses: \fB$CXXCOMSTR\fR\&. .RE .PP +cyglink +.RS 4 +Set construction variables for cygwin linker/loader\&. +.sp +Sets: +\fB$IMPLIBPREFIX\fR, +\fB$IMPLIBSUFFIX\fR, +\fB$LDMODULEVERSIONFLAGS\fR, +\fB$LINKFLAGS\fR, +\fB$RPATHPREFIX\fR, +\fB$RPATHSUFFIX\fR, +\fB$SHLIBPREFIX\fR, +\fB$SHLIBSUFFIX\fR, +\fB$SHLIBVERSIONFLAGS\fR, +\fB$SHLINKCOM\fR, +\fB$SHLINKFLAGS\fR, +\fB$_LDMODULEVERSIONFLAGS\fR, +\fB$_SHLIBVERSIONFLAGS\fR\&. +.RE +.PP default .RS 4 Sets variables by calling a default list of Tool modules for the platform on which SCons is running\&. @@ -2314,7 +2334,7 @@ Sets: .PP gettext .RS 4 -This is actually a toolset, which supports internationalization and localization of sofware being constructed with SCons\&. The toolset loads following tools: +This is actually a toolset, which supports internationalization and localization of software being constructed with SCons\&. The toolset loads following tools: .sp .sp @@ -2430,9 +2450,13 @@ gnulink Set construction variables for GNU linker/loader\&. .sp Sets: +\fB$LDMODULEVERSIONFLAGS\fR, \fB$RPATHPREFIX\fR, \fB$RPATHSUFFIX\fR, -\fB$SHLINKFLAGS\fR\&. +\fB$SHLIBVERSIONFLAGS\fR, +\fB$SHLINKFLAGS\fR, +\fB$_LDMODULESONAME\fR, +\fB$_SHLIBSONAME\fR\&. .RE .PP gs @@ -2744,8 +2768,11 @@ Sets: \fB$LDMODULE\fR, \fB$LDMODULECOM\fR, \fB$LDMODULEFLAGS\fR, +\fB$LDMODULENOVERSIONSYMLINKS\fR, \fB$LDMODULEPREFIX\fR, \fB$LDMODULESUFFIX\fR, +\fB$LDMODULEVERSION\fR, +\fB$LDMODULEVERSIONFLAGS\fR, \fB$LIBDIRPREFIX\fR, \fB$LIBDIRSUFFIX\fR, \fB$LIBLINKPREFIX\fR, @@ -2756,7 +2783,9 @@ Sets: \fB$SHLIBSUFFIX\fR, \fB$SHLINK\fR, \fB$SHLINKCOM\fR, -\fB$SHLINKFLAGS\fR\&. +\fB$SHLINKFLAGS\fR, +\fB$__LDMODULEVERSIONFLAGS\fR, +\fB$__SHLIBVERSIONFLAGS\fR\&. .sp Uses: \fB$LDMODULECOMSTR\fR, @@ -3150,11 +3179,6 @@ Uses: \fB$ASPPCOMSTR\fR\&. .RE .PP -packaging -.RS 4 -A framework for building binary and source packages\&. -.RE -.PP Packaging .RS 4 Sets construction variables for the @@ -3162,6 +3186,11 @@ Sets construction variables for the Builder\&. .RE .PP +packaging +.RS 4 +A framework for building binary and source packages\&. +.RE +.PP pdf .RS 4 Sets construction variables for the Portable Document Format builder\&. @@ -3366,14 +3395,10 @@ Sets: \fB$ARCOM\fR, \fB$ARFLAGS\fR, \fB$LIBPREFIX\fR, -\fB$LIBSUFFIX\fR, -\fB$SHLINK\fR, -\fB$SHLINKCOM\fR, -\fB$SHLINKFLAGS\fR\&. +\fB$LIBSUFFIX\fR\&. .sp Uses: -\fB$ARCOMSTR\fR, -\fB$SHLINKCOMSTR\fR\&. +\fB$ARCOMSTR\fR\&. .RE .PP sunc++ @@ -4475,11 +4500,7 @@ env\&.InstallAs(target = [\*(Aq\&.\&./lib/libfoo\&.a\*(Aq, \*(Aq\&.\&./lib/libba .PP \fBInstallVersionedLib()\fR, \fBenv\&.InstallVersionedLib()\fR .RS 4 -Installs a versioned shared library\&. The -\fB$SHLIBVERSION\fR -construction variable should be defined in the environment to confirm the version number in the library name\&. If -\fB$SHLIBVERSION\fR -is not defined a warning will be issued and the name of the library will be parsed to derive the version\&. The symlinks appropriate to the architecture will be generated\&. +Installs a versioned shared library\&. The symlinks appropriate to the architecture will be generated based on symlinks of the source library\&. .sp .if n \{\ .RS 4 @@ -4487,9 +4508,6 @@ is not defined a warning will be issued and the name of the library will be pars .nf env\&.InstallVersionedLib(target = \*(Aq/usr/local/bin/foo\*(Aq, source = \*(Aqlibxyz\&.1\&.5\&.2\&.so\*(Aq) -env\&.InstallVersionedLib(target = \*(Aq/usr/local/bin/foo\*(Aq, - source = \*(Aqlibxyz\&.1\&.5\&.2\&.so\*(Aq, - SHLIBVERSION=\*(Aq1\&.5\&.2\*(Aq) .fi .if n \{\ .RE @@ -5172,7 +5190,7 @@ env\&.Package( NAME = \*(Aqfoo\*(Aq, .PP \fBPCH()\fR, \fBenv\&.PCH()\fR .RS 4 -Builds a Microsoft Visual C++ precompiled header\&. Calling this builder method returns a list of two targets: the PCH as the first element, and the object file as the second element\&. Normally the object file is ignored\&. This builder method is only provided when Microsoft Visual C++ is being used as the compiler\&. The PCH builder method is generally used in conjuction with the PCH construction variable to force object files to use the precompiled header: +Builds a Microsoft Visual C++ precompiled header\&. Calling this builder method returns a list of two targets: the PCH as the first element, and the object file as the second element\&. Normally the object file is ignored\&. This builder method is only provided when Microsoft Visual C++ is being used as the compiler\&. The PCH builder method is generally used in conjunction with the PCH construction variable to force object files to use the precompiled header: .sp .if n \{\ .RS 4 @@ -5509,7 +5527,7 @@ The \fBPOTUpdate\fR builder may be used with no target specified, in which case default target messages\&.pot -will be used\&. The default target may also be overriden by setting +will be used\&. The default target may also be overridden by setting \fB$POTDOMAIN\fR construction variable or providing it as an override to \fBPOTUpdate\fR @@ -5724,7 +5742,7 @@ Alias (\*(Aqpo\-update\*(Aq by default)\&. The alias name may be changed through the \fB$POUPDATE_ALIAS\fR -construction variable\&. You can easilly update +construction variable\&. You can easily update PO files in your project by \fBscons po\-update\fR\&. @@ -6100,8 +6118,6 @@ When the construction variable is defined a versioned shared library is created\&. This modifies the \fB$SHLINKFLAGS\fR as required, adds the version number to the library name, and creates the symlinks that are needed\&. -\fB$SHLIBVERSION\fR -needs to be of the form X\&.Y\&.Z, where X and Y are numbers, and Z is a number but can also contain letters to designate alpha, beta, or release candidate patch levels\&. .sp .if n \{\ .RS 4 @@ -6113,7 +6129,7 @@ env\&.SharedLibrary(target = \*(Aqbar\*(Aq, source = [\*(Aqbar\&.c\*(Aq, \*(Aqfo .RE .\} .sp -This builder may create multiple links to the library\&. On a POSIX system, for the shared library libbar\&.so\&.2\&.3\&.1, the links created would be libbar\&.so and libbar\&.so\&.2; on a Darwin (OSX) system the library would be libbar\&.2\&.3\&.1\&.dylib and the link would be libbar\&.dylib\&. +On a POSIX system, versions with a single token create exactly one symlink: libbar\&.so\&.6 would have symlinks libbar\&.so only\&. On a POSIX system, versions with two or more tokens create exactly two symlinks: libbar\&.so\&.2\&.3\&.1 would have symlinks libbar\&.so and libbar\&.so\&.2; on a Darwin (OSX) system the library would be libbar\&.2\&.3\&.1\&.dylib and the link would be libbar\&.dylib\&. .sp On Windows systems, specifying register=1 @@ -6684,7 +6700,7 @@ files can be compiled by running .PP \fBTypeLibrary()\fR, \fBenv\&.TypeLibrary()\fR .RS 4 -Builds a Windows type library (\&.tlb) file from an input IDL file (\&.idl)\&. In addition, it will build the associated inteface stub and proxy source files, naming them according to the base name of the +Builds a Windows type library (\&.tlb) file from an input IDL file (\&.idl)\&. In addition, it will build the associated interface stub and proxy source files, naming them according to the base name of the \&.idl file\&. For example, .sp @@ -8491,7 +8507,7 @@ sources = Glob(\*(Aq*\&.cpp\*(Aq, exclude=[\*(Aqos_*_specific_*\&.cpp\*(Aq]) + G .\} .RE .PP -Help(text), env\&.Help(text) +Help(text, append=False), env\&.Help(text, append=False) .RS 4 This specifies help text to be printed if the \fB\-h\fR @@ -8500,7 +8516,13 @@ scons\&. If \fBHelp\fR is called multiple times, the text is appended together in the order that \fBHelp\fR -is called\&. +is called\&. With append set to False, any +\fBHelp\fR +text generated with +\fBAddOption\fR +is clobbered\&. If append is True, the AddOption help is prepended to the help string, thus preserving the +\fB\-h\fR +message\&. .RE .PP Ignore(target, dependency), env\&.Ignore(target, dependency) @@ -10387,6 +10409,24 @@ that are used by built\-in or user\-supplied build rules\&. Construction variabl .PP A number of useful construction variables are automatically defined by scons for each supported platform, and additional construction variables can be defined by the user\&. The following is a list of the automatically defined construction variables: .PP +__LDMODULEVERSIONFLAGS +.RS 4 +This construction variable automatically introduces +\fB$_LDMODULEVERSIONFLAGS\fR +if +\fB$LDMODULEVERSION\fR +is set\&. Othervise it evaluates to an empty string\&. +.RE +.PP +__SHLIBVERSIONFLAGS +.RS 4 +This construction variable automatically introduces +\fB$_SHLIBVERSIONFLAGS\fR +if +\fB$SHLIBVERSION\fR +is set\&. Othervise it evaluates to an empty string\&. +.RE +.PP AR .RS 4 The static library archiver\&. @@ -12586,6 +12626,52 @@ The list of suffixes of files that will be scanned for IDL implicit dependencies .\} .RE .PP +IMPLIBNOVERSIONSYMLINKS +.RS 4 +Used to override +\fB$SHLIBNOVERSIONSYMLINKS\fR/\fB$LDMODULENOVERSIONSYMLINKS\fR +when creating versioned import library for a shared library/loadable module\&. If not defined, then +\fB$SHLIBNOVERSIONSYMLINKS\fR/\fB$LDMODULENOVERSIONSYMLINKS\fR +is used to determine whether to disable symlink generation or not\&. +.RE +.PP +IMPLIBPREFIX +.RS 4 +The prefix used for import library names\&. For example, cygwin uses import libraries (libfoo\&.dll\&.a) in pair with dynamic libraries (cygfoo\&.dll)\&. The +cyglink +linker sets +\fB$IMPLIBPREFIX\fR +to +\*(Aqlib\*(Aq +and +\fB$SHLIBPREFIX\fR +to +\*(Aqcyg\*(Aq\&. +.RE +.PP +IMPLIBSUFFIX +.RS 4 +The suffix used for import library names\&. For example, cygwin uses import libraries (libfoo\&.dll\&.a) in pair with dynamic libraries (cygfoo\&.dll)\&. The +cyglink +linker sets +\fB$IMPLIBSUFFIX\fR +to +\*(Aq\&.dll\&.a\*(Aq +and +\fB$SHLIBSUFFIX\fR +to +\*(Aq\&.dll\*(Aq\&. +.RE +.PP +IMPLIBVERSION +.RS 4 +Used to override +\fB$SHLIBVERSION\fR/\fB$LDMODULEVERSION\fR +when generating versioned import library for a shared library/loadable module\&. If undefined, the +\fB$SHLIBVERSION\fR/\fB$LDMODULEVERSION\fR +is used to determine the version of versioned import library\&. +.RE +.PP IMPLICIT_COMMAND_DEPENDENCIES .RS 4 Controls whether or not SCons will add implicit dependencies for the commands executed to build targets\&. @@ -13028,17 +13114,73 @@ LDMODULEFLAGS General user options passed to the linker for building loadable modules\&. .RE .PP +LDMODULENOVERSIONSYMLINKS +.RS 4 +Instructs the +\fBLoadableModule\fR +builder to not automatically create symlinks for versioned modules\&. Defaults to +$SHLIBNOVERSIONSYMLINKS +.RE +.PP LDMODULEPREFIX .RS 4 The prefix used for loadable module file names\&. On Mac OS X, this is null; on other systems, this is the same as \fB$SHLIBPREFIX\fR\&. .RE .PP +_LDMODULESONAME +.RS 4 +A macro that automatically generates loadable module\*(Aqs SONAME based on $TARGET, $LDMODULEVERSION and $LDMODULESUFFIX\&. Used by +\fBLoadableModule\fR +builder when the linker tool supports SONAME (e\&.g\&. +gnulink)\&. +.RE +.PP LDMODULESUFFIX .RS 4 The suffix used for loadable module file names\&. On Mac OS X, this is null; on other systems, this is the same as $SHLIBSUFFIX\&. .RE .PP +LDMODULEVERSION +.RS 4 +When this construction variable is defined, a versioned loadable module is created by +\fBLoadableModule\fR +builder\&. This activates the +\fB$_LDMODULEVERSIONFLAGS\fR +and thus modifies the +\fB$LDMODULECOM\fR +as required, adds the version number to the library name, and creates the symlinks that are needed\&. +\fB$LDMODULEVERSION\fR +versions should exist in the same format as +\fB$SHLIBVERSION\fR\&. +.RE +.PP +LDMODULEVERSIONFLAGS +.RS 4 +Extra flags added to +\fB$LDMODULECOM\fR +when building versioned +\fBLoadableModule\fR\&. These flags are only used when +\fB$LDMODULEVERSION\fR +is set\&. +.RE +.PP +_LDMODULEVERSIONFLAGS +.RS 4 +This macro automatically introduces extra flags to +\fB$LDMODULECOM\fR +when building versioned +\fBLoadableModule\fR +(that is when +\fB$LDMODULEVERSION\fR +is set)\&. +_LDMODULEVERSIONFLAGS +usually adds +\fB$SHLIBVERSIONFLAGS\fR +and some extra dynamically generated options (such as +\-Wl,\-soname=$_LDMODULESONAME)\&. It is unused by plain (unversioned) loadable modules\&. +.RE +.PP LEX .RS 4 The lexical analyzer generator\&. @@ -15300,11 +15442,26 @@ SHLIBEMITTER TODO .RE .PP +SHLIBNOVERSIONSYMLINKS +.RS 4 +Instructs the +\fBSharedLibrary\fR +builder to not create symlinks for versioned shared libraries\&. +.RE +.PP SHLIBPREFIX .RS 4 The prefix used for shared library file names\&. .RE .PP +_SHLIBSONAME +.RS 4 +A macro that automatically generates shared library\*(Aqs SONAME based on $TARGET, $SHLIBVERSION and $SHLIBSUFFIX\&. Used by +\fBSharedLibrary\fR +builder when the linker tool supports SONAME (e\&.g\&. +gnulink)\&. +.RE +.PP SHLIBSUFFIX .RS 4 The suffix used for shared library file names\&. @@ -15312,11 +15469,43 @@ The suffix used for shared library file names\&. .PP SHLIBVERSION .RS 4 -When this construction variable is defined, a versioned shared library is created\&. This modifies the -\fB$SHLINKFLAGS\fR +When this construction variable is defined, a versioned shared library is created by +\fBSharedLibrary\fR +builder\&. This activates the +\fB$_SHLIBVERSIONFLAGS\fR +and thus modifies the +\fB$SHLINKCOM\fR as required, adds the version number to the library name, and creates the symlinks that are needed\&. \fB$SHLIBVERSION\fR -needs to be of the form X\&.Y\&.Z, where X and Y are numbers, and Z is a number but can also contain letters to designate alpha, beta, or release candidate patch levels\&. +versions should exist as alpha\-numeric, decimal\-delimited values as defined by the regular expression "\ew+[\e\&.\ew+]*"\&. Example +\fB$SHLIBVERSION\fR +values include \*(Aq1\*(Aq, \*(Aq1\&.2\&.3\*(Aq, and \*(Aq1\&.2\&.gitaa412c8b\*(Aq\&. +.RE +.PP +_SHLIBVERSIONFLAGS +.RS 4 +This macro automatically introduces extra flags to +\fB$SHLINKCOM\fR +when building versioned +\fBSharedLibrary\fR +(that is when +\fB$SHLIBVERSION\fR +is set)\&. +_SHLIBVERSIONFLAGS +usually adds +\fB$SHLIBVERSIONFLAGS\fR +and some extra dynamically generated options (such as +\-Wl,\-soname=$_SHLIBSONAME\&. It is unused by "plain" (unversioned) shared libraries\&. +.RE +.PP +SHLIBVERSIONFLAGS +.RS 4 +Extra flags added to +\fB$SHLINKCOM\fR +when building versioned +\fBSharedLibrary\fR\&. These flags are only used when +\fB$SHLIBVERSION\fR +is set\&. .RE .PP SHLINK @@ -15373,6 +15562,25 @@ SHOBJSUFFIX The suffix used for shared object file names\&. .RE .PP +SONAME +.RS 4 +Variable used to hard\-code SONAME for versioned shared library/loadable module\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +env\&.SharedLibrary(\*(Aqtest\*(Aq, \*(Aqtest\&.c\*(Aq, SHLIBVERSION=\*(Aq0\&.1\&.2\*(Aq, SONAME=\*(Aqlibtest\&.so\&.2\*(Aq) +.fi +.if n \{\ +.RE +.\} +.sp +The variable is used, for example, by +gnulink +linker tool\&. +.RE +.PP SOURCE .RS 4 A reserved variable name that may not be set or used in a construction environment\&. (See "Variable Substitution," below\&.) @@ -19532,7 +19740,7 @@ env\&.Program(\*(AqMyApp\*(Aq, [\*(AqFoo\&.cpp\*(Aq, \*(AqBar\&.cpp\*(Aq]) .RE .\} .PP -For more information see the document for the PCH builder, and the PCH and PCHSTOP construction variables\&. To learn about the details of precompiled headers consult the MSDN documention for /Yc, /Yu, and /Yp\&. +For more information see the document for the PCH builder, and the PCH and PCHSTOP construction variables\&. To learn about the details of precompiled headers consult the MSDN documentation for /Yc, /Yu, and /Yp\&. .SS "Using Microsoft Visual C++ external debugging information" .PP Since including debugging information in programs and shared libraries can cause their size to increase significantly, Microsoft provides a mechanism for including the debugging information in an external file called a PDB file\&. SCons supports PDB files through the PDB construction variable\&. |