annotate site_scons/site_tools/cpython/doc/manual.xml @ 16:927f2cf75357

Changed build system from SCons to WAF. * WAF is an old fork of SCons that is now for all intents and purposes a different build system. * Unlike SCons which requires a system install of the scons library to work, the entire WAF library is self-contained in a single 'waf' Python script provided with PARPG. * Build instructions are a little different from SCons - execute the local 'waf' script with the arguments 'configure install'. * To make a local install for testing, add the '--destdir=<directory>' option to make all files install under <directory> as a fake root (e.g. '--destdir=dev_install' would make WAF install all files under the 'dev_install' directory in the PARPG source). * Added a waf_paths.py WAF tool to set GNU-compatible installation path variables (i.e. PREFIX, EXEC_PREFIX, LIBDIR, etc.). These variables should be initialized to sane defaults on Windows, where GNU standards don't usually apply.
author M. George Hansen <technopolitica@gmail.com>
date Thu, 09 Jun 2011 21:35:19 -1000
parents 4706e0194af3
children
rev   line source
11
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
1 <?xml version="1.0" encoding="UTF-8"?>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
4 <article>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
5 <title>CPython, a binary builder for Python installs</title>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
6 <articleinfo>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
7 <author>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
8 <surname>Dirk Baechle</surname>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
9 </author>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
10 </articleinfo>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
11 <para>This first version of a Python Binary Builder is based on the work of
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
12 <ulink url="http://www.scons.org/wiki/GSoC2008/MatiGruca">Mati Gruca's Google Summer of Code 2008 project</ulink>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
13 (<ulink url="http://scons.tigris.org/source/browse/scons/branches/py-builder/">last SVN branch</ulink>).
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
14 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
15 <para>The <quote><literal>InstallPython</literal></quote> method creates <literal>.pyc</literal> or <literal>.pyo</literal> files for <literal>.py</literal> source files
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
16 and adds them to the list of targets along with the source files.
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
17 They are later copied to the destination (target) directory.
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
18 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
19 <para>The <quote><literal>InstallPython</literal></quote> Builder takes a target (destination) directory as its first
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
20 argument and a list of source files/directories as a second argument.
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
21 It returns the list of target files to copy to the
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
22 target directory.
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
23 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
24 <section id="examples"><title>Examples</title>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
25 <para>A simple example of an <quote><literal>SConstruct</literal></quote> file:
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
26 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
27 <screen>env = Environment()
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
28 hello = File('hello.py')
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
29 env.InstallPython('/usr/local/bin/', hello)
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
30 env.Alias('install', '/usr/local/bin/')
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
31 </screen>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
32 <para><quote><literal>SCons</literal></quote> invoked with the <quote><literal>-Q install</literal></quote> parameter will compile the <quote><literal>hello.py</literal></quote> file into
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
33 <quote><literal>hello.pyc</literal></quote>, and copy both files into <quote><literal>/usr/local/bin/</literal></quote> directory.
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
34 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
35 <para>Sample output:
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
36 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
37 <screen>$ scons -Q install
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
38 Install file: "hello.py" as "/usr/local/bin/hello.py"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
39 Install file: "hello.pyc" as "/usr/local/bin/hello.pyc"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
40 </screen>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
41 <para><quote><literal>InstallPython</literal></quote> can also compile Python source files into optimized
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
42 binary files (<quote><literal>.pyo</literal></quote> suffix) instead of ordinary binaries (<quote><literal>.pyc</literal></quote> files). To
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
43 achieve this, change the call to <quote><literal>Environment()</literal></quote> and set the <quote><literal>CPYTHON_PYC</literal></quote>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
44 variable to '<literal>0</literal>' (zero):
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
45 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
46 <screen>env = Environment(CPYTHON_PYC=0)
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
47 hello = File('hello.py')
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
48 env.InstallPython('/usr/local/bin/', hello)
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
49 env.Alias('install', '/usr/local/bin/')
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
50 </screen>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
51 <para>Sample output:
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
52 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
53 <screen>$ scons -Q install
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
54 Install file: "hello.py" as "/usr/local/bin/hello.py"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
55 Install file: "hello.pyo" as "/usr/local/bin/hello.pyo"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
56 </screen>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
57 <para>The <quote><literal>InstallPython</literal></quote> method accepts both, files and directories, as its source arguments:
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
58 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
59 <screen>env = Environment()
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
60 pyfiles = Dir('pyfiles/')
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
61 env.InstallPython('/usr/local/bin/', pyfiles)
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
62 env.Alias('install', '/usr/local/bin')
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
63 </screen>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
64 <para>Running <quote><literal>scons -Q install</literal></quote> will copy all the <quote><literal>.py</literal></quote> files from <quote><literal>pyfiles</literal></quote> directory
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
65 into <quote><literal>/usr/local/bin/pyfiles</literal></quote> directory along with corresponding <quote><literal>.pyc</literal></quote> files.
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
66 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
67 <para>Sample output:
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
68 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
69 <screen>$ scons -Q install
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
70 Install file: "pyfiles/hello.py" as "/usr/local/bin/pyfiles/hello.py"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
71 Install file: "pyfiles/hello.pyc" as "/usr/local/bin/pyfiles/hello.pyc"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
72 Install file: "pyfiles/hello2.py" as "/usr/local/bin/pyfiles/hello2.py"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
73 Install file: "pyfiles/hello2.pyc" as "/usr/local/bin/pyfiles/hello2.pyc"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
74 </screen>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
75 <para>Mixing files and directories is also possible:
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
76 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
77 <screen>env = Environment()
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
78 hello = File('hello.py')
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
79 pyfiles = Dir('pyfiles/')
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
80 env.InstallPython('/usr/local/bin/', [hello, pyfiles])
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
81 env.Alias('install', '/usr/local/bin')
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
82 </screen>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
83 <para>Sample output:
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
84 </para>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
85 <screen>$ scons -Q install
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
86 Install file: "hello.py" as "/usr/local/bin/hello.py"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
87 Install file: "hello.pyc" as "/usr/local/bin/hello.pyc"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
88 Install file: "pyfiles/hello.py" as "/usr/local/bin/pyfiles/hello.py"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
89 Install file: "pyfiles/hello.pyc" as "/usr/local/bin/pyfiles/hello.pyc"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
90 Install file: "pyfiles/hello2.py" as "/usr/local/bin/pyfiles/hello2.py"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
91 Install file: "pyfiles/hello2.pyc" as "/usr/local/bin/pyfiles/hello2.pyc"
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
92 </screen>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
93 </section>
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
94
4706e0194af3 Various improvements to the build process including support for self-contained builds.
M. George Hansen <technopolitica@gmail.com>
parents:
diff changeset
95 </article>