diff options
Diffstat (limited to 'doc/python10')
29 files changed, 4450 insertions, 0 deletions
diff --git a/doc/python10/MANIFEST b/doc/python10/MANIFEST new file mode 100644 index 0000000..c9484d8 --- /dev/null +++ b/doc/python10/MANIFEST @@ -0,0 +1,16 @@ +abstract.xml +acks.xml +arch.fig +builder.fig +copyright.xml +design.xml +future.xml +install.xml +intro.xml +job-task.fig +main.xml +node.fig +process.xml +scanner.fig +scons.mod +sig.fig diff --git a/doc/python10/abstract.xml b/doc/python10/abstract.xml new file mode 100644 index 0000000..294180b --- /dev/null +++ b/doc/python10/abstract.xml @@ -0,0 +1,32 @@ +<para> + + &SCons; is a software construction tool (build tool, or make tool) + implemented in Python, which uses Python scripts as "configuration + files" for software builds. Based on the design which won the + Software Carpentry build tool competition, &SCons solves a number of + problems associated with other build tools, especially including the + classic and ubiquitous &Make; itself. + +</para> + +<para> + + Distinctive features of &SCons; include: a modular design that + lends itself to being embedded in other applications; a global + view of all dependencies in the source tree; an improved model for + parallel (<option>-j</option>) builds; automatic scanning of files for + dependencies; use of MD5 signatures for deciding whether a file + is up-to-date; use of traditional file timestamps instead of + MD5 signatures available as an option; + use of Python functions or objects to build target files; easy user + extensibility. + +</para> + +<para> + + This paper discusses the goals of the &SCons; project, gives an overview + of the design of &SCons; itself, describes the development process used, + and discusses future plans and directions for the tool. + +</para> diff --git a/doc/python10/acks.xml b/doc/python10/acks.xml new file mode 100644 index 0000000..895bad7 --- /dev/null +++ b/doc/python10/acks.xml @@ -0,0 +1,27 @@ +<para> + + First, many thanks to the great group of developers who dove in right + from the beginning and have contributed the code and ideas to make + &SCons; a success: Chad Austin, Charles Crain, Steve Leblanc, and + Anthony Roach. Thanks also to those on the scons-devel mailing list + who have contributed greatly to the discussion, notably including + David Abrahams, Trent Mick, and Steven Shaw. + +</para> + +<para> + + &SCons; would not exist today without the pioneering work of Bob + Sidebotham on the original &Cons; tool, and without Greg Wilson's + having started the Software Carpentry contest. + +</para> + +<para> + + Thanks also to Peter Miller for: Aegis; the testing discipline that it + enforces, without which creating a stable but flexible tool would be + impossible; the "Recursive Make Considered Harmful" paper which led me + to experiment with &Cons; in the first place. + +</para> diff --git a/doc/python10/arch.eps b/doc/python10/arch.eps new file mode 100644 index 0000000..1fdd51f --- /dev/null +++ b/doc/python10/arch.eps @@ -0,0 +1,134 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/arch.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 218 182 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 182 moveto 0 0 lineto 218 0 lineto 218 182 lineto closepath clip newpath +-215.3 324.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +/Courier-Bold ff 300.00 scf sf +3825 2925 m +gs 1 -1 sc (scons) col0 sh gr +/Times-Roman ff 300.00 scf sf +3825 3225 m +gs 1 -1 sc (Script) col0 sh gr +/Times-Roman ff 300.00 scf sf +5100 4875 m +gs 1 -1 sc (Build Engine) col0 sh gr +/Courier-Bold ff 300.00 scf sf +4200 4875 m +gs 1 -1 sc (SCons) col0 sh gr +% Polyline +7.500 slw +n 3600 4200 m 7200 4200 l 7200 5400 l 3600 5400 l + cp gs col0 s gr +/Courier-Bold ff 300.00 scf sf +4725 4050 m +gs 1 -1 sc (SCons) col0 sh gr +/Times-Roman ff 300.00 scf sf +5625 4050 m +gs 1 -1 sc (API) col0 sh gr +% Polyline +n 3600 2400 m 3600 2400 l 3600 2400 l 3600 2400 l + cp gs col0 s gr +% Polyline +n 3600 2400 m 4800 2400 l 4800 3600 l 3600 3600 l + cp gs col0 s gr +% Polyline +n 3600 3600 m 7200 3600 l 7200 4200 l 3600 4200 l + cp gs col0 s gr +% Polyline + [60] 0 sd +n 6000 3600 m 7200 3600 l 7200 2400 l 6000 2400 l + cp gs col0 s gr [] 0 sd +/Times-Italic ff 300.00 scf sf +6300 2925 m +gs 1 -1 sc (other) col0 sh gr +/Times-Italic ff 300.00 scf sf +6150 3225 m +gs 1 -1 sc (interface) col0 sh gr +$F2psEnd +rs diff --git a/doc/python10/arch.fig b/doc/python10/arch.fig new file mode 100644 index 0000000..ae20bd4 --- /dev/null +++ b/doc/python10/arch.fig @@ -0,0 +1,35 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +6 3825 2775 4650 3300 +4 0 0 50 0 14 20 0.0000 4 135 825 3825 2925 scons\001 +4 0 0 50 0 0 20 0.0000 4 255 690 3825 3225 Script\001 +-6 +6 3600 4200 7200 5400 +6 4200 4650 6675 4950 +4 0 0 50 0 0 20 0.0000 4 255 1515 5100 4875 Build Engine\001 +4 0 0 50 0 14 20 0.0000 4 165 825 4200 4875 SCons\001 +-6 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3600 4200 7200 4200 7200 5400 3600 5400 3600 4200 +-6 +6 4725 3825 6150 4050 +4 0 0 50 0 14 20 0.0000 4 165 825 4725 4050 SCons\001 +4 0 0 50 0 0 20 0.0000 4 195 465 5625 4050 API\001 +-6 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3600 2400 3600 2400 3600 2400 3600 2400 3600 2400 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3600 2400 4800 2400 4800 3600 3600 3600 3600 2400 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3600 3600 7200 3600 7200 4200 3600 4200 3600 3600 +2 2 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5 + 6000 3600 7200 3600 7200 2400 6000 2400 6000 3600 +4 0 0 50 0 1 20 0.0000 4 210 570 6300 2925 other\001 +4 0 0 50 0 1 20 0.0000 4 270 975 6150 3225 interface\001 diff --git a/doc/python10/arch.jpg b/doc/python10/arch.jpg Binary files differnew file mode 100644 index 0000000..4e69437 --- /dev/null +++ b/doc/python10/arch.jpg diff --git a/doc/python10/builder.eps b/doc/python10/builder.eps new file mode 100644 index 0000000..db87afc --- /dev/null +++ b/doc/python10/builder.eps @@ -0,0 +1,325 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/builder.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 668 290 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 290 moveto 0 0 lineto 668 0 lineto 668 290 lineto closepath clip newpath +-53.3 342.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/reencdict 12 dict def /ReEncode { reencdict begin +/newcodesandnames exch def /newfontname exch def /basefontname exch def +/basefontdict basefontname findfont def /newfont basefontdict maxlength dict def +basefontdict { exch dup /FID ne { dup /Encoding eq +{ exch dup length array copy newfont 3 1 roll put } +{ exch newfont 3 1 roll put } ifelse } { pop pop } ifelse } forall +newfont /FontName newfontname put newcodesandnames aload pop +128 1 255 { newfont /Encoding get exch /.notdef put } for +newcodesandnames length 2 idiv { newfont /Encoding get 3 1 roll put } repeat +newfontname newfont definefont pop end } def +/isovec [ +8#055 /minus 8#200 /grave 8#201 /acute 8#202 /circumflex 8#203 /tilde +8#204 /macron 8#205 /breve 8#206 /dotaccent 8#207 /dieresis +8#210 /ring 8#211 /cedilla 8#212 /hungarumlaut 8#213 /ogonek 8#214 /caron +8#220 /dotlessi 8#230 /oe 8#231 /OE +8#240 /space 8#241 /exclamdown 8#242 /cent 8#243 /sterling +8#244 /currency 8#245 /yen 8#246 /brokenbar 8#247 /section 8#250 /dieresis +8#251 /copyright 8#252 /ordfeminine 8#253 /guillemotleft 8#254 /logicalnot +8#255 /hyphen 8#256 /registered 8#257 /macron 8#260 /degree 8#261 /plusminus +8#262 /twosuperior 8#263 /threesuperior 8#264 /acute 8#265 /mu 8#266 /paragraph +8#267 /periodcentered 8#270 /cedilla 8#271 /onesuperior 8#272 /ordmasculine +8#273 /guillemotright 8#274 /onequarter 8#275 /onehalf +8#276 /threequarters 8#277 /questiondown 8#300 /Agrave 8#301 /Aacute +8#302 /Acircumflex 8#303 /Atilde 8#304 /Adieresis 8#305 /Aring +8#306 /AE 8#307 /Ccedilla 8#310 /Egrave 8#311 /Eacute +8#312 /Ecircumflex 8#313 /Edieresis 8#314 /Igrave 8#315 /Iacute +8#316 /Icircumflex 8#317 /Idieresis 8#320 /Eth 8#321 /Ntilde 8#322 /Ograve +8#323 /Oacute 8#324 /Ocircumflex 8#325 /Otilde 8#326 /Odieresis 8#327 /multiply +8#330 /Oslash 8#331 /Ugrave 8#332 /Uacute 8#333 /Ucircumflex +8#334 /Udieresis 8#335 /Yacute 8#336 /Thorn 8#337 /germandbls 8#340 /agrave +8#341 /aacute 8#342 /acircumflex 8#343 /atilde 8#344 /adieresis 8#345 /aring +8#346 /ae 8#347 /ccedilla 8#350 /egrave 8#351 /eacute +8#352 /ecircumflex 8#353 /edieresis 8#354 /igrave 8#355 /iacute +8#356 /icircumflex 8#357 /idieresis 8#360 /eth 8#361 /ntilde 8#362 /ograve +8#363 /oacute 8#364 /ocircumflex 8#365 /otilde 8#366 /odieresis 8#367 /divide +8#370 /oslash 8#371 /ugrave 8#372 /uacute 8#373 /ucircumflex +8#374 /udieresis 8#375 /yacute 8#376 /thorn 8#377 /ydieresis] def +/Times-Roman /Times-Roman-iso isovec ReEncode +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 2700 1200 m 4500 1200 l 4500 1800 l 2700 1800 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +2925 1575 m +gs 1 -1 sc (Environment) col0 sh gr +% Polyline +n 2700 2400 m 4500 2400 l 4500 3000 l 2700 3000 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +3600 2775 m +gs 1 -1 sc (BuilderWrapper) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 2700 3600 m 4500 3600 l 4500 4200 l 2700 4200 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +3600 3975 m +gs 1 -1 sc (BuilderBase) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 8400 3600 m 9900 3600 l 9900 4200 l 8400 4200 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +9150 3975 m +gs 1 -1 sc (ActionBase) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +4650 5175 m +gs 1 -1 sc (MultiStep-) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +4650 5460 m +gs 1 -1 sc (Builder) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 3900 4800 m 5400 4800 l 5400 5700 l 3900 5700 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +2550 5175 m +gs 1 -1 sc (Composite-) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +2550 5460 m +gs 1 -1 sc (Builder) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 1800 4800 m 3300 4800 l 3300 5700 l 1800 5700 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +7050 5175 m +gs 1 -1 sc (Command) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +7050 5460 m +gs 1 -1 sc (Action) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 6300 4800 m 7800 4800 l 7800 5700 l 6300 5700 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +9150 5460 m +gs 1 -1 sc (Action) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +9150 5175 m +gs 1 -1 sc (Function) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 8400 4800 m 9900 4800 l 9900 5700 l 8400 5700 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +11250 5175 m +gs 1 -1 sc (List) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +11250 5460 m +gs 1 -1 sc (Action) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 10500 4800 m 12000 4800 l 12000 5700 l 10500 5700 l + cp gs col0 s gr +% Polyline +n 900 2400 m 2100 2400 l 2100 3000 l 900 3000 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +1500 2775 m +gs 1 -1 sc (Node) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 3600 4200 m 3525 4350 l 3675 4350 l + cp gs col0 s gr +% Polyline +n 3150 4800 m 3150 4500 l 4050 4500 l + 4050 4800 l gs col0 s gr +% Polyline +n 3600 4350 m + 3600 4500 l gs col0 s gr +% Polyline +n 9150 4200 m 9075 4350 l 9225 4350 l + cp gs col0 s gr +% Polyline +n 7050 4800 m 7050 4500 l 10950 4500 l + 10950 4800 l gs col0 s gr +% Polyline +n 9150 4350 m + 9150 4800 l gs col0 s gr +% Polyline +gs clippath +9885 3870 m 9885 3930 l 10036 3930 l 9916 3900 l 10036 3870 l cp +eoclip +n 11550 4650 m 11550 3900 l + 9900 3900 l gs col0 s gr gr + +% arrowhead +n 10036 3870 m 9916 3900 l 10036 3930 l 10036 3870 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +8415 3930 m 8415 3870 l 8264 3870 l 8384 3900 l 8264 3930 l cp +eoclip +n 4650 3900 m + 8400 3900 l gs col0 s gr gr + +% arrowhead +n 8264 3930 m 8384 3900 l 8264 3870 l 8264 3930 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3930 1785 m 3870 1785 l 3870 1936 l 3900 1816 l 3930 1936 l cp +eoclip +n 3900 2250 m + 3900 1800 l gs col0 s gr gr + +% arrowhead +n 3930 1936 m 3900 1816 l 3870 1936 l 3930 1936 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3270 2415 m 3330 2415 l 3330 2264 l 3300 2384 l 3270 2264 l cp +eoclip +n 3300 1950 m + 3300 2400 l gs col0 s gr gr + +% arrowhead +n 3270 2264 m 3300 2384 l 3330 2264 l 3270 2264 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3570 3615 m 3630 3615 l 3630 3464 l 3600 3584 l 3570 3464 l cp +eoclip +n 3600 3150 m + 3600 3600 l gs col0 s gr gr + +% arrowhead +n 3570 3464 m 3600 3584 l 3630 3464 l 3570 3464 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4380 4185 m 4320 4185 l 4320 4336 l 4350 4216 l 4380 4336 l cp +eoclip +n 4350 4650 m + 4350 4200 l gs col0 s gr gr + +% arrowhead +n 4380 4336 m 4350 4216 l 4320 4336 l 4380 4336 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +2880 4185 m 2820 4185 l 2820 4336 l 2850 4216 l 2880 4336 l cp +eoclip +n 2850 4650 m + 2850 4200 l gs col0 s gr gr + +% arrowhead +n 2880 4336 m 2850 4216 l 2820 4336 l 2880 4336 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +2715 3930 m 2715 3870 l 2564 3870 l 2684 3900 l 2564 3930 l cp +eoclip +n 1500 3150 m 1500 3900 l + 2700 3900 l gs col0 s gr gr + +% arrowhead +n 2564 3930 m 2684 3900 l 2564 3870 l 2564 3930 l cp gs 0.00 setgray ef gr col0 s +% Polyline +n 4650 3900 m 4575 3860 l 4500 3900 l 4575 3940 l + cp gs col0 s gr +% Polyline +n 1500 3000 m 1460 3075 l 1500 3150 l 1540 3075 l + cp gs col0 s gr +% Polyline +n 3600 3000 m 3560 3075 l 3600 3150 l 3640 3075 l + cp gs col0 s gr +% Polyline +n 3300 1800 m 3260 1875 l 3300 1950 l 3340 1875 l + cp gs col0 s gr +% Polyline +n 3900 2250 m 3860 2325 l 3900 2400 l 3940 2325 l + cp gs col0 s gr +% Polyline +n 4350 4650 m 4310 4725 l 4350 4800 l 4390 4725 l + cp gs col0 s gr +% Polyline +n 2850 4650 m 2810 4725 l 2850 4800 l 2890 4725 l + cp gs col0 s gr +% Polyline +n 11550 4650 m 11510 4725 l 11550 4800 l 11590 4725 l + cp gs col0 s gr +% Polyline + [60] 0 sd +n 3600 1200 m + 3600 900 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/builder.fig b/doc/python10/builder.fig new file mode 100644 index 0000000..75e5ec0 --- /dev/null +++ b/doc/python10/builder.fig @@ -0,0 +1,128 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +6 2700 1200 4500 1800 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2700 1200 4500 1200 4500 1800 2700 1800 2700 1200 +4 0 0 50 0 0 16 0.0000 4 165 1290 2925 1575 Environment\001 +-6 +6 2700 2400 4500 3000 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2700 2400 4500 2400 4500 3000 2700 3000 2700 2400 +4 1 0 50 0 0 16 0.0000 4 225 1620 3600 2775 BuilderWrapper\001 +-6 +6 2700 3600 4500 4200 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2700 3600 4500 3600 4500 4200 2700 4200 2700 3600 +4 1 0 50 0 0 16 0.0000 4 165 1215 3600 3975 BuilderBase\001 +-6 +6 8400 3600 9900 4200 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 8400 3600 9900 3600 9900 4200 8400 4200 8400 3600 +4 1 0 50 0 0 16 0.0000 4 165 1140 9150 3975 ActionBase\001 +-6 +6 3900 4800 5400 5700 +6 4050 4950 5250 5475 +4 1 0 50 0 0 16 0.0000 4 225 1140 4650 5175 MultiStep-\001 +4 1 0 50 0 0 16 0.0000 4 165 750 4650 5460 Builder\001 +-6 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3900 4800 5400 4800 5400 5700 3900 5700 3900 4800 +-6 +6 1800 4800 3300 5700 +6 1950 4950 3150 5475 +4 1 0 50 0 0 16 0.0000 4 225 1200 2550 5175 Composite-\001 +4 1 0 50 0 0 16 0.0000 4 165 750 2550 5460 Builder\001 +-6 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1800 4800 3300 4800 3300 5700 1800 5700 1800 4800 +-6 +6 6300 4800 7800 5700 +6 6525 4950 7575 5475 +4 1 0 50 0 0 16 0.0000 4 165 1020 7050 5175 Command\001 +4 1 0 50 0 0 16 0.0000 4 165 675 7050 5460 Action\001 +-6 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 6300 4800 7800 4800 7800 5700 6300 5700 6300 4800 +-6 +6 8400 4800 9900 5700 +6 8700 4950 9600 5475 +4 1 0 50 0 0 16 0.0000 4 165 675 9150 5460 Action\001 +4 1 0 50 0 0 16 0.0000 4 165 870 9150 5175 Function\001 +-6 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 8400 4800 9900 4800 9900 5700 8400 5700 8400 4800 +-6 +6 10500 4800 12000 5700 +6 10875 4950 11625 5475 +4 1 0 50 0 0 16 0.0000 4 165 390 11250 5175 List\001 +4 1 0 50 0 0 16 0.0000 4 165 675 11250 5460 Action\001 +-6 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 10500 4800 12000 4800 12000 5700 10500 5700 10500 4800 +-6 +6 900 2400 2100 3000 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 900 2400 2100 2400 2100 3000 900 3000 900 2400 +4 1 0 50 0 0 16 0.0000 4 165 525 1500 2775 Node\001 +-6 +2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 3600 4200 3525 4350 3675 4350 3600 4200 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 3150 4800 3150 4500 4050 4500 4050 4800 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 + 3600 4350 3600 4500 +2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 9150 4200 9075 4350 9225 4350 9150 4200 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 7050 4800 7050 4500 10950 4500 10950 4800 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 + 9150 4350 9150 4800 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 + 1 1 1.00 60.00 120.00 + 11550 4650 11550 3900 9900 3900 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 4650 3900 8400 3900 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3900 2250 3900 1800 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3300 1950 3300 2400 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3600 3150 3600 3600 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 4350 4650 4350 4200 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 2850 4650 2850 4200 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 + 1 1 1.00 60.00 120.00 + 1500 3150 1500 3900 2700 3900 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 4650 3900 4575 3860 4500 3900 4575 3940 4650 3900 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 1500 3000 1460 3075 1500 3150 1540 3075 1500 3000 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 3600 3000 3560 3075 3600 3150 3640 3075 3600 3000 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 3300 1800 3260 1875 3300 1950 3340 1875 3300 1800 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 3900 2250 3860 2325 3900 2400 3940 2325 3900 2250 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 4350 4650 4310 4725 4350 4800 4390 4725 4350 4650 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 2850 4650 2810 4725 2850 4800 2890 4725 2850 4650 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 11550 4650 11510 4725 11550 4800 11590 4725 11550 4650 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 3600 1200 3600 900 diff --git a/doc/python10/builder.jpg b/doc/python10/builder.jpg Binary files differnew file mode 100644 index 0000000..e9085e8 --- /dev/null +++ b/doc/python10/builder.jpg diff --git a/doc/python10/copyright.xml b/doc/python10/copyright.xml new file mode 100644 index 0000000..d141fc6 --- /dev/null +++ b/doc/python10/copyright.xml @@ -0,0 +1,32 @@ +<!-- + + Copyright (c) 2001, 2002, 2003 Steven Knight + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<blockquote> + <para> + + Copyright (c) 2001, 2002 Steven Knight + + </para> +</blockquote> diff --git a/doc/python10/design.xml b/doc/python10/design.xml new file mode 100644 index 0000000..cb58af9 --- /dev/null +++ b/doc/python10/design.xml @@ -0,0 +1,898 @@ +<para> + + The &SCons; architecture consists of three layers: + +</para> + +<mediaobject> + <imageobject> + <imagedata fileref="arch" format="eps" align="center"> + </imageobject> + <imageobject> + <imagedata fileref="arch.jpg" format="jpg" align="center"> + </imageobject> + <!-- PDF files? + <imageobject> + <imagedata fileref="arch.pdf" align="center"> + </imageobject> + --> +</mediaobject> + +<itemizedlist> + + <listitem> + <para> + + The &SCons; <emphasis>Build Engine</emphasis>, a package of Python + modules that handle dependency management and updating out-of-date + objects. + + </para> + </listitem> + + <listitem> + <para> + + The &SCons; <emphasis>API</emphasis> (applications programming + interface) between the Build Engine + and the user interface. + + </para> + </listitem> + + <listitem> + <para> + + The &scons; <emphasis>script</emphasis> itself (note lower case + <emphasis>sc</emphasis>), which is the pre-provided interface to + the Build Engine. + + </para> + </listitem> + +</itemizedlist> + +<para> + + Notice that this architecture separates the internal workings of + &SCons; (the Build Engine) from the + external user interface. The benefit is that the &SCons; Build Engine + can be imported into any other software package written in Python + to support a variety of user interfaces—or, to look at it + in reverse, other software interfaces can use the &SCons; Build + Engine to manage dependencies between their objects. + +</para> + +<para> + + Because the + &SCons; package itself is modular, only those parts of the package + relevant to the embedding interface need be imported; for example, + a utility that wants to use only file timestamps for checking + whether a file is up-to-date + need not import the MD5 signature module. + +</para> + +<section> + <title>The &SCons; Build Engine</title> + + <para> + + The Build Engine is a package of Python modules that + form the heart of &SCons;. + + The Build Engine can be broadly divided into five + architectural subsystems, each responsible + for a crucial part of &SCons; functionality: + + </para> + + <itemizedlist> + + <listitem> + <para> + + A <emphasis>node</emphasis> subsystem, responsible for managing + the files (or other objects) to be built, and the dependency + relationships between them. + + </para> + </listitem> + + <listitem> + <para> + + A <emphasis>scanner</emphasis> subsystem, responsible for + scanning various file types for implicit dependencies. + + </para> + </listitem> + + <listitem> + <para> + + A <emphasis>signature</emphasis> subsystem, responsible for + deciding whether a given file (or other object) requires + rebuilding. + + </para> + </listitem> + + <listitem> + <para> + + A <emphasis>builder</emphasis> subsystem, responsible for + actually executing the necessary command or function to + build a file (or other object). + + </para> + </listitem> + + <listitem> + <para> + + A <emphasis>job/task</emphasis> subsystem, responsible for + handling parallelization of builds. + + </para> + </listitem> + + </itemizedlist> + + <para> + + The rest of this section will provide a high-level overview of the + class structure of each of these Build Engine subsystems. + + </para> + + <section> + <title>Node Subsystem</title> + + <para> + + The node subsystem of the Build Engine is + responsible for managing the knowledge in &SCons; of + the relationships among the external objects + (files) it is responsible for updating. + The most important of these relationships is + the dependency relationship between various &Node; objects, + which &SCons; uses to determine the order + in which builds should be performed. + + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="node" format="eps" align="center"> + </imageobject> + <imageobject> + <imagedata fileref="node.jpg" format="jpg" align="center"> + </imageobject> + <!-- PDF files? + <imageobject> + <imagedata fileref="node.pdf" align="center"> + </imageobject> + --> + </mediaobject> + + <para> + + The &scons; script (or other + user interface) + tells the Build Engine + about dependencies + through its &consenv; API. + The Build Engine also discovers + dependencies automatically through the use of &Scanner; objects. + + </para> + + <para> + + Subclasses of the &Node; class maintain additional + relationships that reflect the real-world + existence of these objects. + For example, the &Node_FS; subclass + is responsible for managing a + representation of the directory hierarchy + of a file system. + + </para> + + <para> + + A &Walker; class is used by other subsystems + to walk the dependency tree maintained by the &Node; class. + The &Walker; class maintains a stack of &Node; objects + visited during its depth-first traversal of the + dependency tree, + and uses an intermediate node &Wrapper; class + to maintain state information about a + &Node; object's dependencies. + + </para> + + </section> + + <section> + <title>Scanner Subsystem</title> + + <para> + + The scanner subsystem is responsible for maintaining + objects that can scan the contents of a &Node;'s + for implicit dependencies. + + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="scanner" format="eps" align="center"> + </imageobject> + <imageobject> + <imagedata fileref="scanner.jpg" format="jpg" align="center"> + </imageobject> + <!-- PDF files? + <imageobject> + <imagedata fileref="scanner.pdf" align="center"> + </imageobject> + --> + </mediaobject> + + <para> + + In practice, a given &Scanner; subclass object + functions as a prototype, + returning clones of itself + depending on the &consenv; + values governing how the &Node; + should be scanned. + + </para> + + </section> + + <section> + <title>Signature Subsystem</title> + + <para> + + The signature subsystem is responsible for computing + signature information for &Node; objects. + The signature subsystem in &SCons; + supports multiple ways to + determine whether a &Node is up-to-date + by using an abstract &Sig; class + as a strategy wrapper: + + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="sig" format="eps" align="center"> + </imageobject> + <imageobject> + <imagedata fileref="sig.jpg" format="jpg" align="center"> + </imageobject> + <!-- PDF files? + <imageobject> + <imagedata fileref="sig.pdf" align="center"> + </imageobject> + --> + </mediaobject> + + <para> + + By default, &SCons; tracks dependencies by computing and + maintaining MD5 signatures for the contents of each source file + (or other object). The signature of a <emphasis>derived</emphasis> + file consists of the aggregate of the signatures of all the source + files <emphasis>plus</emphasis> the command-line string used to + build the file. These signatures are stored in a &sconsign; file + in each directory. + + </para> + + <para> + + If the contents of any of the source files changes, the change to its + MD5 signature is propogated to the signature of the derived file(s). The + simple fact that the new signature does not match the stored signature + indicates that the derived file is not up to date and must be rebuilt. + + </para> + + <para> + + A separate &TimeStamp; subclass of the &Sig; class supports + the use of traditional file timestamps for + deciding whether files are up-to-date. + + </para> + + </section> + + <section> + <title>Builder Subsystem</title> + + <para> + + The &SCons; Build Engine records how out-of-date files + (or other objects) should be rebuilt in &Builder; objects, + maintained by the builder subsystem: + + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="builder" format="eps" align="center"> + </imageobject> + <imageobject> + <imagedata fileref="builder.jpg" format="jpg" align="center"> + </imageobject> + <!-- PDF files? + <imageobject> + <imagedata fileref="builder.pdf" align="center"> + </imageobject> + --> + </mediaobject> + + <para> + + The actual underlying class name is &BuilderBase;, + and there are subclasses that can encapsulate + multiple &Builder; objects for special purposes. + One subclass + (&CompositeBuilder;) + selects an appropriate encapsulated &Builder; + based on the file suffix of the target object. + The other + (&MultiStepBuilder;). + can chain together multiple + &Builder; objects, + for example, + to build an executable program from a source file + through an implicit intermediate object file. + + </para> + + <para> + + A &BuilderBase; object has an associated + &ActionBase; object + responsible for actually executing + the appropriate steps + to update the target file. + There are three subclasses, + one for externally executable commands + (&CommandAction;), + one for Python functions + (&FunctionAction;), + and one for lists of + multiple &Action; objects + (&ListAction;). + + </para> + + </section> + + <section> + <title>Job/Task Subsystem</title> + + <para> + + &SCons; supports parallel builds with a thread-based tasking + model, managed by the job/task subsystem. + + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="job-task" format="eps" align="center"> + </imageobject> + <imageobject> + <imagedata fileref="job-task.jpg" format="jpg" align="center"> + </imageobject> + <!-- PDF files? + <imageobject> + <imagedata fileref="job-task.pdf" align="center"> + </imageobject> + --> + </mediaobject> + + <para> + + Instead of performing an outer-loop recursive descent + of the dependency tree and then forking a task when it finds a + file that needs updating, &SCons; starts as many threads as are + requested, each thread managed by the &Jobs; class. + As a performance optimization, + the &Jobs; class maintains an internal + distinction between + &Serial; and &Parallel; + build jobs, + so that serial builds + don't pay any performance penalty + by using a multi-threaded implementation + written for &Parallel; builds. + + </para> + + <para> + + Each &Jobs; object, running in its own thread, + then requests a &Task; from a central &Taskmaster;, + which is responsible + for handing out available &Task; objects for (re-)building + out-of-date nodes. A condition variable + makes sure that the &Jobs; objects + query the &Taskmaster; one at a time. + + </para> + + <para> + + The &Taskmaster uses the node subsystem's + &Walker; class to walk the dependency tree, + and the &Sig; class to use the + appropriate method + of deciding if a &Node; is up-to-date. + + </para> + + <para> + + This scheme has many advantages over the standard &Make; + implementation of <option>-j</option>. + Effective use of <option>-j</option> is difficult + with the usual recursive use of Make, + because the number of jobs started by <option>-j</option> multiply + at each level of the source tree. + This makes the actual number of jobs + executed at any moment very dependent on the size and layout of + the tree. &SCons;, in contrast, starts only as many jobs as are + requested, and keeps them constantly busy (excepting jobs that + block waiting for their dependency files to finish building). + + </para> + + </section> + +</section> + +<section> + <title>The &SCons; API</title> + + <para> + + This section provides an overview of the &SCons; interface. The + complete interface specification is both more detailed and flexible + than this overview. + + </para> + + <section> + <title>&ConsVars;</title> + + <para> + + In &SCons;, a &consenv; is an object through which an external + interface (such as the &scons; script) communicates dependency + information to the &SCons; Build Engine. + + </para> + + <para> + + A construction environment is implemented as a dictionary + containing: + + </para> + + <itemizedlist> + + <listitem> + <para> + + construction variables, string values that are substituted + into command lines or used by builder functions; + + </para> + </listitem> + + <listitem> + <para> + + one or more &Builder; objects that can be invoked to update a + file or other object; + + </para> + </listitem> + + <listitem> + <para> + + one or more &Scanner; objects that can be used to + scan a file automatically for dependencies (such as + files specified on <literal>#include</literal> lines). + + </para> + </listitem> + + </itemizedlist> + + <para> + + &Consenvs; are instantiated as follows: + + </para> + + <programlisting> + env = Environment() + env_debug = Environment(CCFLAGS = '-g') + </programlisting> + + </section> + + <section> + <title>&Builder; Objects</title> + + <para> + + An &SCons; &Builder; object encapsulates information about how to + build a specific type of file: an executable program, an object + file, a library, etc. A &Builder; object is associated with a + file through an associated &consenv; method and later invoked to + actually build the file. The &Builder; object will typically use + construction variables (such as &CCFLAGS;, &LIBPATH;) to influence + the specific build execution. + + </para> + + <para> + + &Builder; objects are instantiated as follows: + + </para> + + <programlisting> + bld = Builder(name = 'Program', action = "$CC -o $TARGET $SOURCES") + </programlisting> + + <para> + + In the above example, the <literal>action</literal> is a + command-line string in which the Build Engine will + interpolate the values of construction + variables before execution. The actual + <literal>action</literal> specified, though, + may be a function: + + </para> + + <programlisting> + def update(dest): + # [code to update the object] + return 0 + + bld = Builder(name = 'Program', function = update) + </programlisting> + + <para> + + Or a callable Python object (or class): + + </para> + + <programlisting> + class class_a: + def __call__(self, kw): + # build the desired object + return 0 + + builder = SCons.Builder.Builder(action = class_a()) + </programlisting> + + <para> + + A &Builder; object may have the <literal>prefix</literal> and + <literal>suffix</literal> of its target file type specified + as keyword arguments at instantiation. Additionally, the + suffix of the <emphasis>source files</emphasis> used by this + &Builder; to build its target files may be specified using the + <literal>src_suffix</literal> keyword argument: + + </para> + + <programlisting> + bld_lib = Builder(name = 'Library', action = "$AR r $TARGET $SOURCES", + prefix = 'lib', suffix = '.a', src_suffix = '.o') + </programlisting> + + <para> + + The specified <literal>prefix</literal> and + <literal>suffix</literal> will be appended to the name of any + target file built by this &Builder; object, if they are not + already part of the file name. The <literal>src_suffix</literal> + is used by the &SCons; Build Engine to chain together + multiple &Builder; objects to create, + for example, a library from the original source + files without having to specify the + intermediate <literal>.o</literal> files. + + </para> + + <para> + + &Builder; objects are associated with a &consenv; through a + &consvar; named &BUILDERS;, a list of the &Builder objects that + will be available for execution through the &consenv: + + </para> + + <programlisting> + env = Environment(BUILDERS = [ Object, Library, WebPage, Program ]) + </programlisting> + + </section> + + <section> + <title>&Scanner; Objects</title> + + <para> + + &Scanner; objects perform automatic checking for dependencies + by scanning the contents of files. The canonical + example is scanning a C source file or header file for + files specified on <literal>#include</literal> lines. + + </para> + + <para> + + A &Scanner; object is instantiated as follows: + + </para> + + <programlisting> + def c_scan(contents): + # scan contents of file + return # list of files found + + c_scanner = Scanner(name = 'CScan', function = c_scan, + argument = None, + skeys = ['.c', '.C', '.h', '.H') + </programlisting> + + <para> + + The <literal>skeys</literal> argument specifies a list of file + suffixes for file types that this &Scanner; knows how to scan. + + </para> + + <para> + + &Scanner; objects are associated with a &consenv; through a + &consvar; named &SCANNERS;, a list of the &Scanner; objects that + will be available through the &consenv: + + </para> + + <programlisting> + env = Environment(SCANNERS = [ CScan, M4Scan ]) + </programlisting> + + <para> + + For utilities that will build files with a variety of file + suffixes, or which require unusual scanning rules, a &Scanner; + object may be associated explicitly with a &Builder; object as + follows: + + </para> + + <programlisting> + def tool_scan(contents): + # scan contents of file + return # list of files found + + tool_scanner = Scanner(name = 'TScan', function = tool_scan) + + bld = Builder(name = 'Tool', scanner = tool_scanner) + </programlisting> + + </section> + + <section> + <title>&BuildDir;</title> + + <para> + + &SCons; supports a flexible mechanism for building target + files in a separate build directory from the source files. + The &BuildDir; syntax is straightforward: + + </para> + + <programlisting> + BuildDir(source = 'src', build = 'bld') + </programlisting> + + <para> + + By + default, source files are linked or copied into the build + directory, because exactly replicating the source directory + is sometimes necessary for certain combinations of use of + <literal>#include "..."</literal> and <option>-I</option> search + paths. + + An option exists to specify that only output files should be placed in + the build directory: + + </para> + + <programlisting> + BuildDir(source = 'src', build = 'bld', no_sources = 1) + </programlisting> + + </section> + + <section> + <title>&Repository;</title> + + <para> + + &SCons; supports the ability to search a list of code repositories + for source files and derived files. This works much like + &Make;'s <varname>VPATH</varname> feature, as implemented in + recent versions of GNU &Make;. + (The POSIX standard for &Make; specifies slightly + different behavior for <varname>VPATH</varname>.) + The syntax is: + + </para> + + <programlisting> + Repository('/home/source/1.1', '/home/source/1.0') + </programlisting> + + <para> + + A command-line <option>-Y</option> option exists to allow + repositories to be specified on the command line, or in the + &SCONSFLAGS; environment variable (not construction variable!). + This avoids a chicken-and-egg situation and allows the top-level + &SConstruct; file to be found in a repository as well. + + </para> + + </section> + + <section> + <title>&Cache;</title> + + <para> + + &SCons; supports a way for developers to share derived files. Again, the + syntax is straightforward: + + </para> + + <programlisting> + Cache('/var/build.cache/i386') + </programlisting> + + <para> + + Copies of any derived files built will be placed in the specified + directory with their MD5 signature. If another build results in an + out-of-date derived file with the same signature, the derived file + will be copied from the cache instead of being rebuilt. + + </para> + + </section> + +</section> + +<section> + <title>The &scons; Script</title> + + <para> + + The &scons; script provides an interface + that looks roughly equivalent to the + classic &Make; utility—that is, execution from the command + line, and dependency information read from configuration files. + + </para> + + <para> + + The most noticeable difference between &scons; and &Make;, or most + other build tools, is that the configuration files are actually + Python scripts, generically called "SConscripts" (although the + top-level "Makefile" is named &SConstruct). Users do not have to + learn a new language syntax, but instead configure dependency + information by making direct calls to the Python API of the + &SCons; Build Engine. Here is an example &SConstruct file which + builds a program in side-by-side normal and debug versions: + + </para> + + <programlisting> + env = Environment() + debug = env.Copy(CCFLAGS = '-g') + + source_files = ['f1.c', 'f2.c', 'f3.c'] + + env.Program(target = 'foo', sources = source_files) + debug.Program(target = 'foo-debug', sources = source_files) + </programlisting> + + <para> + + Notice the fact that this file is a Python script, which allows us + to define and re-use an array that lists the source files. + + </para> + + <para> + + Because quoting individul strings in long + lists of files can get tedious and error-prone, the &SCons; + methods support a short-cut of listing multiple files in a single + string, separated by white space. + This would change + the assignment in the above example to a more easily-readable: + + </para> + + <programlisting> + source_files = 'f1.c f2.c f3.c' + </programlisting> + + <para> + + The mechanism to establish hierarchical builds is to "include" any + subsidiary configuration files in the build by listing them explicitly + in a call to the &SConscript; function: + + </para> + + <programlisting> + SConscript('src/SConscript', 'lib/SConscript') + </programlisting> + + <para> + + By convention, configuration files in subdirectories are named + &SConscript;. + + </para> + + <para> + + The &scons; script has intentionally been made to look, from + the outside, as much like &Make; as is practical. To this + end, the &scons; script supports all of the same command-line + options supported by GNU &Make;: <option>-f</option> FILE, + <option>-j</option>, <option>-k</option>, <option>-s</option>, + etc. For compatibility, &scons; ignores those GNU &Make; options + that don't make sense for the &SCons; architecture, such as + <option>-b</option>, <option>-m</option>, <option>-S</option>, + and <option>-t</option>. The + intention is that, given an equivalent &SConstruct; file for a + &Makefile;, a user could use &SCons; as a drop-in replacement for + &Make;. Additional command-line options are, where possible, taken + from the Perl &Cons; utility on which the &SCons; design is based. + + </para> + +</section> diff --git a/doc/python10/future.xml b/doc/python10/future.xml new file mode 100644 index 0000000..272d508 --- /dev/null +++ b/doc/python10/future.xml @@ -0,0 +1,170 @@ +<para> + + There are a number of things we would like to do to continue to + improve &SCons; in the future. + +</para> + +<section> + <title>Distutils Cooperation</title> + + <para> + + There is a certain amount of overlap between what &SCons; does + to search out and make use of various compilers on a system, and + the impressively complete job that the Distutils do of describing + much the same thing. Collaborating to provide some sort of common + interface between the two tools would benefit both tools. + + </para> + +</section> + +<section> + <title>Additional Builder Support</title> + + <para> + + Adding additional builders would broaden the + potential user base. In rough order of importance: + + </para> + + <variablelist> + + <varlistentry> + <term>Java</term> + <listitem> + <para> + + Given the popularity of Java, support for it would greatly + increase the appeal of &SCons; in the large community of Java + users. + + </para> + + <para> + + Good support for Java is, however, a tricky + proposition. Because the Java compiler can make decisions + about compiling other files based on what classes it finds + in a file, it behaves "unpredictably" from the point of + view of an outside build tool like &SCons; or &Make;. Some + sort of sophisticated scanning of Java source code to + identify what other classes are likely to be compiled + would be an obvious first step, but notice that here + &SCons; would be scanning the file to find additional + targets to be built. This is the inverse of the sort of + <literal>#include</literal> scanning performed + for C files, in which &SCons; is looking for additional + <emphasis>dependencies</emphasis>. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Documentation toolchains</term> + <listitem> + <para> + + A number of early adopters + are using &SCons; to + build documents + from TeX or DocBook source files. + Built-in support for + various documentation toolchains + would be an obvious boon + for many people. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>C#</term> + <listitem> + <para> + + The reality is that anything that Microsoft does will doubtless + have a wide audience. Turning &SCons;' back on that would be + cutting off its nose to spite its face. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Fortran</term> + <listitem> + <para> + + Despite the fact that &SCons; is no longer directly + associated with Software Carpentry, it still shares the + same goal: to make programming easier for more than just + programmers. To that end, good Fortran support would + help a great many physical scientists and other computer + <emphasis>users</emphasis> out there who still rely on Fortran + for a great deal of their work. + + </para> + </listitem> + </varlistentry> + + </variablelist> + +</section> + +<section> + <title>Database Interface</title> + + <para> + + The Nodes in an &SCons; dependency graph aren't only restricted to + files. Creating an interface to mSQL or MySQL databases would allow + the possibility of updating external files in response to changes in + database fields, or vice versa. This could be handy, for example, + for generating a cache of static web pages from a database that only + need re-generating when the appropriate database objects change. + + </para> + +</section> + +<section> + <title>Tool Integration</title> + + <para> + + &SCons; should work well with as many popular Integrated Development + Environments (IDEs) and tool chains as possible: Komodo, Microsoft + Visual Studio, ClearCase, etc. Suggestions for additional tools are + welcome. + + </para> + +</section> + +<section> + <title>Makefile Interface</title> + + <para> + + Because the &SCons; Build Engine can be embedded in any Python + interface, there isn't any technical reason why a &Makefile; + interpreter couldn't be written in Python and use the &SCons; Build + Engine for its dependency analysis. + + </para> + + <para> + + Proof-of-concept for the idea already exists. Gary Holt's + <literal>make++</literal> (also known as <literal>makepp</literal>) + is a Perl implementation of just such a &Makefile; interpreter. It + could possible serve as a model for a Python version, in much the + same way the &Cons; design served as the prototype for &SCons;. + + </para> + +</section> diff --git a/doc/python10/install.xml b/doc/python10/install.xml new file mode 100644 index 0000000..d150beb --- /dev/null +++ b/doc/python10/install.xml @@ -0,0 +1,179 @@ +<para> + + Initial installation of a new utility provides the first, lasting + impression of how well the software is likely to perform. From the + start, &SCons; has made clean installation a priority. + +</para> + +<section> + <title>Version Control</title> + + <para> + + Distributing an application like &SCons; that depends + on a package normally found in a library poses a + problem. If the &scons; script and the &SCons; Build Engine + are installed separately, it could be easy + to introduce a version mismatch between the Build Engine + installed in + <filename>/usr/lib/python*/site-packages</filename> + and the &scons; script installed in + <filename>/usr/bin</filename>. + Such a mismatch + could possible mean exceptions that prevent builds, or even worse, + silently unreliable builds. + + </para> + + <para> + + To reduce the possibility of a version mismatch, + the &scons; script looks first for its + imported modules in <filename>/usr/lib/scons-{version}/</filename>, + then in <filename>/usr/lib/scons/</filename>, + and then in the normal &PYTHONPATH; locations, + including <filename>/usr/lib/python*/site-packages</filename>). + Searching in a version-specific library directory first + makes it convenient to install and use multiple + side-by-side versions of &SCons;, + which is sometimes important + when verifying that a new version does not introduce any + errors into the local build process. + Searching next in an &SCons;-specific library directory + makes it convenient for other software to find + the &SCons; Build Engine without having to worry about + installing separate copies for + multiple versions of Python. + + </para> + +</section> + +<section> + <title>Packages</title> + + <para> + + &SCons; is currently distributed in the following packages: + + </para> + + <table> + <title></title> + <tgroup cols="2"> + <tbody> + + <row valign="top"> + <entry> + <literal>scons-</literal><emphasis>version</emphasis><literal>.tar.gz</literal> + </entry> + <entry><para> + + The traditional <literal>.tar.gz</literal> file, + installable by running <filename>setup.py</filename>. + + </para></entry> + </row> + + <row valign="top"> + <entry> + <literal>scons-</literal><emphasis>version</emphasis><literal>.noarch.rpm</literal> + </entry> + <entry><para> + + An RPM file for typical installation. + + </para></entry> + </row> + + <row valign="top"> + <entry> + <literal>scons-</literal><emphasis>version</emphasis><literal>_all.deb</literal> + </entry> + <entry><para> + + A Debian package. + + </para></entry> + </row> + + <row valign="top"> + <entry> + <literal>scons-</literal><emphasis>version</emphasis><literal>.win32.exe</literal> + </entry> + <entry><para> + + A Windows installer. + + </para></entry> + </row> + + <row valign="top"> + <entry> + <literal>scons-</literal><emphasis>version</emphasis><literal>.src.rpm</literal> + </entry> + <entry><para> + + A source RPM file. + + </para></entry> + </row> + + <row valign="top"> + <entry> + <literal>scons-src-</literal><emphasis>version</emphasis><literal>.tar.gz</literal> + </entry> + <entry><para> + + A tarball of the &SCons; source tree, + including the full set of regression tests. + + </para></entry> + </row> + + </tbody> + </tgroup> + </table> + + <para> + + Like other software written in Python, &SCons; benefits greatly from + the tremendous effort put into the <literal>distutils</literal> by + Greg Ward and others. These take care of 90% of the work by making + it almost trivial to generate the appropriate RPM files, Debian + packages, and Windows installer. + + </para> + +</section> + +<section> + <title>Default Builder Objects</title> + + <para> + + As part of the installation process, &SCons; runs a set of scripts + that look for popular compilers and other tools and set up + appropriate default &Builder; objects for the tools found. These + &Builder; objects are then used to initialize the default &consenv; + values. + + </para> + +</section> + +<section> + <title>Default Scanner Objects</title> + + <para> + + Additionally, &SCons; comes with a stock set of &Scanner; objects + for the various file types that it supports out of the box. Any + unusal &Scanner; objects required for a specific tool will be + detected at installation time and associated with the appropriate + &Builder; object for the tool. + + </para> + +</section> diff --git a/doc/python10/intro.xml b/doc/python10/intro.xml new file mode 100644 index 0000000..d3057be --- /dev/null +++ b/doc/python10/intro.xml @@ -0,0 +1,212 @@ +<para> + + More than twenty years after its creation, the classic UNIX &Make; + utility and its descendants are still the dominant way in which + software is built. &Make; has maintained this position despite the + fact that the intervening years have revealed many + shortcomings of the &Make; model for building software: + +</para> + +<itemizedlist> + + <listitem> + <para> + + The use of timestamps to decide when a file has been updated is + imprecise and prone to error, especially across distributed file + systems such as NFS. + + </para> + </listitem> + + <listitem> + <para> + + Builds of typical large software systems still take hours, if not + days, despite the tremendous advances in CPU and disk speeds over + recent years. + + </para> + </listitem> + + <listitem> + <para> + + &Make; maintains static definitions of dependencies in its + &Makefiles;. Much effort has been put into + utilities (<application>mkdepend</application>, <application>gcc + -M</application>) and schemes (<filename>Makefile.d</filename> + files) to try to keep &Makefile; dependencies up-to-date, + but these only confirm that &Make;'s static dependencies are + inherently fragile. + + </para> + </listitem> + + <listitem> + <para> + + The standard recursive use of &Make; for build hierarchies leads + to incomplete dependency graphs, which must be overcome by + manually changing the order in which directories are built, or + through the use of multiple build passes. + + </para> + </listitem> + +</itemizedlist> + +<para> + + One need only look at the plethora of helper and wrapper utilities + (automake, easymake, imake, jmake, makeLib, maketool, mkmed, shake, + SMake, TMAKE) and complete alternatives to &Make; (Ant, bake, bau, + bras, Cake, Cons, Cook, Jam, jmk, jus, makeme, mash, MK, nmake, Odin, + VMake) that have been created over the years to realize that vanilla + &Make; is not satisfying everyone's build requirements. So why Yet + Another build tool? + +</para> + +<section> + <title>Enter Software Carpentry</title> + + <para> + + Most of the build tools just mentioned + were written by programmers and for + programmers. The fact that most programmer-friendly + utilities do a poor job of fulfilling the needs + of non-programmers prompted Greg Wilson to + organize the Software Carpentry competition in January 2000. + Software Carpentry was an + open design contest with the express goal of producing a set of + next-generation utilities, including a build tool, that would be + accessible + not only to + programmers + but also to computer <emphasis>users</emphasis> + such as physical scientists. + + </para> + + <para> + + The key to this usability would be that all of + these utilities, including the build tool, would be + written in Python. + This provided the catalyst for actually + pursuing an idea + that had been floating around one of the more + intriguing &Make; alternatives, + a Perl utility called &Cons;. + What if the friendlier syntax of Python + could be married to the + architectural advantages of &Cons;? + + </para> + + <para> + + The resulting merged design, at that time named &ScCons;, + won the Software Carpentry build tool competition. CodeSourcery (by + then the administrators of the competition) ultimately decided not to + fund development of the build tool, but the seed had been planted and the + design had taken root. + + </para> + +</section> + +<section> + <title>Cons</title> + + <para> + + It helps to know something about &Cons;. + &Cons; was first released in 1996 by Bob Sidebotham, + then an employee of Fore Systems, + and it has a number of + distinctive features that set it apart from most &Make;-alikes: + + </para> + + <itemizedlist> + + <listitem> + <para> + + &Cons; "configuration files" are not Yet Another + invented mini-language, but are actually <emphasis>Perl + scripts</emphasis>, which means the full power and flexibility of + a real scripting language can be applied to build problems. + + </para> + </listitem> + + <listitem> + <para> + + &Cons; builds everything from a single process at the top of the + source tree, with a global view of the dependencies. + + </para> + </listitem> + + <listitem> + <para> + + &Cons; scans files automatically for dependencies such as + files specified on <literal>#include</literal> lines. + + </para> + </listitem> + + <listitem> + <para> + + &Cons; decides if a file was out-of-date by using MD5 checksums of + the contents of files, not timestamps. + + </para> + </listitem> + + </itemizedlist> + + <para> + + Despite all of these intriguing architectural features, the great + strength of &Cons;—being written in Perl—was also one of + its weaknesses, turning away many potential users due to the + (real or perceived) steep learning curve of Perl. + + </para> + +</section> + +<section> + <title>&SCons;</title> + + <para> + + Through the &ScCons; contest entry, + &SCons; is the direct descendant of the &Cons; architecture, + and is currently + under active, supported development with a growing body of + users. Its first release was 13 December 2001, under the simple and + non-restrictive MIT license, and from the outset, the goal of the + members of the &SCons; project has been to deliver a stable, reliable + tool that can be used for industrial-strength software builds. + + </para> + + <para> + + The rest of this paper will give an overview of the &SCons; design + (including its architecture and interface), describe the development + methodology used, and discuss future directions for &SCons;. + + </para> + +</section> diff --git a/doc/python10/job-task.eps b/doc/python10/job-task.eps new file mode 100644 index 0000000..b3eeaff --- /dev/null +++ b/doc/python10/job-task.eps @@ -0,0 +1,238 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/job-task.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 416 236 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 236 moveto 0 0 lineto 416 0 lineto 416 236 lineto closepath clip newpath +-35.3 342.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 4200 3900 m 5100 3900 l 5100 4500 l 4200 4500 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4650 4275 m +gs 1 -1 sc (Task) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 4200 5100 m 5100 5100 l 5100 5700 l 4200 5700 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4650 5475 m +gs 1 -1 sc (Node) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 6300 2100 m 7200 2100 l 7200 2700 l 6300 2700 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +6750 2475 m +gs 1 -1 sc (Sig) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 6300 3300 m 7500 3300 l 7500 3900 l 6300 3900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +6900 3675 m +gs 1 -1 sc (Walker) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 4200 2100 m 5700 2100 l 5700 2700 l 4200 2700 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4950 2475 m +gs 1 -1 sc (TaskMaster) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 2400 3300 m 3600 3300 l 3600 3900 l 2400 3900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3000 3675 m +gs 1 -1 sc (Parallel) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 600 3300 m 1800 3300 l 1800 3900 l 600 3900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1200 3675 m +gs 1 -1 sc (Serial) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 1200 2100 m 3000 2100 l 3000 2700 l 1200 2700 l + cp gs col0 s gr +/Times-Roman ff 255.00 scf sf +2099 2475 m +gs 1 -1 sc (Jobs) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 2700 2700 m 2660 2775 l 2700 2850 l 2740 2775 l + cp gs col0 s gr +% Polyline +n 5700 2400 m 5775 2440 l 5850 2400 l 5775 2360 l + cp gs col0 s gr +% Polyline +n 5400 2700 m 5360 2775 l 5400 2850 l 5440 2775 l + cp gs col0 s gr +% Polyline +n 4650 2700 m 4610 2775 l 4650 2850 l 4690 2775 l + cp gs col0 s gr +% Polyline +n 1500 2700 m 1460 2775 l 1500 2850 l 1540 2775 l + cp gs col0 s gr +% Polyline +n 4650 4500 m 4610 4575 l 4650 4650 l 4690 4575 l + cp gs col0 s gr +% Polyline +gs clippath +1470 3315 m 1530 3315 l 1530 3164 l 1500 3284 l 1470 3164 l cp +eoclip +n 1500 2850 m + 1500 3300 l gs col0 s gr gr + +% arrowhead +n 1470 3164 m 1500 3284 l 1530 3164 l 1470 3164 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +2670 3315 m 2730 3315 l 2730 3164 l 2700 3284 l 2670 3164 l cp +eoclip +n 2700 2850 m + 2700 3300 l gs col0 s gr gr + +% arrowhead +n 2670 3164 m 2700 3284 l 2730 3164 l 2670 3164 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4620 3915 m 4680 3915 l 4680 3764 l 4650 3884 l 4620 3764 l cp +eoclip +n 4650 2850 m + 4650 3900 l gs col0 s gr gr + +% arrowhead +n 4620 3764 m 4650 3884 l 4680 3764 l 4620 3764 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4620 5115 m 4680 5115 l 4680 4964 l 4650 5084 l 4620 4964 l cp +eoclip +n 4650 4650 m + 4650 5100 l gs col0 s gr gr + +% arrowhead +n 4620 4964 m 4650 5084 l 4680 4964 l 4620 4964 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +6315 3630 m 6315 3570 l 6164 3570 l 6284 3600 l 6164 3630 l cp +eoclip +n 5400 2850 m 5400 3600 l + 6300 3600 l gs col0 s gr gr + +% arrowhead +n 6164 3630 m 6284 3600 l 6164 3570 l 6164 3630 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +6315 2430 m 6315 2370 l 6164 2370 l 6284 2400 l 6164 2430 l cp +eoclip +n 5850 2400 m + 6300 2400 l gs col0 s gr gr + +% arrowhead +n 6164 2430 m 6284 2400 l 6164 2370 l 6164 2430 l cp gs 0.00 setgray ef gr col0 s +% Polyline +n 3000 2400 m 3075 2440 l 3150 2400 l 3075 2360 l + cp gs col0 s gr +% Polyline +gs clippath +4215 2430 m 4215 2370 l 4064 2370 l 4184 2400 l 4064 2430 l cp +eoclip +n 3150 2400 m + 4200 2400 l gs col0 s gr gr + +% arrowhead +n 4064 2430 m 4184 2400 l 4064 2370 l 4064 2430 l cp gs 0.00 setgray ef gr col0 s +% Polyline + [60] 0 sd +n 2100 2100 m + 2100 1800 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 4950 2100 m + 4950 1800 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 6750 2100 m + 6750 1800 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/job-task.fig b/doc/python10/job-task.fig new file mode 100644 index 0000000..6febd97 --- /dev/null +++ b/doc/python10/job-task.fig @@ -0,0 +1,90 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +6 4200 3900 5100 4500 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 4200 3900 5100 3900 5100 4500 4200 4500 4200 3900 +4 1 0 50 0 0 16 0.0000 4 165 465 4650 4275 Task\001 +-6 +6 4200 5100 5100 5700 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 4200 5100 5100 5100 5100 5700 4200 5700 4200 5100 +4 1 0 50 0 0 16 0.0000 4 165 525 4650 5475 Node\001 +-6 +6 6300 2100 7200 2700 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 6300 2100 7200 2100 7200 2700 6300 2700 6300 2100 +4 1 0 50 0 0 16 0.0000 4 225 330 6750 2475 Sig\001 +-6 +6 6300 3300 7500 3900 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 6300 3300 7500 3300 7500 3900 6300 3900 6300 3300 +4 1 0 50 0 0 16 0.0000 4 165 735 6900 3675 Walker\001 +-6 +6 4200 2100 5700 2700 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 4200 2100 5700 2100 5700 2700 4200 2700 4200 2100 +4 1 0 50 0 0 16 0.0000 4 165 1155 4950 2475 TaskMaster\001 +-6 +6 2400 3300 3600 3900 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2400 3300 3600 3300 3600 3900 2400 3900 2400 3300 +4 1 0 50 0 0 16 0.0000 4 165 765 3000 3675 Parallel\001 +-6 +6 600 3300 1800 3900 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 600 3300 1800 3300 1800 3900 600 3900 600 3300 +4 1 0 50 0 0 16 0.0000 4 165 585 1200 3675 Serial\001 +-6 +6 1200 2100 3000 2700 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1200 2100 3000 2100 3000 2700 1200 2700 1200 2100 +4 1 0 50 0 0 17 0.0000 4 165 420 2099 2475 Jobs\001 +-6 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 2700 2700 2660 2775 2700 2850 2740 2775 2700 2700 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 5700 2400 5775 2440 5850 2400 5775 2360 5700 2400 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 5400 2700 5360 2775 5400 2850 5440 2775 5400 2700 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 4650 2700 4610 2775 4650 2850 4690 2775 4650 2700 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 1500 2700 1460 2775 1500 2850 1540 2775 1500 2700 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 4650 4500 4610 4575 4650 4650 4690 4575 4650 4500 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 1500 2850 1500 3300 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 2700 2850 2700 3300 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 4650 2850 4650 3900 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 4650 4650 4650 5100 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 + 1 1 1.00 60.00 120.00 + 5400 2850 5400 3600 6300 3600 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 5850 2400 6300 2400 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 3000 2400 3075 2440 3150 2400 3075 2360 3000 2400 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3150 2400 4200 2400 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 2100 2100 2100 1800 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 4950 2100 4950 1800 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 6750 2100 6750 1800 diff --git a/doc/python10/job-task.jpg b/doc/python10/job-task.jpg Binary files differnew file mode 100644 index 0000000..ff3ded0 --- /dev/null +++ b/doc/python10/job-task.jpg diff --git a/doc/python10/main.xml b/doc/python10/main.xml new file mode 100644 index 0000000..42bc4af --- /dev/null +++ b/doc/python10/main.xml @@ -0,0 +1,221 @@ +<?xml version="1.0"?> + +<!-- + + Copyright (c) 2001, 2002, 2003 Steven Knight + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + + <!ENTITY % scons SYSTEM "scons.mod"> + %scons; + + <!ENTITY abstract SYSTEM "abstract.xml"> + <!ENTITY acks SYSTEM "acks.xml"> + <!ENTITY copyright SYSTEM "copyright.xml"> + <!ENTITY design SYSTEM "design.xml"> + <!ENTITY future SYSTEM "future.xml"> + <!ENTITY install SYSTEM "install.xml"> + <!ENTITY intro SYSTEM "intro.xml"> + <!ENTITY process SYSTEM "process.xml"> + +]> + +<article> + <articleinfo> + <title>SCons Design and Implementation</title> + + <author> + <firstname>Steven</firstname> + <surname>Knight</surname> + </author> + + <copyright> + <year>2001</year> + <year>2002</year> + <holder>Steven Knight</holder> + </copyright> + + <pubdate>2002</pubdate> + + <confgroup> + <confdates>4-7 February 2002</confdates> + <conftitle>The Tenth International Python Conference</conftitle> + <address>Alexandria, Virginia</address> + </confgroup> + + <revhistory> + <revision> + <revnumber>0.2</revnumber> + <date>16 December 2001</date> + <revremark>Internal re-review.</revremark> + </revision> + <revision> + <revnumber>0.1</revnumber> + <date>8 October 2001</date> + <revremark>Submitted for Python10 conference.</revremark> + </revision> + </revhistory> + + </articleinfo> + + <abstract> + &abstract; + </abstract> + + <section id="sect-intro"> + <title>Introduction</title> + &intro; + </section> + + <section id="sect-design"> + <title>Architecture</title> + &design; + </section> + + <section id="sect-install"> + <title>Installation</title> + &install; + </section> + + <section id="sect-process"> + <title>Development Process</title> + &process; + </section> + + <section id="sect-future"> + <title>Future Directions</title> + &future; + </section> + + <section id="sect-summary"> + <title>Summary</title> + <para> + + This paper has introduced &SCons;, a next-generation build tool + with a modular, embeddable architecture and a direct Python + interface. &SCons; has a global view of the dependencies in a source + tree, uses MD5 signatures to decide if derived files are out of date, + and automatically scans files for dependencies, all of which make &SCons; + builds exceptionally reliable. The &SCons; development methodology has + been described, notable for its emphasis on automated regression + testing to ensure a robust and reliable tool from day one. Several + future directions for &SCons; have also been discussed. + + </para> + </section> + + <section id="sect-acks"> + <title>Acknowledgements</title> + &acks; + </section> + + <!-- + <section id="sect-refs"> + <title>References</title> + <para> + </para> + </section> + --> + + <bibliography id="sect-refs"> + <title>References</title> + + <biblioentry> + <abbrev>1</abbrev> + <authorgroup> + <author><firstname>Stuart I.</firstname><surname>Feldman</surname></author> + </authorgroup> + <copyright> + <year>Aug 1978</year> + </copyright> + <publisher> + <publishername>Bell Laboratories</publishername> + </publisher> + <title>Make - A Program for Maintaining Computer Programs</title> + </biblioentry> + + <biblioentry> + <abbrev>2</abbrev> + <authorgroup> + <author><firstname>Peter</firstname><surname>Miller</surname></author> + </authorgroup> + <copyright> + <year>1997</year> + <holder>Peter Miller</holder> + </copyright> + <title>Recursive Make Considered Harmful</title> + <!--http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html--> + </biblioentry> + + <biblioentry> + <abbrev>3</abbrev> + <authorgroup> + <author><firstname>Andrew</firstname><surname>Oram</surname></author> + <author><firstname>Steve</firstname><surname>Talbott</surname></author> + </authorgroup> + <copyright> + <year>1986</year> + <year>1991</year> + <holder>O'Reilly & Associates, Inc.</holder> + </copyright> + <publisher> + <publishername>O'Reilly & Associates, Inc.</publishername> + </publisher> + <title>Managing Projects with Make, 2nd Ed.</title> + </biblioentry> + + <biblioentry> + <abbrev>4</abbrev> + <authorgroup> + <author><firstname>Richard M.</firstname><surname>Stallman</surname></author> + <author><firstname>Roland</firstname><surname>McGrath</surname></author> + </authorgroup> + <copyright> + <year>1988</year> + <year>'89</year> + <year>'90</year> + <year>'91</year> + <year>'92</year> + <year>'93</year> + <year>'94</year> + <year>'95</year> + <year>'96</year> + <year>'97</year> + <year>'98</year> + <year>'99</year> + <year>2000</year> + <holder>Free Software Foundation, Inc.</holder> + </copyright> + <publisher> + <publishername>Free Software Foundation, Inc.</publishername> + </publisher> + <title>GNU Make</title> + <subtitle>A Program for Directing Recompilation</subtitle> + </biblioentry> + + </bibliography> + +</article> diff --git a/doc/python10/node.eps b/doc/python10/node.eps new file mode 100644 index 0000000..995235d --- /dev/null +++ b/doc/python10/node.eps @@ -0,0 +1,351 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/node.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 452 362 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 362 moveto 0 0 lineto 452 0 lineto 452 362 lineto closepath clip newpath +0.7 414.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 2700 1200 m 4500 1200 l 4500 1800 l 2700 1800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +2925 1575 m +gs 1 -1 sc (Environment) col0 sh gr +% Polyline +n 2700 3600 m 4500 3600 l 4500 4200 l 2700 4200 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3375 3975 m +gs 1 -1 sc (Node) col0 sh gr +% Polyline +n 5700 1800 m 6900 1800 l 6900 2400 l 5700 2400 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +5925 2175 m +gs 1 -1 sc (Walker) col0 sh gr +% Polyline +n 2100 2400 m 3300 2400 l 3300 3000 l 2100 3000 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +2325 2775 m +gs 1 -1 sc (Builder) col0 sh gr +% Polyline +n 3900 2400 m 5100 2400 l 5100 3000 l 3900 3000 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4125 2775 m +gs 1 -1 sc (Scanner) col0 sh gr +% Polyline +n 2400 6300 m 3300 6300 l 3300 6900 l 2400 6900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +2700 6675 m +gs 1 -1 sc (Dir) col0 sh gr +% Polyline +n 0 6300 m 900 6300 l 900 6900 l 0 6900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +150 6675 m +gs 1 -1 sc (Entry) col0 sh gr +% Polyline +n 1200 6300 m 2100 6300 l 2100 6900 l 1200 6900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1425 6675 m +gs 1 -1 sc (File) col0 sh gr +% Polyline +n 1050 5100 m 2250 5100 l 2250 5700 l 1050 5700 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1200 5475 m +gs 1 -1 sc (Node.FS) col0 sh gr +% Polyline +n 1650 5700 m 1575 5850 l 1725 5850 l + cp gs col0 s gr +% Polyline +n 450 6300 m 450 6000 l 2700 6000 l + 2700 6300 l gs col0 s gr +% Polyline +n 1650 6300 m + 1650 5850 l gs col0 s gr +% Polyline + [60] 0 sd +n 5100 6300 m 6300 6300 l 6300 6900 l 5100 6900 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +5325 6675 m +gs 1 -1 sc (Record) col0 sh gr +% Polyline + [60] 0 sd +n 6600 6300 m 7500 6300 l 7500 6900 l 6600 6900 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +6750 6675 m +gs 1 -1 sc (Field) col0 sh gr +% Polyline + [60] 0 sd +n 4950 5100 m 6150 5100 l 6150 5700 l 4950 5700 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +5100 5475 m +gs 1 -1 sc (Node.DB) col0 sh gr +% Polyline +n 5550 5700 m 5475 5850 l 5625 5850 l + cp gs col0 s gr +% Polyline + [60] 0 sd +n 4350 6300 m 4350 6000 l 7050 6000 l + 7050 6300 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 5550 5850 m + 5550 6300 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 3900 6300 m 4800 6300 l 4800 6900 l 3900 6900 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +4050 6675 m +gs 1 -1 sc (Table) col0 sh gr +% Polyline +n 5700 3000 m 6900 3000 l 6900 3600 l 5700 3600 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +5850 3375 m +gs 1 -1 sc (Wrapper) col0 sh gr +% Polyline +n 900 1200 m 1800 1200 l 1800 1800 l 900 1800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1200 1575 m +gs 1 -1 sc (FS) col0 sh gr +% Polyline +n 3600 4200 m 3525 4350 l 3675 4350 l + cp gs col0 s gr +% Polyline +n 1800 5100 m 1800 4800 l 5550 4800 l + 5550 5100 l gs col0 s gr +% Polyline +n 3600 4800 m + 3600 4350 l gs col0 s gr +% Polyline +n 4200 1800 m 4160 1875 l 4200 1950 l 4240 1875 l + cp gs col0 s gr +% Polyline +n 3000 6150 m 2960 6225 l 3000 6300 l 3040 6225 l + cp gs col0 s gr +% Polyline +n 6300 3600 m 6260 3675 l 6300 3750 l 6340 3675 l + cp gs col0 s gr +% Polyline +n 6300 2400 m 6260 2475 l 6300 2550 l 6340 2475 l + cp gs col0 s gr +% Polyline +n 3000 4200 m 2960 4275 l 3000 4350 l 3040 4275 l + cp gs col0 s gr +% Polyline +n 4200 3450 m 4160 3525 l 4200 3600 l 4240 3525 l + cp gs col0 s gr +% Polyline +n 3000 3450 m 2960 3525 l 3000 3600 l 3040 3525 l + cp gs col0 s gr +% Polyline +gs clippath +2235 5370 m 2235 5430 l 2386 5430 l 2266 5400 l 2386 5370 l cp +eoclip +n 3000 6150 m 3000 5400 l + 2250 5400 l gs col0 s gr gr + +% arrowhead +n 2386 5370 m 2266 5400 l 2386 5430 l 2386 5370 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +2715 3930 m 2715 3870 l 2564 3870 l 2684 3900 l 2564 3930 l cp +eoclip +n 3000 4350 m 3000 4500 l 1800 4500 l 1800 3900 l + 2700 3900 l gs col0 s gr gr + +% arrowhead +n 2564 3930 m 2684 3900 l 2564 3870 l 2564 3930 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4485 3870 m 4485 3930 l 4636 3930 l 4516 3900 l 4636 3870 l cp +eoclip +n 6300 3750 m 6300 3900 l + 4500 3900 l gs col0 s gr gr + +% arrowhead +n 4636 3870 m 4516 3900 l 4636 3930 l 4636 3870 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4230 2985 m 4170 2985 l 4170 3136 l 4200 3016 l 4230 3136 l cp +eoclip +n 4200 3450 m + 4200 3000 l gs col0 s gr gr + +% arrowhead +n 4230 3136 m 4200 3016 l 4170 3136 l 4230 3136 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3030 2985 m 2970 2985 l 2970 3136 l 3000 3016 l 3030 3136 l cp +eoclip +n 3000 3450 m + 3000 3000 l gs col0 s gr gr + +% arrowhead +n 3030 3136 m 3000 3016 l 2970 3136 l 3030 3136 l cp gs 0.00 setgray ef gr col0 s +% Polyline +n 3000 1800 m 2960 1875 l 3000 1950 l 3040 1875 l + cp gs col0 s gr +% Polyline +gs clippath +2970 2415 m 3030 2415 l 3030 2264 l 3000 2384 l 2970 2264 l cp +eoclip +n 3000 1950 m + 3000 2400 l gs col0 s gr gr + +% arrowhead +n 2970 2264 m 3000 2384 l 3030 2264 l 2970 2264 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4170 2415 m 4230 2415 l 4230 2264 l 4200 2384 l 4170 2264 l cp +eoclip +n 4200 1950 m + 4200 2400 l gs col0 s gr gr + +% arrowhead +n 4170 2264 m 4200 2384 l 4230 2264 l 4170 2264 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +6270 3015 m 6330 3015 l 6330 2864 l 6300 2984 l 6270 2864 l cp +eoclip +n 6300 2550 m + 6300 3000 l gs col0 s gr gr + +% arrowhead +n 6270 2864 m 6300 2984 l 6330 2864 l 6270 2864 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4785 6570 m 4785 6630 l 4936 6630 l 4816 6600 l 4936 6570 l cp +eoclip +n 5100 6600 m + 4800 6600 l gs col0 s gr gr + +% arrowhead +n 4936 6570 m 4816 6600 l 4936 6630 l 4936 6570 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +6285 6570 m 6285 6630 l 6436 6630 l 6316 6600 l 6436 6570 l cp +eoclip +n 6600 6600 m + 6300 6600 l gs col0 s gr gr + +% arrowhead +n 6436 6570 m 6316 6600 l 6436 6630 l 6436 6570 l cp gs 0.00 setgray ef gr col0 s +% Polyline +n 1350 1800 m 1310 1875 l 1350 1950 l 1390 1875 l + cp gs col0 s gr +% Polyline +gs clippath +1320 5115 m 1380 5115 l 1380 4964 l 1350 5084 l 1320 4964 l cp +eoclip +n 1350 1950 m + 1350 5100 l gs col0 s gr gr + +% arrowhead +n 1320 4964 m 1350 5084 l 1380 4964 l 1320 4964 l cp gs 0.00 setgray ef gr col0 s +% Polyline + [60] 0 sd +n 1350 1200 m + 1350 900 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 3600 1200 m + 3600 900 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/node.fig b/doc/python10/node.fig new file mode 100644 index 0000000..3c40f07 --- /dev/null +++ b/doc/python10/node.fig @@ -0,0 +1,165 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +6 2700 1200 4500 1800 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2700 1200 4500 1200 4500 1800 2700 1800 2700 1200 +4 0 0 50 0 0 16 0.0000 4 165 1290 2925 1575 Environment\001 +-6 +6 2700 3600 4500 4200 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2700 3600 4500 3600 4500 4200 2700 4200 2700 3600 +4 0 0 50 0 0 16 0.0000 4 165 525 3375 3975 Node\001 +-6 +6 5700 1800 6900 2400 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 5700 1800 6900 1800 6900 2400 5700 2400 5700 1800 +4 0 0 50 0 0 16 0.0000 4 165 735 5925 2175 Walker\001 +-6 +6 2100 2400 3300 3000 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2100 2400 3300 2400 3300 3000 2100 3000 2100 2400 +4 0 0 50 0 0 16 0.0000 4 165 750 2325 2775 Builder\001 +-6 +6 3900 2400 5100 3000 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3900 2400 5100 2400 5100 3000 3900 3000 3900 2400 +4 0 0 50 0 0 16 0.0000 4 165 780 4125 2775 Scanner\001 +-6 +6 0 5100 3300 6900 +6 2400 6300 3300 6900 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2400 6300 3300 6300 3300 6900 2400 6900 2400 6300 +4 0 0 50 0 0 16 0.0000 4 165 345 2700 6675 Dir\001 +-6 +6 0 6300 900 6900 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 0 6300 900 6300 900 6900 0 6900 0 6300 +4 0 0 50 0 0 16 0.0000 4 225 555 150 6675 Entry\001 +-6 +6 1200 6300 2100 6900 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1200 6300 2100 6300 2100 6900 1200 6900 1200 6300 +4 0 0 50 0 0 16 0.0000 4 165 390 1425 6675 File\001 +-6 +6 1050 5100 2250 5700 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1050 5100 2250 5100 2250 5700 1050 5700 1050 5100 +4 0 0 50 0 0 16 0.0000 4 165 855 1200 5475 Node.FS\001 +-6 +6 450 5700 2700 6300 +2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 1650 5700 1575 5850 1725 5850 1650 5700 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 450 6300 450 6000 2700 6000 2700 6300 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 + 1650 6300 1650 5850 +-6 +-6 +6 3900 5100 7500 6900 +6 5100 6300 6300 6900 +2 2 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5 + 5100 6300 6300 6300 6300 6900 5100 6900 5100 6300 +4 0 0 50 0 0 16 0.0000 4 165 705 5325 6675 Record\001 +-6 +6 6600 6300 7500 6900 +2 2 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5 + 6600 6300 7500 6300 7500 6900 6600 6900 6600 6300 +4 0 0 50 0 0 16 0.0000 4 165 510 6750 6675 Field\001 +-6 +6 4950 5100 6150 5700 +2 2 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5 + 4950 5100 6150 5100 6150 5700 4950 5700 4950 5100 +4 0 0 50 0 0 16 0.0000 4 165 930 5100 5475 Node.DB\001 +-6 +6 4350 5700 7050 6300 +2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 5550 5700 5475 5850 5625 5850 5550 5700 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 + 4350 6300 4350 6000 7050 6000 7050 6300 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 5550 5850 5550 6300 +-6 +6 3900 6300 4800 6900 +2 2 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5 + 3900 6300 4800 6300 4800 6900 3900 6900 3900 6300 +4 0 0 50 0 0 16 0.0000 4 165 555 4050 6675 Table\001 +-6 +-6 +6 5700 3000 6900 3600 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 5700 3000 6900 3000 6900 3600 5700 3600 5700 3000 +4 0 0 50 0 0 16 0.0000 4 225 870 5850 3375 Wrapper\001 +-6 +6 900 1200 1800 1800 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 900 1200 1800 1200 1800 1800 900 1800 900 1200 +4 0 0 50 0 0 16 0.0000 4 165 270 1200 1575 FS\001 +-6 +2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 3600 4200 3525 4350 3675 4350 3600 4200 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 1800 5100 1800 4800 5550 4800 5550 5100 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 + 3600 4800 3600 4350 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 4200 1800 4160 1875 4200 1950 4240 1875 4200 1800 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 3000 6150 2960 6225 3000 6300 3040 6225 3000 6150 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 6300 3600 6260 3675 6300 3750 6340 3675 6300 3600 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 6300 2400 6260 2475 6300 2550 6340 2475 6300 2400 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 3000 4200 2960 4275 3000 4350 3040 4275 3000 4200 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 4200 3450 4160 3525 4200 3600 4240 3525 4200 3450 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 3000 3450 2960 3525 3000 3600 3040 3525 3000 3450 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 3 + 1 1 1.00 60.00 120.00 + 3000 6150 3000 5400 2250 5400 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 5 + 1 1 1.00 60.00 120.00 + 3000 4350 3000 4500 1800 4500 1800 3900 2700 3900 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 3 + 1 1 1.00 60.00 120.00 + 6300 3750 6300 3900 4500 3900 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 1 1 1.00 60.00 120.00 + 4200 3450 4200 3000 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 1 1 1.00 60.00 120.00 + 3000 3450 3000 3000 +2 3 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5 + 3000 1800 2960 1875 3000 1950 3040 1875 3000 1800 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 1 1 1.00 60.00 120.00 + 3000 1950 3000 2400 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 1 1 1.00 60.00 120.00 + 4200 1950 4200 2400 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 1 1 1.00 60.00 120.00 + 6300 2550 6300 3000 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 1 1 1.00 60.00 120.00 + 5100 6600 4800 6600 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 1 1 1.00 60.00 120.00 + 6600 6600 6300 6600 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 1350 1800 1310 1875 1350 1950 1390 1875 1350 1800 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 1 1 1.00 60.00 120.00 + 1350 1950 1350 5100 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 1350 1200 1350 900 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 3600 1200 3600 900 diff --git a/doc/python10/node.jpg b/doc/python10/node.jpg Binary files differnew file mode 100644 index 0000000..98ceb5e --- /dev/null +++ b/doc/python10/node.jpg diff --git a/doc/python10/process.xml b/doc/python10/process.xml new file mode 100644 index 0000000..f1b2479 --- /dev/null +++ b/doc/python10/process.xml @@ -0,0 +1,353 @@ +<para> + + The &SCons; project has paid particular attention from day one to the + development process. One of the first internal documents produced was + a set of Developer's Guidelines to provide a loose framework for what + we were trying to accomplish and how we would go about accomplishing + it. These Guidelines cover things like: + +</para> + +<itemizedlist> + + <listitem> + <para> + + &SCons; will be written to Python version 1.5.2 (to ensure + usability by a wide install base). + + </para> + </listitem> + + <listitem> + <para> + + How &SCons; is be tested: which infrastructure modules to use, + what platforms to test on, etc. + + </para> + </listitem> + + <listitem> + <para> + + Expectations for developers (subscribe to the mailing list, + encouraged to register at SourceForge). + + </para> + </listitem> + + <listitem> + <para> + + Brief outline of how to use the change management systems (Aegis and + CVS) for &SCons; development;. + + </para> + </listitem> + +</itemizedlist> + +<para> + + Establishing these guidelines up front had two purposes: 1) + Demonstrate the seriousness of the project to anyone wondering about + joining the effort; 2) Give potential developers an idea up front as + to whether their development style would mesh with the rest of the + project. + +</para> + +<section> + <title>Aegis</title> + + <para> + + One of the most important aspects of the &SCons; development process + is the use of Peter Miller's Aegis change management system. I + had been using Aegis for personal projects for several years, and + found its development methodology vastly improved the quality of my + programming. I was consequently committed to using it for &SCons; + development. + + </para> + + <para> + + Aegis provides a number of things, including: + + </para> + + <itemizedlist> + + <listitem> + <para> + + A flexible source code control and branching model. + + </para> + </listitem> + + <listitem> + <para> + + A defined process with separate development, review and + integration steps. + + </para> + </listitem> + + <listitem> + <para> + + A distributed development model based on distribution of atomic + change sets. + + </para> + </listitem> + + </itemizedlist> + + <para> + + The single most important reason for using Aegis, however, is its + management of automated tests as part of the development process. + + </para> + +</section> + +<section> + <title>Testing, Testing, Testing</title> + + <para> + + The &SCons; project has made extensive use of automated tests from day + one, taking inspiration mostly from Aegis, partly from the eXtreme + Programming model, and with a little home-brew scripting for glue. + + </para> + + <section> + <title>Testing Criteria</title> + + <para> + + The underlying criteria for testing changes to the &SCons; code + are taken from Aegis: + + </para> + + <itemizedlist> + + <listitem> + <para> + + Every change must have one or more new or modified tests + checked in along with the code. + + </para> + </listitem> + + <listitem> + <para> + + The new code being checked in must pass all of the new and/or + modified tests. + + </para> + </listitem> + + <listitem> + <para> + + The <emphasis>old</emphasis>, already checked-in code in must + <emphasis>fail</emphasis> all of the new and/or modified + tests. + + </para> + </listitem> + + <listitem> + <para> + + The new code being checked in must pass all unmodified, + already checked-in tests. + + </para> + </listitem> + + </itemizedlist> + + <para> + + In practice, these restrictions can be overridden as necessaryfor + example, when changing comments or documentation. + + </para> + + <para> + + The criterion that surprises many people is having the old code + fail the tests in the change. This makes sure that the new tests + or modified tests really do exercise the bug fix or feature being + added by the change. + + </para> + + <para> + + Together, these criteria ensure that every newly checked-in + version &SCons; conforms to defined behavior, as defined by + the tests. Whenever a bug is found, its fix is checked in with + a new or modified test that guarantees the bug will not recur + in the future. We have already built up a regression test base + of almost 90 tests that cover the vast majority of &SCons;' + functionality. + + </para> + + </section> + + <section> + <title>Testing Infrastructure</title> + + <para> + + Testing standards are no good if they're too much of a burden for + developers, who will at best work around or ignore the testing + requirements, or at worst stop contributing code and go join a + project that's more fun. To this end, good testing infrastructure + that makes it easy to write tests is crucial. + + </para> + + <para> + + &SCons; development uses two development methodologies, one for + the individual modules in the build engine, and the other for + end-to-end tests of the &SCons; script. + + </para> + + <para> + + For the build engine modules, we use PyUnit. Every change to a + build engine module must have a change to its corresponding unit + tests, which live side-by-side in a separate file that imports + module. As we build up a large body of unit tests, this ensures + that the build engine will perform correctly whenever someone uses + it in some application other than the &SCons; script itself. + + </para> + + <para> + + For end-to-end script tests, we have developed two modules to make + writing tests easy. The first, <filename>TestCmd.py</filename>, + is a generic module for + testing commands or scripts (in any language, not just Python). + + The second module, <filename>TestScons.py</filename>, + is a subclass of the generic + <filename>TestCmd.py</filename> module. + <filename>TestScons.py</filename> + takes care of initialization and + displaying error conditions + specific to testing &SCons;. + + </para> + + <para> + + In practice, simple tests only + need to initialize a test object, use the object to write some + input files, run &SCons;, and then check whatever criteria + determine whether the test passed or failed. A complete test of + the &Program; method, for example, looks like this: + + </para> + + <programlisting> + test = TestSCons.TestSCons() + + test.write('SConstruct', + """env = Environment() + env.Program(target = 'foo', source = 'foo.c') + """) + + test.write('foo.c', + """ + int + main(int argc, char *argv[]) + { + argv[argc++] = "-"; /* dummy use of args */ + printf("foo.c successfully compiled\\n"); + exit (0); + } + """) + + test.run(arguments = 'foo') # runs SCons + + test.run(program = test.workpath('foo')) + + test.fail_test(test.stdout() != "foo.c successfully compiled\n") + + test.pass_test() + </programlisting> + + </section> + +</section> + +<section> + <title>SourceForge</title> + + <para> + + Registration of the &SCons; project was approved at SourceForge on + 29 June 2001. Within a week, the initial code base was checked in, + mailing lists were created, and the web site was set up. We started + making use of the task-list manager to track what we had to finish + for initial release. + + </para> + + <para> + + The obvious complication was how to use + structured testing methodology of Aegis when SourceForge uses + CVS for source control. Not using the SourceForge CVS tree would + have had two significant disadvantages: one, missing out on the + archiving and central location in the event of disaster; two, people + coming to the SourceForge project page wouldn't be able to browse + the source. The latter was particularly important in + the early stages of development, in order to avoid any impression + that this was Yet Another Project that starts with a bang and then + dwindles as the initial enthusiasm starts to wear off. + + </para> + + <para> + + The solution was to use the SourceForge CVS repository for read-only + access to the source. &SCons; developers are welcome to use CVS for + their development, but the changes are <emphasis>not</emphasis> + committed to the SourceForge repository. Instead, patches are sent + to the integrator for processing through Aegis. When the change + has been integrated into the Aegis repository, a home-brew + script translates the Aegis change into a virtual shell script + of commands that copy the necessary files from Aegis and check them + in to CVS at SourceForge. + + </para> + + <para> + + (In practice, write access is not actually disabled for registered + developers, but if they do make any changes directly at SourceForge, + they can be overwritten at the next Aegis update.) + + </para> + +</section> diff --git a/doc/python10/scanner.eps b/doc/python10/scanner.eps new file mode 100644 index 0000000..35614f8 --- /dev/null +++ b/doc/python10/scanner.eps @@ -0,0 +1,168 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/scanner.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 398 200 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 200 moveto 0 0 lineto 398 0 lineto 398 200 lineto closepath clip newpath +-17.3 360.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 2700 5400 m 4500 5400 l 4500 6000 l 2700 6000 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3000 5775 m +gs 1 -1 sc (ProgScanner) col0 sh gr +% Polyline +n 2700 4200 m 4500 4200 l 4500 4800 l 2700 4800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3225 4575 m +gs 1 -1 sc (Scanner) col0 sh gr +% Polyline +n 2700 3000 m 4500 3000 l 4500 3600 l 2700 3600 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +2925 3375 m +gs 1 -1 sc (Environment) col0 sh gr +% Polyline + [60] 0 sd +n 5100 5400 m 6900 5400 l 6900 6000 l 5100 6000 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +5400 5775 m +gs 1 -1 sc (JavaScanner) col0 sh gr +% Polyline +n 300 5400 m 2100 5400 l 2100 6000 l 300 6000 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +750 5775 m +gs 1 -1 sc (CScanner) col0 sh gr +% Polyline +n 600 3300 m 1500 3300 l 1500 3900 l 600 3900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +825 3675 m +gs 1 -1 sc (Node) col0 sh gr +% Polyline +n 1200 5400 m 1200 5100 l 6000 5100 l + 6000 5400 l gs col0 s gr +% Polyline +n 3600 4950 m + 3600 5400 l gs col0 s gr +% Polyline +n 3600 4800 m 3525 4950 l 3675 4950 l + cp gs col0 s gr +% Polyline +n 3600 3600 m 3560 3675 l 3600 3750 l 3640 3675 l + cp gs col0 s gr +% Polyline +n 1050 3900 m 1010 3975 l 1050 4050 l 1090 3975 l + cp gs col0 s gr +% Polyline +gs clippath +2715 4530 m 2715 4470 l 2564 4470 l 2684 4500 l 2564 4530 l cp +eoclip +n 1050 4050 m 1050 4500 l + 2700 4500 l gs col0 s gr gr + +% arrowhead +n 2564 4530 m 2684 4500 l 2564 4470 l 2564 4530 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3570 4215 m 3630 4215 l 3630 4064 l 3600 4184 l 3570 4064 l cp +eoclip +n 3600 3750 m + 3600 4200 l gs col0 s gr gr + +% arrowhead +n 3570 4064 m 3600 4184 l 3630 4064 l 3570 4064 l cp gs 0.00 setgray ef gr col0 s +% Polyline + [60] 0 sd +n 3600 3000 m + 3600 2700 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/scanner.fig b/doc/python10/scanner.fig new file mode 100644 index 0000000..01488e8 --- /dev/null +++ b/doc/python10/scanner.fig @@ -0,0 +1,57 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +6 2700 5400 4500 6000 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2700 5400 4500 5400 4500 6000 2700 6000 2700 5400 +4 0 0 50 0 0 16 0.0000 4 225 1245 3000 5775 ProgScanner\001 +-6 +6 2700 4200 4500 4800 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2700 4200 4500 4200 4500 4800 2700 4800 2700 4200 +4 0 0 50 0 0 16 0.0000 4 165 780 3225 4575 Scanner\001 +-6 +6 2700 3000 4500 3600 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2700 3000 4500 3000 4500 3600 2700 3600 2700 3000 +4 0 0 50 0 0 16 0.0000 4 165 1290 2925 3375 Environment\001 +-6 +6 5100 5400 6900 6000 +2 2 1 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 5100 5400 6900 5400 6900 6000 5100 6000 5100 5400 +4 0 0 50 0 0 16 0.0000 4 165 1200 5400 5775 JavaScanner\001 +-6 +6 300 5400 2100 6000 +2 2 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 300 5400 2100 5400 2100 6000 300 6000 300 5400 +4 0 0 50 0 0 16 0.0000 4 165 945 750 5775 CScanner\001 +-6 +6 600 3300 1500 3900 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 600 3300 1500 3300 1500 3900 600 3900 600 3300 +4 0 0 50 0 0 16 0.0000 4 165 525 825 3675 Node\001 +-6 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 + 1200 5400 1200 5100 6000 5100 6000 5400 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 3600 4950 3600 5400 +2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 3600 4800 3525 4950 3675 4950 3600 4800 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 3600 3600 3560 3675 3600 3750 3640 3675 3600 3600 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 1050 3900 1010 3975 1050 4050 1090 3975 1050 3900 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 0 3 + 1 1 1.00 60.00 120.00 + 1050 4050 1050 4500 2700 4500 +2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3600 3750 3600 4200 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 3600 3000 3600 2700 diff --git a/doc/python10/scanner.jpg b/doc/python10/scanner.jpg Binary files differnew file mode 100644 index 0000000..08e5dcb --- /dev/null +++ b/doc/python10/scanner.jpg diff --git a/doc/python10/scons.mod b/doc/python10/scons.mod new file mode 100644 index 0000000..8df6d2c --- /dev/null +++ b/doc/python10/scons.mod @@ -0,0 +1,428 @@ +<!-- + + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation + + An SCons-specific DTD module, for use with SCons DocBook + documentation, that contains names, phrases, acronyms, etc. used + throughout the SCons documentation. + +--> + + + +<!-- + + Other applications that we reference. + +--> + +<!ENTITY Aegis "<application>Aegis</application>"> +<!ENTITY Ant "<application>Ant</application>"> +<!ENTITY Autoconf "<application>Autoconf</application>"> +<!ENTITY Automake "<application>Automake</application>"> +<!ENTITY cc "<application>cc</application>"> +<!ENTITY Cons "<application>Cons</application>"> +<!ENTITY cp "<application>cp</application>"> +<!ENTITY csh "<application>csh</application>"> +<!ENTITY gcc "<application>gcc</application>"> +<!ENTITY Jam "<application>Jam</application>"> +<!ENTITY jar "<application>jar</application>"> +<!ENTITY javac "<application>javac</application>"> +<!ENTITY javah "<application>javah</application>"> +<!ENTITY Make "<application>Make</application>"> +<!ENTITY Makepp "<application>Make++</application>"> +<!ENTITY Python "<application>Python</application>"> +<!ENTITY ranlib "<application>ranlib</application>"> +<!ENTITY rmic "<application>rmic</application>"> +<!ENTITY SCons "<application>SCons</application>"> +<!ENTITY scons "<application>scons</application>"> +<!ENTITY ScCons "<application>ScCons</application>"> +<!ENTITY tar "<application>tar</application>"> +<!ENTITY touch "<application>touch</application>"> +<!ENTITY zip "<application>zip</application>"> + + +<!-- + + Classes. + +--> + +<!ENTITY Action "<classname>Action</classname>"> +<!ENTITY ActionBase "<classname>ActionBase</classname>"> +<!ENTITY CommandAction "<classname>CommandAction</classname>"> +<!ENTITY FunctionAction "<classname>FunctionAction</classname>"> +<!ENTITY ListAction "<classname>ListAction</classname>"> +<!ENTITY Builder "<classname>Builder</classname>"> +<!ENTITY BuilderBase "<classname>BuilderBase</classname>"> +<!ENTITY CompositeBuilder "<classname>CompositeBuilder</classname>"> +<!ENTITY MultiStepBuilder "<classname>MultiStepBuilder</classname>"> +<!ENTITY Job "<classname>Job</classname>"> +<!ENTITY Jobs "<classname>Jobs</classname>"> +<!ENTITY Serial "<classname>Serial</classname>"> +<!ENTITY Parallel "<classname>Parallel</classname>"> +<!ENTITY Node "<classname>Node</classname>"> +<!ENTITY Node_FS "<classname>Node.FS</classname>"> +<!ENTITY Scanner "<classname>Scanner</classname>"> +<!ENTITY Sig "<classname>Sig</classname>"> +<!ENTITY Signature "<classname>Signature</classname>"> +<!ENTITY Taskmaster "<classname>Taskmaster</classname>"> +<!ENTITY TimeStamp "<classname>TimeStamp</classname>"> +<!ENTITY Walker "<classname>Walker</classname>"> +<!ENTITY Wrapper "<classname>Wrapper</classname>"> + + + +<!-- + + Options, command-line. + +--> + +<!ENTITY debug-explain "<literal>--debug=explain</literal>"> +<!ENTITY implicit-cache "<literal>--implicit-cache</literal>"> +<!ENTITY implicit-deps-changed "<literal>--implicit-deps-changed</literal>"> +<!ENTITY implicit-deps-unchanged "<literal>--implicit-deps-unchanged</literal>"> +<!ENTITY Q "<literal>-Q</literal>"> + +<!-- + + Options, SConscript-settable. + +--> + +<!ENTITY implicit_cache "<literal>implicit_cache</literal>"> +<!ENTITY implicit_deps_changed "<literal>implicit_deps_changed</literal>"> +<!ENTITY implicit_deps_unchanged "<literal>implicit_deps_unchanged</literal>"> + + + +<!-- + + File and directory names. + +--> + +<!ENTITY build "<filename>build</filename>"> +<!ENTITY Makefile "<filename>Makefile</filename>"> +<!ENTITY Makefiles "<filename>Makefiles</filename>"> +<!ENTITY SConscript "<filename>SConscript</filename>"> +<!ENTITY SConstruct "<filename>SConstruct</filename>"> +<!ENTITY Sconstruct "<filename>Sconstruct</filename>"> +<!ENTITY sconstruct "<filename>sconstruct</filename>"> +<!ENTITY sconsign "<filename>.sconsign</filename>"> +<!ENTITY src "<filename>src</filename>"> + + + +<!-- + + Methods and functions. This includes functions from both + the Build Engine and the Native Python Interface. + +--> + +<!ENTITY Add "<function>Add</function>"> +<!ENTITY AddOptions "<function>AddOptions</function>"> +<!ENTITY Alias "<function>Alias</function>"> +<!ENTITY Aliases "<function>Aliases</function>"> +<!ENTITY Append "<function>Append</function>"> +<!ENTITY BoolOption "<function>BoolOption</function>"> +<!ENTITY Build "<function>Build</function>"> +<!ENTITY CacheDir "<function>CacheDir</function>"> +<!ENTITY Clean "<function>Clean</function>"> +<!ENTITY Clone "<function>Clone</function>"> +<!ENTITY Command "<function>Command</function>"> +<!ENTITY Configure "<function>Configure</function>"> +<!ENTITY Copy "<function>Copy</function>"> +<!ENTITY Default "<function>Default</function>"> +<!ENTITY DefaultRules "<function>DefaultRules</function>"> +<!ENTITY Depends "<function>Depends</function>"> +<!ENTITY Dir "<function>Dir</function>"> +<!ENTITY Entry "<function>Entry</function>"> +<!ENTITY EnumOption "<function>EnumOption</function>"> +<!ENTITY Environment "<function>Environment</function>"> +<!ENTITY Export "<function>Export</function>"> +<!ENTITY File "<function>File</function>"> +<!ENTITY Finish "<function>Finish</function>"> +<!ENTITY GenerateHelpText "<function>GenerateHelpText</function>"> +<!ENTITY Help "<function>Help</function>"> +<!ENTITY Ignore "<function>Ignore</function>"> +<!ENTITY Import "<function>Import</function>"> +<!ENTITY Install "<function>Install</function>"> +<!ENTITY InstallAs "<function>InstallAs</function>"> +<!ENTITY Link "<function>Link</function>"> +<!ENTITY ListOption "<function>ListOption</function>"> +<!ENTITY Local "<function>Local</function>"> +<!ENTITY Module "<function>Module</function>"> +<!ENTITY Objects "<function>Objects</function>"> +<!ENTITY Options "<function>Options</function>"> +<!ENTITY PackageOption "<function>PackageOption</function>"> +<!ENTITY PathOption "<function>PathOption</function>"> +<!ENTITY Precious "<function>Precious</function>"> +<!ENTITY Prepend "<function>Prepend</function>"> +<!ENTITY Replace "<function>Replace</function>"> +<!ENTITY Repository "<function>Repository</function>"> +<!ENTITY Return "<function>Return</function>"> +<!ENTITY RuleSet "<function>RuleSet</function>"> +<!ENTITY Salt "<function>Salt</function>"> +<!ENTITY SetBuildSignatureType "<function>SetBuildSignatureType</function>"> +<!ENTITY SetContentSignatureType "<function>SetContentSignatureType</function>"> +<!ENTITY SourceSignature "<function>SourceSignature</function>"> +<!ENTITY SourceSignatures "<function>SourceSignatures</function>"> +<!ENTITY Split "<function>Split</function>"> +<!ENTITY TargetSignatures "<function>TargetSignatures</function>"> +<!ENTITY Task "<function>Task</function>"> + +<!-- Environment methods --> +<!ENTITY subst "<function>subst</function>"> + +<!-- Configure context functions --> +<!ENTITY Message "<function>Message</function>"> +<!ENTITY Result "<function>Result</function>"> +<!ENTITY CheckCHeader "<function>CheckCHeader</function>"> +<!ENTITY CheckCXXHeader "<function>CheckCXXHeader</function>"> +<!ENTITY CheckFunc "<function>CheckFunc</function>"> +<!ENTITY CheckHeader "<function>CheckHeader</function>"> +<!ENTITY CheckLib "<function>CheckLib</function>"> +<!ENTITY CheckLibWithHeader "<function>CheckLibWithHeader</function>"> +<!ENTITY CheckType "<function>CheckType</function>"> +<!ENTITY TryAction "<function>TryAction</function>"> +<!ENTITY TryBuild "<function>TryBuild</function>"> +<!ENTITY TryCompile "<function>TryCompile</function>"> +<!ENTITY TryLink "<function>TryLink</function>"> +<!ENTITY TryRun "<function>TryRun</function>"> + +<!-- Python functions --> +<!ENTITY str "<function>str</function>"> +<!ENTITY zipfile "<function>zipfile</function>"> + +<!-- Obsolete, but referenced in old documents. --> +<!ENTITY Cache "<function>Cache</function>"> + + + +<!-- + + Global variables. + +--> + +<!ENTITY ARGUMENTS "<varname>ARGUMENTS</varname>"> +<!ENTITY BUILD_TARGETS "<varname>BUILD_TARGETS</varname>"> +<!ENTITY COMMAND_LINE_TARGETS "<varname>COMMAND_LINE_TARGETS</varname>"> +<!ENTITY DEFAULT_TARGETS "<varname>DEFAULT_TARGETS</varname>"> + + + +<!-- + + Construction variables. + +--> + +<!ENTITY BUILDERMAP "<varname>BUILDERMAP</varname>"> +<!ENTITY BUILDERS "<varname>BUILDERS</varname>"> +<!ENTITY CC "<varname>CC</varname>"> +<!ENTITY CCFLAGS "<varname>CCFLAGS</varname>"> +<!ENTITY CCCOM "<varname>CCCOM</varname>"> +<!ENTITY COLOR "<varname>COLOR</varname>"> +<!ENTITY COLORS "<varname>COLORS</varname>"> +<!ENTITY CONFIG "<varname>CONFIG</varname>"> +<!ENTITY CPPDEFINES "<varname>CPPDEFINES</varname>"> +<!ENTITY ENV "<varname>ENV</varname>"> +<!ENTITY JAVACLASSDIR "<varname>JAVACLASSDIR</varname>"> +<!ENTITY LIBDIRPREFIX "<varname>LIBDIRPREFIX</varname>"> +<!ENTITY LIBDIRSUFFIX "<varname>LIBDIRSUFFIX</varname>"> +<!ENTITY LIBLINKPREFIX "<varname>LIBLINKPREFIX</varname>"> +<!ENTITY LIBLINKSUFFIX "<varname>LIBLINKSUFFIX</varname>"> +<!ENTITY LIBPATH "<varname>LIBPATH</varname>"> +<!ENTITY LIBS "<varname>LIBS</varname>"> +<!ENTITY LINK "<varname>LINK</varname>"> +<!ENTITY LINKCOM "<varname>LINKCOM</varname>"> +<!ENTITY LINKFLAGS "<varname>LINKFLAGS</varname>"> +<!ENTITY RELEASE "<varname>RELEASE</varname>"> +<!ENTITY RELEASE_BUILD "<varname>RELEASE_BUILD</varname>"> +<!ENTITY SCANNERMAP "<varname>SCANNERMAP</varname>"> +<!ENTITY SCANNERS "<varname>SCANNERS</varname>"> +<!ENTITY TARFLAGS "<varname>TARFLAGS</varname>"> +<!ENTITY TARSUFFIX "<varname>TARSUFFIX</varname>"> + + + +<!-- + + Environment variables. + +--> + +<!ENTITY PATH "<varname>PATH</varname>"> +<!ENTITY PYTHONPATH "<varname>PYTHONPATH</varname>"> +<!ENTITY SCONSFLAGS "<varname>SCONSFLAGS</varname>"> + + + +<!-- + + Function and method arguments. + +--> + +<!ENTITY allowed_values "<varname>allowed_values</varname>"> +<!ENTITY build_dir "<varname>build_dir</varname>"> +<!ENTITY map "<varname>map</varname>"> +<!ENTITY ignorecase "<varname>ignorecase</varname>"> +<!ENTITY options "<varname>options</varname>"> +<!ENTITY exports "<varname>exports</varname>"> +<!ENTITY source "<varname>source</varname>"> +<!ENTITY target "<varname>target</varname>"> + + + +<!-- + + Values of function and method arguments. + +--> + +<!ENTITY all "<literal>all</literal>"> +<!ENTITY none "<literal>none</literal>"> + + + +<!-- + + Builder and Scanner objects. + +--> + +<!ENTITY BuildDir "<function>BuildDir</function>"> +<!ENTITY CFile "<function>CFile</function>"> +<!ENTITY CXXFile "<function>CXXFile</function>"> +<!ENTITY DVI "<function>DVI</function>"> +<!ENTITY Jar "<function>Jar</function>"> +<!ENTITY Java "<function>Java</function>"> +<!ENTITY JavaH "<function>JavaH</function>"> +<!ENTITY Library "<function>Library</function>"> +<!ENTITY Object "<function>Object</function>"> +<!ENTITY PCH "<function>PCH</function>"> +<!ENTITY PDF "<function>PDF</function>"> +<!ENTITY PostScript "<function>PostScript</function>"> +<!ENTITY Program "<function>Program</function>"> +<!ENTITY RES "<function>RES</function>"> +<!ENTITY RMIC "<function>RMIC</function>"> +<!ENTITY SharedLibrary "<function>SharedLibrary</function>"> +<!ENTITY SharedObject "<function>SharedObject</function>"> +<!ENTITY StaticLibrary "<function>StaticLibrary</function>"> +<!ENTITY StaticObject "<function>StaticObject</function>"> +<!ENTITY Tar "<function>Tar</function>"> +<!ENTITY Zip "<function>Zip</function>"> + +<!-- Obsolete, but referenced in old documents. --> +<!ENTITY MakeBuilder "<function>Make</function>"> + + + +<!-- + + Terms. Define both singular and plural forms in various + case-sensitive combinations for use in titles, in-line, etc. + +--> + +<!ENTITY buildfunc "<literal>builder function</literal>"> +<!ENTITY builder_method "<literal>builder method</literal>"> + +<!ENTITY Configure_Contexts "<literal>Configure Contexts</literal>"> +<!ENTITY configure_context "<literal>configure context</literal>"> + +<!ENTITY ConsEnv "<literal>Construction Environment</literal>"> +<!ENTITY ConsEnvs "<literal>Construction Environments</literal>"> +<!ENTITY Consenv "<literal>Construction environment</literal>"> +<!ENTITY Consenvs "<literal>Construction environments</literal>"> +<!ENTITY consenv "<literal>construction environment</literal>"> +<!ENTITY consenvs "<literal>construction environments</literal>"> + +<!ENTITY ConsVar "<literal>Construction Variable</literal>"> +<!ENTITY ConsVars "<literal>Construction Variables</literal>"> +<!ENTITY Consvar "<literal>Construction variable</literal>"> +<!ENTITY Consvars "<literal>Construction variables</literal>"> +<!ENTITY consvar "<literal>construction variable</literal>"> +<!ENTITY consvars "<literal>construction variables</literal>"> + +<!ENTITY CPPPATH "<literal>CPPPATH</literal>"> + +<!ENTITY Dictionary "<literal>Dictionary</literal>"> + +<!ENTITY Emitter "<literal>Emitter</literal>"> +<!ENTITY emitter "<literal>emitter</literal>"> +<!ENTITY Generator "<literal>Generator</literal>"> +<!ENTITY generator "<literal>generator</literal>"> + +<!ENTITY Nodes "<literal>Nodes</literal>"> + +<!ENTITY signature "<literal>signature</literal>"> +<!ENTITY buildsignature "<literal>build signature</literal>"> + +<!ENTITY true "<literal>true</literal>"> +<!ENTITY false "<literal>false</literal>"> + +<!ENTITY typedef "<literal>typedef</literal>"> + +<!-- + + File and program names used in examples. + +--> + +<!ENTITY bar "<application>bar</application>"> +<!ENTITY common1_c "<filename>common1.c</filename>"> +<!ENTITY common2_c "<filename>common2.c</filename>"> +<!ENTITY custom_py "<filename>custom.py</filename>"> +<!ENTITY goodbye "<application>goodbye</application>"> +<!ENTITY goodbye_o "<filename>goodbye.o</filename>"> +<!ENTITY goodbye_obj "<filename>goodbye.obj</filename>"> +<!ENTITY file_dll "<filename>file.dll</filename>"> +<!ENTITY file_in "<filename>file.in</filename>"> +<!ENTITY file_lib "<filename>file.lib</filename>"> +<!ENTITY file_o "<filename>file.o</filename>"> +<!ENTITY file_obj "<filename>file.obj</filename>"> +<!ENTITY file_out "<filename>file.out</filename>"> +<!ENTITY foo "<application>foo</application>"> +<!ENTITY foo_o "<filename>foo.o</filename>"> +<!ENTITY foo_obj "<filename>foo.obj</filename>"> +<!ENTITY hello "<application>hello</application>"> +<!ENTITY hello_c "<filename>hello.c</filename>"> +<!ENTITY hello_exe "<filename>hello.exe</filename>"> +<!ENTITY hello_h "<filename>hello.h</filename>"> +<!ENTITY hello_o "<filename>hello.o</filename>"> +<!ENTITY hello_obj "<filename>hello.obj</filename>"> +<!ENTITY libfile_a "<filename>libfile_a</filename>"> +<!ENTITY libfile_so "<filename>libfile_so</filename>"> +<!ENTITY new_hello "<application>new_hello</application>"> +<!ENTITY new_hello_exe "<application>new_hello.exe</application>"> +<!ENTITY prog "<filename>prog</filename>"> +<!ENTITY prog1 "<filename>prog1</filename>"> +<!ENTITY prog2 "<filename>prog2</filename>"> +<!ENTITY prog_c "<filename>prog.c</filename>"> +<!ENTITY prog_exe "<filename>prog.exe</filename>"> +<!ENTITY stdio_h "<filename>stdio.h</filename>"> + +<!-- + + Punctuation. + +--> + +<!ENTITY plus "<literal>+</literal>"> +<!ENTITY hash "<literal>#</literal>"> + +<!-- + + Mailing lists + +--> + +<!ENTITY scons-announce "<literal>announce@scons.tigris.org</literal>"> +<!ENTITY scons-devel "<literal>dev@scons.tigris.org</literal>"> +<!ENTITY scons-users "<literal>users@scons.tigris.org</literal>"> diff --git a/doc/python10/sig.eps b/doc/python10/sig.eps new file mode 100644 index 0000000..26aabaa --- /dev/null +++ b/doc/python10/sig.eps @@ -0,0 +1,147 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/sig.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 308 128 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 128 moveto 0 0 lineto 308 0 lineto 308 128 lineto closepath clip newpath +-71.3 288.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 1200 3000 m 2700 3000 l 2700 3600 l 1200 3600 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1950 3375 m +gs 1 -1 sc (Taskmaster) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 3300 4200 m 4500 4200 l 4500 4800 l 3300 4800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3900 4575 m +gs 1 -1 sc (MD5) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 5100 4200 m 6300 4200 l 6300 4800 l 5100 4800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +5700 4575 m +gs 1 -1 sc (TStamp) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 4200 3000 m 5400 3000 l 5400 3600 l 4200 3600 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4800 3375 m +gs 1 -1 sc (Sig) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 2700 3300 m 2775 3340 l 2850 3300 l 2775 3260 l + cp gs col0 s gr +% Polyline +n 4800 3600 m 4725 3750 l 4875 3750 l + cp gs col0 s gr +% Polyline +n 3900 4200 m 3900 3900 l 5700 3900 l + 5700 4200 l gs col0 s gr +% Polyline +n 4800 3750 m + 4800 3900 l gs col0 s gr +% Polyline +gs clippath +4215 3330 m 4215 3270 l 4064 3270 l 4184 3300 l 4064 3330 l cp +eoclip +n 2850 3300 m + 4200 3300 l gs col0 s gr gr + +% arrowhead +n 4064 3330 m 4184 3300 l 4064 3270 l 4064 3330 l cp gs 0.00 setgray ef gr col0 s +% Polyline + [60] 0 sd +n 1950 3000 m + 1950 2700 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 4800 3000 m + 4800 2700 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/sig.fig b/doc/python10/sig.fig new file mode 100644 index 0000000..823d59e --- /dev/null +++ b/doc/python10/sig.fig @@ -0,0 +1,44 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +6 1200 3000 2700 3600 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1200 3000 2700 3000 2700 3600 1200 3600 1200 3000 +4 1 0 50 0 0 16 0.0000 4 165 1125 1950 3375 Taskmaster\001 +-6 +6 3300 4200 4500 4800 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3300 4200 4500 4200 4500 4800 3300 4800 3300 4200 +4 1 0 50 0 0 16 0.0000 4 165 525 3900 4575 MD5\001 +-6 +6 5100 4200 6300 4800 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 5100 4200 6300 4200 6300 4800 5100 4800 5100 4200 +4 1 0 50 0 0 16 0.0000 4 225 780 5700 4575 TStamp\001 +-6 +6 4200 3000 5400 3600 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 4200 3000 5400 3000 5400 3600 4200 3600 4200 3000 +4 1 0 50 0 0 16 0.0000 4 225 330 4800 3375 Sig\001 +-6 +2 3 0 1 0 7 50 0 -1 4.000 0 0 7 0 0 5 + 2700 3300 2775 3340 2850 3300 2775 3260 2700 3300 +2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 + 4800 3600 4725 3750 4875 3750 4800 3600 +2 1 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 4 + 3900 4200 3900 3900 5700 3900 5700 4200 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 + 4800 3750 4800 3900 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 2850 3300 4200 3300 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 1950 3000 1950 2700 +2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 + 4800 3000 4800 2700 diff --git a/doc/python10/sig.jpg b/doc/python10/sig.jpg Binary files differnew file mode 100644 index 0000000..0c7e0df --- /dev/null +++ b/doc/python10/sig.jpg |
