From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 26 Apr 2014 15:11:58 +0200 Subject: Imported Upstream version 2.3.1 --- doc/user/builders-writing.xml | 532 +++++++++++++++++++++++++++--------------- 1 file changed, 345 insertions(+), 187 deletions(-) (limited to 'doc/user/builders-writing.xml') diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index e6b165b..bc7983d 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -1,6 +1,28 @@ + + + %scons; + + + %builders-mod; + + %functions-mod; + + %tools-mod; + + %variables-mod; + +]> + + +Writing Your Own Builders + - - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - + + +import SCons.Defaults; SCons.Defaults.ConstructionEnvironment['TOOLS'] = {}; bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + + +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + + +file.input + + +hello.c + + - - % scons -Q - AttributeError: 'SConsEnvironment' object has no attribute 'Program': - File "/home/my/project/SConstruct", line 4: - env.Program('hello.c') - + + scons -Q + @@ -247,15 +293,34 @@ This functionality could be invoked as in the following example: - + + +env = Environment() +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env.Append(BUILDERS = {'Foo' : bld}) +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + + +file.input + + +hello.c + + +cat + + - - env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env.Append(BUILDERS = {'Foo' : bld}) - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - + +env = Environment() +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env.Append(BUILDERS = {'Foo' : bld}) +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + @@ -264,13 +329,13 @@ This functionality could be invoked as in the following example: - - env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env['BUILDERS']['Foo'] = bld - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - + +env = Environment() +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env['BUILDERS']['Foo'] = bld +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + @@ -281,12 +346,9 @@ This functionality could be invoked as in the following example: - - % scons -Q - foobuild < file.input > file.foo - cc -o hello.o -c hello.c - cc -o hello hello.o - + + scons -Q + @@ -310,22 +372,40 @@ This functionality could be invoked as in the following example: - + + +bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +env.Foo('file1') +env.Foo('file2') + + +file1.input + + +file2.input + + +cat + + - - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file1') - env.Foo('file2') - + +bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file1') +env.Foo('file2') + - - % scons -Q - foobuild < file1.input > file1.foo - foobuild < file2.input > file2.foo - + + scons -Q + @@ -352,9 +432,9 @@ This functionality could be invoked as in the following example: - def build_function(target, source, env): - # Code to build "target" from "source" - return None +def build_function(target, source, env): + # Code to build "target" from "source" + return None @@ -439,16 +519,21 @@ This functionality could be invoked as in the following example: - - def build_function(target, source, env): - # Code to build "target" from "source" - return None - bld = Builder(action = build_function, - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file') - + + +def build_function(target, source, env): + # Code to build "target" from "source" + return None +bld = Builder(action = build_function, + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file') + + +file.input + + @@ -459,10 +544,9 @@ This functionality could be invoked as in the following example: - - % scons -Q - build_function(["file.foo"], ["file.input"]) - + + scons -Q + @@ -481,8 +565,8 @@ This functionality could be invoked as in the following example: - def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (target[0], source[0]) +def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (target[0], source[0]) @@ -582,22 +666,39 @@ This functionality could be invoked as in the following example: - - - - def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) - bld = Builder(generator = generate_actions, - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file') - + + +def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (source[0], target[0]) +bld = Builder(generator = generate_actions, + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +env.Foo('file') + + +file.input + + +cat + + - - % scons -Q - foobuild < file.input > file.foo - + +def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (source[0], target[0]) +bld = Builder(generator = generate_actions, + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file') + + + + scons -Q + @@ -643,20 +744,44 @@ This functionality could be invoked as in the following example: - + + +def modify_targets(target, source, env): + target.append('new_target') + source.append('new_source') + return target, source +bld = Builder(action = 'foobuild $TARGETS - $SOURCES', + suffix = '.foo', + src_suffix = '.input', + emitter = modify_targets) +env = Environment(BUILDERS = {'Foo' : bld}) +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +env.Foo('file') + + +file.input + + +new_source + + +cat + + - - def modify_targets(target, source, env): - target.append('new_target') - source.append('new_source') - return target, source - bld = Builder(action = 'foobuild $TARGETS - $SOURCES', - suffix = '.foo', - src_suffix = '.input', - emitter = modify_targets) - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file') - + +def modify_targets(target, source, env): + target.append('new_target') + source.append('new_source') + return target, source +bld = Builder(action = 'foobuild $TARGETS - $SOURCES', + suffix = '.foo', + src_suffix = '.input', + emitter = modify_targets) +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file') + @@ -664,10 +789,9 @@ This functionality could be invoked as in the following example: - - % scons -Q - foobuild file.foo new_target - file.input new_source - + + scons -Q + @@ -685,43 +809,61 @@ This functionality could be invoked as in the following example: - - bld = Builder(action = 'my_command $SOURCES > $TARGET', - suffix = '.foo', - src_suffix = '.input', - emitter = '$MY_EMITTER') - def modify1(target, source, env): - return target, source + ['modify1.in'] - def modify2(target, source, env): - return target, source + ['modify2.in'] - env1 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify1) - env2 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify2) - env1.Foo('file1') - env2.Foo('file2') - import os - env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() - env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() + + + +bld = Builder(action = 'my_command $SOURCES > $TARGET', + suffix = '.foo', + src_suffix = '.input', + emitter = '$MY_EMITTER') +def modify1(target, source, env): + return target, source + ['modify1.in'] +def modify2(target, source, env): + return target, source + ['modify2.in'] +env1 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify1) +env2 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify2) +env1.Foo('file1') +env2.Foo('file2') +import os +env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() +env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() + + +file1.input + + +file2.input + + +modify1.input + + +modify2.input + + +cat + - + - - bld = Builder(action = 'my_command $SOURCES > $TARGET', - suffix = '.foo', - src_suffix = '.input', - emitter = '$MY_EMITTER') - def modify1(target, source, env): - return target, source + ['modify1.in'] - def modify2(target, source, env): - return target, source + ['modify2.in'] - env1 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify1) - env2 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify2) - env1.Foo('file1') - env2.Foo('file2') - + +bld = Builder(action = 'my_command $SOURCES > $TARGET', + suffix = '.foo', + src_suffix = '.input', + emitter = '$MY_EMITTER') +def modify1(target, source, env): + return target, source + ['modify1.in'] +def modify2(target, source, env): + return target, source + ['modify2.in'] +env1 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify1) +env2 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify2) +env1.Foo('file1') +env2.Foo('file2') + @@ -732,11 +874,9 @@ This functionality could be invoked as in the following example: - - % scons -Q - my_command file1.input modify1.in > file1.foo - my_command file2.input modify2.in > file2.foo - + + scons -Q + @@ -820,14 +960,23 @@ This functionality could be invoked as in the following example: - - def TOOL_ADD_HEADER(env): - """A Tool to add a header from $HEADER to the source file""" - add_header = Builder(action=['echo "$HEADER" > $TARGET', - 'cat $SOURCE >> $TARGET']) - env.Append(BUILDERS = {'AddHeader' : add_header}) - env['HEADER'] = '' # set default value - + + +def TOOL_ADD_HEADER(env): + """A Tool to add a header from $HEADER to the source file""" + add_header = Builder(action=['echo "$HEADER" > $TARGET', + 'cat $SOURCE >> $TARGET']) + env.Append(BUILDERS = {'AddHeader' : add_header}) + env['HEADER'] = '' # set default value + + +env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") +env.AddHeader('tgt', 'src') + + +hi there + + @@ -835,11 +984,11 @@ This functionality could be invoked as in the following example: - - # Use TOOL_ADD_HEADER from site_scons/site_init.py - env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") - env.AddHeader('tgt', 'src') - + +# Use TOOL_ADD_HEADER from site_scons/site_init.py +env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") +env.AddHeader('tgt', 'src') + @@ -850,7 +999,7 @@ This functionality could be invoked as in the following example: @@ -885,15 +1034,22 @@ This functionality could be invoked as in the following example: functions: - - from SCons.Script import * # for Execute and Mkdir - def build_id(): - """Return a build ID (stub version)""" - return "100" - def MakeWorkDir(workdir): - """Create the specified dir immediately""" - Execute(Mkdir(workdir)) - + + +from SCons.Script import * # for Execute and Mkdir +def build_id(): + """Return a build ID (stub version)""" + return "100" +def MakeWorkDir(workdir): + """Create the specified dir immediately""" + Execute(Mkdir(workdir)) + + +import my_utils +MakeWorkDir('/tmp/work') +print "build_id=" + my_utils.build_id() + + @@ -902,11 +1058,11 @@ This functionality could be invoked as in the following example: - - import my_utils - print "build_id=" + my_utils.build_id() - my_utils.MakeWorkDir('/tmp/work') - + +import my_utils +print "build_id=" + my_utils.build_id() +my_utils.MakeWorkDir('/tmp/work') + Note that although you can put this library in @@ -917,9 +1073,9 @@ This functionality could be invoked as in the following example: such as &Environment; or &Mkdir; or &Execute; in any file other than a &SConstruct; or &SConscript; you always need to do - - from SCons.Script import * - + +from SCons.Script import * + This is true in modules in site_scons such as @@ -954,21 +1110,23 @@ This functionality could be invoked as in the following example: - + - env = Environment() - #env.SourceCode('.', env.BitKeeper('my_command')) - env.Program('hello.c') +env = Environment() +#env.SourceCode('.', env.BitKeeper('my_command')) +env.Program('hello.c') - hello.c +hello.c - + scons -Q --> + + -- cgit v1.2.3