Mercurial > parpg-core

diff site_scons/site_tools/cpython/doc/manual.xml @ 11:4706e0194af3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Various improvements to the build process including support for self-contained builds. * Note that despite all of these changes PARPG still does not run because asset paths are not standardized, * Modified the SCons script so that by default running `scons` with no arguments creates a self-contained "build" under a build subdirectory to make in-source testing easier. To install PARPG, use `scons install` instead. * Got rid of the binary launcher and replaced it with a shell script for unix and a batch script for Windows (batch script is untested). The binary turned out to be too much trouble to maintain. * Modified the parpg.settings module and parpg.main entry script so that PARPG searches through several default search paths for configuration file(s). PARPG thus no longer crashes if it can't find a configuration file in any particular search path, but will crash it if can't find any configuration files. * Paths supplied to parpg.main are now appended as search paths for the configuration file(s). * Changed the default configuration file name to "parpg.cfg" to simplify searches. * Created the site_scons directory tree where SCons extensions and tools should be placed. * Created a new SCons builder, CopyRecurse, which can copy only certain files and folders from a directory tree using filters (files and folders that start with a leading dot "." e.g. ".svn" are ignored by default). * Added the CPython SCons tool (stands for Compile-Python - I didn't name it!), which provides the InstallPython builder for pre-compiling python sources before they are installed. However, it is currently broken and only installs the python sources.
author M. George Hansen <technopolitica@gmail.com>
date Tue, 31 May 2011 02:46:20 -0700
parents
children
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/site_scons/site_tools/cpython/doc/manual.xml	Tue May 31 02:46:20 2011 -0700
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<article>
+  <title>CPython, a binary builder for Python installs</title>
+  <articleinfo>
+    <author>
+      <surname>Dirk Baechle</surname>
+    </author>
+  </articleinfo>
+<para>This first version of a Python Binary Builder is based on the work of
+<ulink url="http://www.scons.org/wiki/GSoC2008/MatiGruca">Mati Gruca's Google Summer of Code 2008 project</ulink>
+(<ulink url="http://scons.tigris.org/source/browse/scons/branches/py-builder/">last SVN branch</ulink>).
+</para>
+<para>The <quote><literal>InstallPython</literal></quote> method creates <literal>.pyc</literal> or <literal>.pyo</literal> files for <literal>.py</literal> source files
+and adds them to the list of targets along with the source files.
+They are later copied to the destination (target) directory.
+</para>
+<para>The <quote><literal>InstallPython</literal></quote> Builder takes a target (destination) directory as its first
+argument and a list of source files/directories as a second argument.
+It returns the list of target files to copy to the
+target directory.
+</para>
+<section id="examples"><title>Examples</title>
+<para>A simple example of an <quote><literal>SConstruct</literal></quote> file:
+</para>
+<screen>env = Environment()
+hello = File('hello.py')
+env.InstallPython('/usr/local/bin/', hello)
+env.Alias('install', '/usr/local/bin/')
+</screen>
+<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
+<quote><literal>hello.pyc</literal></quote>, and copy both files into <quote><literal>/usr/local/bin/</literal></quote> directory.
+</para>
+<para>Sample output:
+</para>
+<screen>$ scons -Q install
+Install file: "hello.py" as "/usr/local/bin/hello.py"
+Install file: "hello.pyc" as "/usr/local/bin/hello.pyc"
+</screen>
+<para><quote><literal>InstallPython</literal></quote> can also compile Python source files into optimized
+binary files (<quote><literal>.pyo</literal></quote> suffix) instead of ordinary binaries (<quote><literal>.pyc</literal></quote> files). To
+achieve this, change the call to <quote><literal>Environment()</literal></quote> and set the <quote><literal>CPYTHON_PYC</literal></quote>
+variable to '<literal>0</literal>' (zero):
+</para>
+<screen>env = Environment(CPYTHON_PYC=0)
+hello = File('hello.py')
+env.InstallPython('/usr/local/bin/', hello)
+env.Alias('install', '/usr/local/bin/')
+</screen>
+<para>Sample output:
+</para>
+<screen>$ scons -Q install
+Install file: "hello.py" as "/usr/local/bin/hello.py"
+Install file: "hello.pyo" as "/usr/local/bin/hello.pyo"
+</screen>
+<para>The <quote><literal>InstallPython</literal></quote> method accepts both, files and directories, as its source arguments:
+</para>
+<screen>env = Environment()
+pyfiles = Dir('pyfiles/')
+env.InstallPython('/usr/local/bin/', pyfiles)
+env.Alias('install', '/usr/local/bin')
+</screen>
+<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
+into <quote><literal>/usr/local/bin/pyfiles</literal></quote> directory along with corresponding <quote><literal>.pyc</literal></quote> files.
+</para>
+<para>Sample output:
+</para>
+<screen>$ scons -Q install
+Install file: "pyfiles/hello.py" as "/usr/local/bin/pyfiles/hello.py"
+Install file: "pyfiles/hello.pyc" as "/usr/local/bin/pyfiles/hello.pyc"
+Install file: "pyfiles/hello2.py" as "/usr/local/bin/pyfiles/hello2.py"
+Install file: "pyfiles/hello2.pyc" as "/usr/local/bin/pyfiles/hello2.pyc"
+</screen>
+<para>Mixing files and directories is also possible:
+</para>
+<screen>env = Environment()
+hello = File('hello.py')
+pyfiles = Dir('pyfiles/')
+env.InstallPython('/usr/local/bin/', [hello, pyfiles])
+env.Alias('install', '/usr/local/bin')
+</screen>
+<para>Sample output:
+</para>
+<screen>$ scons -Q install
+Install file: "hello.py" as "/usr/local/bin/hello.py"
+Install file: "hello.pyc" as "/usr/local/bin/hello.pyc"
+Install file: "pyfiles/hello.py" as "/usr/local/bin/pyfiles/hello.py"
+Install file: "pyfiles/hello.pyc" as "/usr/local/bin/pyfiles/hello.pyc"
+Install file: "pyfiles/hello2.py" as "/usr/local/bin/pyfiles/hello2.py"
+Install file: "pyfiles/hello2.pyc" as "/usr/local/bin/pyfiles/hello2.pyc"
+</screen>
+</section>
+
+</article>