doc/design/native.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE sconsdoc [
   3     <!ENTITY % scons SYSTEM "../scons.mod">
   4     %scons;
   5 ]>
   6
   7 <chapter id="chap-native"
   8          xmlns="http://www.scons.org/dbxsd/v1.0"
   9          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  10          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  11 <title>Native Python Interface</title>
  12
  13 <!--
  14
  15   __COPYRIGHT__
  16
  17   Permission is hereby granted, free of charge, to any person obtaining
  18   a copy of this software and associated documentation files (the
  19   "Software"), to deal in the Software without restriction, including
  20   without limitation the rights to use, copy, modify, merge, publish,
  21   distribute, sublicense, and/or sell copies of the Software, and to
  22   permit persons to whom the Software is furnished to do so, subject to
  23   the following conditions:
  24
  25   The above copyright notice and this permission notice shall be included
  26   in all copies or substantial portions of the Software.
  27
  28   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  29   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  30   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  31   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  32   LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  33   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  34   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  35
  36 -->
  37
  38 <para>
  39
  40  The "Native Python" interface is the interface
  41  that the actual &SCons; utility will present to users.
  42  Because it exposes the Python Build Engine API,
  43  &SCons; users will have direct access to the complete
  44  functionality of the Build Engine.
  45  In contrast, a different user interface such as a GUI
  46  may choose to only use, and present to the end-user,
  47  a subset of the Build Engine functionality.
  48
  49 </para>
  50
  51 <section id="sect-config">
  52  <title>Configuration files</title>
  53
  54  <para>
  55
  56   &SCons; configuration files are simply Python scripts that invoke
  57   methods to specify target files to be built, rules for building the
  58   target files, and dependencies.  Common build rules are available by
  59   default and need not be explicitly specified in the configuration
  60   files.
  61
  62  </para>
  63
  64  <para>
  65
  66   By default, the &SCons; utility searches for a file named
  67   &SConstruct;, &Sconstruct;, &sconstruct;, &SConstruct.py;, &Sconstruct.py;
  68   or &sconstruct.py; (in that order) in the current directory,
  69   and reads its configuration from the first file
  70   found.  A <option>-f</option> command-line option exists to read a
  71   different file name.
  72
  73  </para>
  74
  75 </section>
  76
  77
  78
  79 <section id="sect-syntax">
  80  <title>Python syntax</title>
  81
  82  <para>
  83
  84   Because &SCons; configuration files are Python scripts, normal Python
  85   syntax can be used to generate or manipulate lists of targets or
  86   dependencies:
  87
  88  </para>
  89
  90         <programlisting>
  91         sources = ['aaa.c', 'bbb.c', 'ccc.c']
  92         env.Make('bar', sources)
  93         </programlisting>
  94
  95  <para>
  96
  97   Python flow-control can be used to iterate through invocations of
  98   build rules:
  99
 100  </para>
 101
 102         <programlisting>
 103         objects = ['aaa.o', 'bbb.o', 'ccc.o']
 104         for obj in objects:
 105                 src = replace(obj, '.o', '.c')
 106                 env.Make(obj, src)
 107         </programlisting>
 108
 109  <para>
 110
 111   or to handle more complicated conditional invocations:
 112
 113  </para>
 114
 115         <programlisting>
 116         # only build 'foo' on Linux systems
 117         if sys.platform == 'linux1':
 118                 env.Make('foo', 'foo.c')
 119         </programlisting>
 120
 121  <para>
 122
 123   Because &SCons; configuration files are Python scripts, syntax errors
 124   will be caught by the Python parser.  Target-building does not begin
 125   until after all configuration files are read, so a syntax error will
 126   not cause a build to fail half-way.
 127
 128  </para>
 129
 130 </section>
 131
 132
 133
 134 <section id="sect-subsidiary">
 135  <title>Subsidiary configuration Files</title>
 136
 137  <para>
 138
 139   A configuration file can instruct &SCons; to read up subsidiary
 140   configuration files.  Subsidiary files are specified explicitly in a
 141   configuration file via the &SConscript; method.  As usual, multiple
 142   file names may be specified with white space separation, or in an
 143   array:
 144
 145  </para>
 146
 147         <programlisting>
 148         SConscript('other_file')
 149         SConscript('file1 file2')
 150         SConscript(['file3', 'file4'])
 151         SConscript(['file name with white space'])
 152         </programlisting>
 153
 154  <para>
 155
 156   An explicit <literal>sconscript</literal> keyword may be used:
 157
 158  </para>
 159
 160         <programlisting>
 161         SConscript(sconscript = 'other_file')
 162         </programlisting>
 163
 164  <para>
 165
 166   Including subsidiary configuration files is recursive: a configuration
 167   file included via &SConscript; may in turn &SConscript; other
 168   configuration files.
 169
 170  </para>
 171
 172 </section>
 173
 174
 175
 176 <section id="sect-scoping">
 177  <title>Variable scoping in subsidiary files</title>
 178
 179  <para>
 180
 181   When a subsidiary configuration file is read, it is given its own
 182   namespace; it does not have automatic access to variables from the parent
 183   configuration file.
 184
 185  </para>
 186
 187  <para>
 188
 189   Any variables (not just &SCons; objects) that are to be shared between configuration files must be
 190   explicitly passed in the &SConscript; call
 191   using the &Export; method:
 192
 193  </para>
 194
 195         <programlisting>
 196         env = Environment()
 197         debug = Environment(CCFLAGS = '-g')
 198         installdir = '/usr/bin'
 199         SConscript('src/SConscript', Export(env=env, debug=debug, installdir=installdir))
 200         </programlisting>
 201
 202 <!--
 203 The <literal>env=env</literal> stuff bugs me
 204 because it imposes extra work on the normal
 205 case where you <emphasis>don't</emphasis> rename
 206 the variables.
 207 Can we simplify the &Export; method
 208 so that a string
 209 without a keyword assignment
 210 is split into variables that are passed
 211 through transparently?
 212 Equivalent to the above example:
 213 <literal>SConscript('src/SConscript', Export('env debug installdir'))</literal>
 214 -->
 215
 216  <para>
 217
 218   Which may be specified explicitly using a keyword argument:
 219
 220  </para>
 221
 222         <programlisting>
 223         env = Environment()
 224         debug = Environment(CCFLAGS = '-g')
 225         installdir = '/usr/bin'
 226         SConscript(sconscript = 'src/SConscript',
 227                    export = Export(env=env, debug=debug, installdir=installdir))
 228         </programlisting>
 229
 230  <para>
 231
 232   Explicit variable-passing provides control over exactly what is available
 233   to a subsidiary file, and avoids unintended side effects of changes in
 234   one configuration file affecting other far-removed configuration files
 235   (a very hard-to-debug class of build problem).
 236
 237  </para>
 238
 239 </section>
 240
 241
 242
 243 <section id="sect-hierarchy">
 244  <title>Hierarchical builds</title>
 245
 246  <para>
 247
 248   The &SConscript; method is so named because, by convention, subsidiary
 249   configuration files in subdirectories are named &SConscript;:
 250
 251  </para>
 252
 253         <programlisting>
 254         SConscript('src/SConscript')
 255         SConscript('lib/build_me')
 256         </programlisting>
 257
 258  <para>
 259
 260   When a subsidiary configuration file is read from a subdirectory, all
 261   of that configuration file's targets and build rules are interpreted
 262   relative to that directory (as if &SCons; had changed its working
 263   directory to that subdirectory).  This allows for easy support of
 264   hierarchical builds of directory trees for large projects.
 265
 266  </para>
 267
 268 </section>
 269
 270
 271
 272 <section id="sect-sharing">
 273  <title>Sharing &consenvs;</title>
 274
 275  <para>
 276
 277   &SCons; will allow users to share &consenvs;, as well as other &SCons;
 278   objects and Python variables, by importing them from a central, shared
 279   repository using normal Python syntax:
 280
 281  </para>
 282
 283         <programlisting>
 284         from LocalEnvironments import optimized, debug
 285
 286         optimized.Make('foo', 'foo.c')
 287         debug.Make('foo-d', 'foo.c')
 288         </programlisting>
 289
 290  <para>
 291
 292   The expectation is that some local tool-master, integrator or
 293   administrator will be responsible for assembling environments (creating
 294   the &Builder; objects that specify the tools, options, etc.) and make
 295   these available for sharing by all users.
 296
 297  </para>
 298
 299  <para>
 300
 301   The modules containing shared &consenvs;
 302   (<literal>LocalEnvironments</literal> in the above example) can be
 303   checked in and controlled with the rest of the source files.  This
 304   allows a project to track the combinations of tools and command-line
 305   options that work on different platforms, at different times, and with
 306   different tool versions, by using already-familiar revision control
 307   tools.
 308
 309  </para>
 310
 311 </section>
 312
 313
 314
 315 <section id="sect-help">
 316  <title>Help</title>
 317
 318  <para>
 319
 320   The &SCons; utility provides a &Help; function to allow the writer
 321   of a &SConstruct; file to provide help text that is specific to
 322   the local build tree:
 323
 324  </para>
 325
 326         <programlisting>
 327         Help("""
 328         Type:
 329                 scons .         build and test everything
 330                 scons test      build the software
 331                 scons src       run the tests
 332                 scons web       build the web pages
 333         """)
 334         </programlisting>
 335
 336  <para>
 337
 338   This help text is displayed in response to the <option>-h</option>
 339   command-line option.  Calling the &Help; function more than once is an
 340   error.
 341
 342  </para>
 343
 344 </section>
 345
 346
 347
 348 <section id="sect-debug">
 349  <title>Debug</title>
 350
 351  <para>
 352
 353   &SCons; supports several command-line options for printing extra
 354   information with which to debug build problems.
 355
 356  </para>
 357
 358 <!--
 359 These need to be specified and explained
 360 beyond what the man page will have.
 361 -->
 362
 363   <!-- BEGIN HTML -->
 364
 365  <para>
 366
 367   See the -d, -p, -pa, and -pw options
 368   in the  <!--<A HREF="#sccons_Man_page">man page</A>-->, below.
 369   All of these options make use of call-back functions to
 370   <!--<A HREF="reference.html#Customizing_output">control the output</A>-->
 371   printed by the Build Engine.
 372
 373  </para>
 374
 375   <!-- END HTML -->
 376
 377 </section>
 378
 379 </chapter>