Commits

Anthony Tuininga committed 1a213ae Merge

Merged in takluyver/cx_freeze/docs-review (pull request #20)

Docs refresh

Comments (0)

Files changed (5)

doc/distutils.rst

 
 On Mac OS X, you can use ``bdist_dmg`` to build a Mac disk image.
 
+distutils commands
+------------------
+
 cx_Freeze creates four new commands and subclasses four others in order to
 provide the ability to both build and install executables. In typical distutils
 fashion they can be provided in the setup script, on the command line or in
 a ``setup.cfg`` configuration file. They are described in further detail below.
 
-distutils commands
-------------------
+To specify options in the script, use underscores in the name. For example::
+
+    setup(...
+          options = {'build_exe': {'init_script':'Console'}} )
+
+To specify the same options on the command line, use dashes, like this::
+
+    python setup.py build_exe --init-script Console
+
+Some options also have a short form to use on the command line. These are given in brackets below.
 
 build
 `````
 +-----------------------+-----------------------------------------------------+
 | option name           | description                                         |
 +=======================+=====================================================+
-| build-exe (-b)        | directory for built executables and dependent files |
+| build_exe (-b)        | directory for built executables and dependent files,|
+|                       | defaults to ``build/``                              |
 +-----------------------+-----------------------------------------------------+
 
+.. _distutils_build_exe:
+
 build_exe
 `````````
 
 +-----------------------+-----------------------------------------------------+
 | option name           | description                                         |
 +=======================+=====================================================+
-| build-exe (-b)        | directory for built executables and dependent files |
+| build_exe (-b)        | directory for built executables and dependent files,|
+|                       | defaults to ``build/``                              |
 +-----------------------+-----------------------------------------------------+
 | optimize (-o)         | optimization level, one of 0 (disabled), 1 or 2     |
 +-----------------------+-----------------------------------------------------+
 | packages (-p)         | comma separated list of packages to include, which  |
 |                       | includes all submodules in the package              |
 +-----------------------+-----------------------------------------------------+
-| namespace-packages    | comma separated list of packages to be treated as   |
+| namespace_packages    | comma separated list of packages to be treated as   |
 |                       | namespace packages (path is extended using pkgutil) |
 +-----------------------+-----------------------------------------------------+
-| replace-paths         | Modify filenames attached to code objects, which    |
+| replace_paths         | Modify filenames attached to code objects, which    |
 |                       | appear in tracebacks. Pass a comma separated list of|
 |                       | paths in the form <search>=<replace>. The value *   |
 |                       | in the search portion will match the directory      |
 | path                  | comma separated list of paths to search; the        |
 |                       | default value is sys.path                           |
 +-----------------------+-----------------------------------------------------+
-| init-script (-i)      | the name of the script to use during initialization |
+| init_script (-i)      | the name of the script to use during initialization |
 |                       | which, if given as a relative path, will be joined  |
 |                       | with the initscripts subdirectory of the cx_Freeze  |
 |                       | installation; the default value is "Console"        |
 +-----------------------+-----------------------------------------------------+
 | compressed (-c)       | create a compressed zip file                        |
 +-----------------------+-----------------------------------------------------+
-| copy-dependent-files  | copy all dependent files                            |
+| copy_dependent_files  | copy all dependent files                            |
 +-----------------------+-----------------------------------------------------+
-| create-shared-zip     | create a shared zip file called library.zip which   |
+| create_shared_zip     | create a shared zip file called library.zip which   |
 |                       | will contain all modules shared by all executables  |
 |                       | which are built                                     |
 +-----------------------+-----------------------------------------------------+
-| append-script-to-exe  | append the script module to the executable          |
+| append_script_to_exe  | append the script module to the executable          |
 +-----------------------+-----------------------------------------------------+
-| include-in-shared-zip | include the script module in the shared zip file    |
+| include_in_shared_zip | include the script module in the shared zip file    |
 +-----------------------+-----------------------------------------------------+
 | icon                  | include the icon in the frozen executables on the   |
 |                       | Windows platform and alongside the frozen           |
 |                       | in the constants module called BUILD_CONSTANTS in   |
 |                       | form <name>=<value>                                 |
 +-----------------------+-----------------------------------------------------+
-| include-files         | list containing files to be copied to the target    |
+| include_files         | list containing files to be copied to the target    |
 |                       | directory; it is expected that this list will       |
 |                       | contain strings or 2-tuples for the source and      |
 |                       | destination; the source can be a file or a directory|
 |                       | and CVS directories); the target must not be an     |
 |                       | absolute path                                       |
 +-----------------------+-----------------------------------------------------+
-| include-msvcr         | include the Microsoft Visual C runtime DLLs and (if |
+| include_msvcr         | include the Microsoft Visual C runtime DLLs and (if |
 |                       | necessary) the manifest file required to run the    |
 |                       | executable without needing the redistributable      |
 |                       | package installed                                   |
 +-----------------------+-----------------------------------------------------+
-| zip-includes          | list containing files to be included in the zip file|
+| zip_includes          | list containing files to be included in the zip file|
 |                       | directory; it is expected that this list will       |
 |                       | contain strings or 2-tuples for the source and      |
 |                       | destination                                         |
 +-----------------------+-----------------------------------------------------+
-| bin-includes          | list of names of files to include when determining  |
+| bin_includes          | list of names of files to include when determining  |
 |                       | dependencies of binary files that would normally be |
 |                       | excluded; note that version numbers that normally   |
 |                       | follow the shared object extension are stripped     |
 |                       | prior to performing the comparison                  |
 +-----------------------+-----------------------------------------------------+
-| bin-excludes          | list of names of files to exclude when determining  |
+| bin_excludes          | list of names of files to exclude when determining  |
 |                       | dependencies of binary files that would normally be |
 |                       | included; note that version numbers that normally   |
 |                       | follow the shared object extension are stripped     |
 |                       | prior to performing the comparison                  |
 +-----------------------+-----------------------------------------------------+
-| bin-path-includes     | list of paths from which to include files when      |
+| bin_path_includes     | list of paths from which to include files when      |
 |                       | determining dependencies of binary files            |
 +-----------------------+-----------------------------------------------------+
-| bin-path-excludes     | list of paths from which to exclude files when      |
+| bin_path_excludes     | list of paths from which to exclude files when      |
 |                       | determining dependencies of binary files            |
 +-----------------------+-----------------------------------------------------+
 | silent (-s)           | suppress all output except warnings                 |
 +-----------------------+-----------------------------------------------------+
 | option name           | description                                         |
 +=======================+=====================================================+
-| install-exe           | directory for installed executables and dependent   |
+| install_exe           | directory for installed executables and dependent   |
 |                       | files                                               |
 +-----------------------+-----------------------------------------------------+
 
 +-----------------------+-----------------------------------------------------+
 | option name           | description                                         |
 +=======================+=====================================================+
-| install-dir (-d)      | directory to install executables to; this defaults  |
+| install_dir (-d)      | directory to install executables to; this defaults  |
 |                       | to a subdirectory called <name>-<version> in the    |
 |                       | "Program Files" directory on Windows and            |
 |                       | <prefix>/lib on other platforms; on platforms other |
 |                       | than Windows symbolic links are also created in     |
 |                       | <prefix>/bin for each executable.                   |
 +-----------------------+-----------------------------------------------------+
-| build-dir (-b)        | build directory (where to install from); this       |
+| build_dir (-b)        | build directory (where to install from); this       |
 |                       | defaults to the build_dir from the build command    |
 +-----------------------+-----------------------------------------------------+
 | force (-f)            | force installation, overwriting existing files      |
 +-----------------------+-----------------------------------------------------+
-| skip-build            | skip the build steps                                |
+| skip_build            | skip the build steps                                |
 +-----------------------+-----------------------------------------------------+
 
 bdist_msi
 +-----------------------+-----------------------------------------------------+
 | option name           | description                                         |
 +=======================+=====================================================+
-| add-to-path           | add the target directory to the PATH environment    |
+| add_to_path           | add the target directory to the PATH environment    |
 |                       | variable; the default value is True if there are    |
 |                       | any console based executables and False otherwise   |
 +-----------------------+-----------------------------------------------------+
-| upgrade-code          | define the upgrade code for the package that is     |
+| upgrade_code          | define the upgrade code for the package that is     |
 |                       | created; this is used to force removal of any       |
 |                       | packages created with the same upgrade code prior   |
 |                       | to the installation of this one                     |
 | iconfile              | Path to an icns icon file for the application. This |
 |                       | will be copied into the bundle.                     |
 +-----------------------+-----------------------------------------------------+
-| qt-menu-nib           | Path to the qt-menu.nib file for Qt applications.   |
+| qt_menu_nib           | Path to the qt-menu.nib file for Qt applications.   |
 |                       | By default, it will be auto-detected.               |
 +-----------------------+-----------------------------------------------------+
 
 +-----------------------+-----------------------------------------------------+
 | option name           | description                                         |
 +=======================+=====================================================+
-| volume-label          | Volume label of the DMG disk image                  |
+| volume_label          | Volume label of the DMG disk image                  |
 +-----------------------+-----------------------------------------------------+
 
  .. versionadded:: 4.3
+Frequently Asked Questions
+==========================
+
+Problems with running frozen programs
+-------------------------------------
+
+A common problem is that cx_Freeze hasn't automatically detected that a file
+needs to be copied. Modules that your code imports are detected, but if they're
+dynamically loaded - e.g. by a plugin system - you have to tell cx_Freeze about
+them. This is easy using a :doc:`setup script <distutils>`:
+
+* For Python code, specify the module names in the ``packages`` option.
+* List compiled libraries (.dll or .so files) in the ``include-files`` option.
+* Data files are a bit more complex - see :ref:`data_files`.
+
+Freezing for other platforms
+----------------------------
+
+cx_Freeze works on Windows, Mac and Linux, but on each platform it only makes an
+executable that runs on that platform. So if you want to freeze your program for
+Windows, freeze it on Windows; if you want to run it on Macs, freeze it on a Mac.
+
+At a pinch, you can try to make a Windows executable using
+`Wine <http://www.winehq.org/>`_. Our experience is that you need to copy some
+files in manually after cx_Freeze has run to make the executable work. We don't
+recommend this option.
+
+.. _data_files:
+
+Using data files
+----------------
+
+Applications often need data files besides the code, such as icons. Using a
+:ref:`setup script <distutils>`, you can list data files or directories in the
+``include_files`` option to ``build_exe``. They'll be copied to the build
+directory alongside the executable. Then to find them, use code like this::
+
+    def find_data_file(filename):
+        if getattr(sys, 'frozen', False):
+            # The application is frozen
+            datadir = os.path.dirname(sys.executable)
+        else:
+            # The application is not frozen
+            # Change this bit to match where you store your data files:
+            datadir = os.path.dirname(__file__)
+            
+        return os.path.join(datadir, filename)
+
+An alternative is to embed data in code, for example by using `Qt's resource
+system <http://developer.qt.nokia.com/doc/qt-4.8/resources.html>`_.
+
+.. seealso:: `A tutorial covering resources in PyQt <http://lateral.netmanagers.com.ar/stories/BBS49.html>`_
+
+Microsoft Visual C++ Redistributable Package
+--------------------------------------------
+
+Python on Windows requires the Microsoft Visual C++ Redistributable Package.
+Python 2.6-3.2 uses the 2008 version, and because of how this is installed,
+cx_Freeze doesn't automatically copy it for your application. It's also not
+clear whether everyone has the right to redistribute the DLLs. You're
+responsible for checking the license conditions associated with the DLLs you
+have installed.
+
+* If your license allows you to distribute these files, specify the
+  ``include_msvcr`` option to :ref:`distutils_build_exe` to have them
+  distributed automatically.
+
+* If not, your users or your installer will need to install the Microsoft Visual
+  C++ Redistributable Package (a free download from Microsoft).
+  It's not uncommon for this to already be present on modern computers, but
+  it's not, as far as we know, part of a standard Windows installation. Note
+  that the "SP1" version of this *does not* work -- it has to exactly match
+  the version which Python itself is compiled with.
+
+     * 2008 (Python 2.6-3.2) `for x86 (32 bit) Windows <http://www.microsoft.com/download/en/details.aspx?id=29>`_
+       or `for x64 (64 bit) Windows <http://www.microsoft.com/download/en/details.aspx?id=15336>`_
+     * 2010 (Python 3.3) `for x86 (32 bit) Windows <http://www.microsoft.com/en-gb/download/details.aspx?id=5555>`_
+       or `for x64 (64 bit) Windows <http://www.microsoft.com/en-us/download/details.aspx?id=14632>`_
+
+Up to Python 2.5, and again from Python 3.3, the MSVCR DLLs are installed in a
+normal location, and cx_Freeze will copy them automatically. It's still up to
+you to ensure that the licenses of all the files you use allow you to distribute
+them as part of your application.
    :maxdepth: 2
    
    overview.rst
+   distutils.rst
    script.rst
-   distutils.rst
+   faq.rst
    releasenotes.rst
    development/index.rst
    license.rst
 Using cx_Freeze
 ===============
 
-There are three different ways to use cx_Freeze. The first is to use the
-included :ref:`cxfreeze script <script>`, which works well for simple scripts.
-The second is to create a :ref:`distutils setup script <distutils>`, which can
-be used for more complicated configuration or to retain the configuration for
-future use. The third method involves working directly with the classes and
-modules used internally by cx_Freeze, and should be reserved for complicated
-scripts or extending or embedding.
+There are three different ways to use cx_Freeze:
 
-There are three different options for producing executables as well. The first,
-and the only option in earlier versions of cx_Freeze, is to append the zip file
-of modules to the executable itself. The second option is creating a private
-zip file with the same name as the executable but with the extension .zip. The
-final, default option is to create a zip file called ``library.zip`` and place
-all modules in this zip file. The final two options are necessary when creating
-an RPM since the RPM builder automatically strips executables.
+1. Use the included :ref:`cxfreeze script <script>`.
+2. Create a :ref:`distutils setup script <distutils>`. This is useful if you
+   need extra options when freezing your program, because you can save them in
+   the script. Run ``cxfreeze-quickstart`` to generate a simple setup script.
+3. Work directly with the classes and modules used internally by cx_Freeze. This
+   should be reserved for complicated scripts or extending or embedding.
 
 cx_Freeze normally produces a folder containing an executable file for your
 program, along with the shared libraries (DLLs or .so files) needed to run it.
 more advanced Windows installer, use a separate tool like `Inno Setup
 <http://www.jrsoftware.org/isinfo.php>`_ to package the files cx_Freeze collects.
 
-Using data files
-----------------
+Python modules for your executables are stored in zip files. These can go in
+three different places:
 
-Applications often need data files besides the code, such as icons. Using a
-:ref:`setup script <distutils>`, you can list data files or directories in the
-``include_files`` option to ``build_exe``. They'll be copied to the build
-directory alongside the executable. Then to find them, your code can do::
-
-    appdir = os.path.dirname(sys.argv[0])
-    data_file_name = os.path.join(appdir, "some_data_directory",
-            "some_file.dat")
-
-An alternative is to embed data in code, for example by using `Qt's resource
-system <http://developer.qt.nokia.com/doc/qt-4.8/resources.html>`_.
-
-.. seealso:: `A tutorial covering resources in PyQt <http://lateral.netmanagers.com.ar/stories/BBS49.html>`_
-
-Microsoft Visual C++ 2008 Redistributable Package
--------------------------------------------------
-
-Since Python 2.6, Python on Windows requires the Microsoft Visual C++ 2008
-Redistributable Package. Its DLLs are stored in a different way from most DLLs,
-and cx_Freeze doesn't currently automatically copy them, (for technical
-details, see `this mailing list thread
-<http://www.mail-archive.com/cx-freeze-users@lists.sourceforge.net/msg00087.html>`_).
-You have two options to deal with this:
-
-1. Get your users to install the Microsoft Visual C++ 2008 Redistributable
-   Package (free download, `for x86 (32 bit) Windows 
-   <http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=29>`_
-   or `for x64 (64 bit) Windows
-   <http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=15336>`_).
-   It's not uncommon for this to already be present on modern computers, but
-   it's not (as far as we know) part of a standard Windows installation. Note
-   that the "SP1" version of this *does not* work -- it has to exactly match
-   the version which Python itself is compiled with.
-
-2. Copy the following files from your system to the directory where cx_Freeze
-   has assembled your files. You are responsible for making sure that you have
-   the right to redistribute them::
-
-    C:\WINDOWS\WinSxS\Manifests\x86_Microsoft.VC90.CRT_1fc8b3b9a1e18e3b_9.0.21022.8_x-ww_d08d0375.manifest
-    C:\WINDOWS\WinSxS\x86_Microsoft.VC90.CRT_1fc8b3b9a1e18e3b_9.0.21022.8_x-ww_d08d0375\msvcm90.dll
-    C:\WINDOWS\WinSxS\x86_Microsoft.VC90.CRT_1fc8b3b9a1e18e3b_9.0.21022.8_x-ww_d08d0375\msvcp90.dll
-    C:\WINDOWS\WinSxS\x86_Microsoft.VC90.CRT_1fc8b3b9a1e18e3b_9.0.21022.8_x-ww_d08d0375\msvcr90.dll
+* The default is to create a zip file called ``library.zip`` and place
+  all modules in this zip file.
+* Each executable can have a private zip file with the same name as the
+  executable (except for the .zip extension).
+* Each executable can have a zip file of modules appended to it. This was the
+  default in earlier versions of cx_Freeze, but it doesn't work with for
+  creating an RPM, since the RPM builder strips executables.
 
 Further customization can be done using the following options:
 
-+-----------------------+-----------------------------------------------------+
-| option name           | description                                         |
-+=======================+=====================================================+
-| --version             | show version number and exit                        |
-+-----------------------+-----------------------------------------------------+
-| -h, --help            | show this help message and exit                     |
-+-----------------------+-----------------------------------------------------+
-| -O                    | optimize generated bytecode as per PYTHONOPTIMIZE;  |
-|                       | use -OO in order to remove doc strings              |
-+-----------------------+-----------------------------------------------------+
-| -c, --compress        | compress byte code in zip files                     |
-+-----------------------+-----------------------------------------------------+
-| -s, --silent          | suppress all output except warnings                 |
-+-----------------------+-----------------------------------------------------+
-| --base-name           | file on which to base the executable; if the name   |
-|                       | of the file is not an absolute file name, the       |
-|                       | subdirectory bases inside the cx_Freeze package     |
-|                       | will be searched for a file matching the name,      |
-|                       | without regard to the extension                     |
-+-----------------------+-----------------------------------------------------+
-| --init-script         | script which will be executed upon startup; if the  |
-|                       | name of the file is not an absolute file name, the  |
-|                       | subdirectory initscripts inside the cx_Freeze       |
-|                       | package will be searched for a file matching the    |
-|                       | name, without regard to the extension               |
-+-----------------------+-----------------------------------------------------+
-| --target-dir          | directory in which to place the executable and any  |
-|                       | dependent files                                     |
-+-----------------------+-----------------------------------------------------+
-| --target-name         | the name of the file to create; the default is the  |
-|                       | base name of the script and the extension of the    |
-|                       | base executable name                                |
-+-----------------------+-----------------------------------------------------+
-| --shared-name         | the name of the file to create; the default is the  |
-|                       | base name of the script and the extension of the    |
-|                       | base executable name                                |
-+-----------------------+-----------------------------------------------------+
-| --no-copy-deps        | do not copy any dependent files (extensions, shared |
-|                       | libraries, etc.) to the target directory; this also |
-|                       | modifies the default init script to ConsoleKeepPath |
-|                       | and means that the target executable requires a     |
-|                       | Python installation to execute properly             |
-+-----------------------+-----------------------------------------------------+
-| --default-path        | list of paths separated by the standard path        |
-|                       | separator for the platform which will be used to    |
-|                       | initialize the search path instead of sys.path      |
-+-----------------------+-----------------------------------------------------+
-| --include-path        | list of paths separated by the standard path        |
-|                       | separator for the platform which will be used to    |
-|                       | add to the search path                              |
-+-----------------------+-----------------------------------------------------+
-| --replace-paths       | replace all the paths in modules found in the given |
-|                       | paths with the given replacement string; multiple   |
-|                       | values are separated by the standard path separator |
-|                       | for the platform and each value is of the form      |
-|                       | <search>=<replace>; <search> can be * which means   |
-|                       | all paths not already specified                     |
-+-----------------------+-----------------------------------------------------+
-| --include-modules     | comma separated list of names of modules to include |
-+-----------------------+-----------------------------------------------------+
-| --exclude-modules     | comma separated list of names of modules to exclude |
-+-----------------------+-----------------------------------------------------+
-| --ext-list-file       | name of file in which to place the list of          |
-|                       | dependent files which were copied to the target     |
-|                       | directory                                           |
-+-----------------------+-----------------------------------------------------+
-| -z, --zip-include     | name of file to add to the zip file or a            |
-|                       | specification of the form <name>=<arcname> which    |
-|                       | will specify the archive name to use; multiple      |
-|                       | --zip-include arguments can be used                 |
-+-----------------------+-----------------------------------------------------+
+.. option:: --version
+
+   show version number and exit
+
+.. option:: -h, --help
+
+   show this help message and exit
+
+
+.. option:: -O
+
+    optimize generated bytecode as per PYTHONOPTIMIZE; use -OO in order to
+    remove doc strings
+
+.. option:: -c, --compress
+
+    compress byte code in zip files
+
+.. option:: -s, --silent
+
+    suppress all output except warnings and errors
+
+.. option:: --base-name=NAME
+
+    file on which to base the target file; if the name of
+    the file is not an absolute file name, the
+    subdirectory bases (rooted in the directory in which
+    the freezer is found) will be searched for a file
+    matching the name
+
+.. option:: --init-script=NAME
+
+    script which will be executed upon startup; if the
+    name of the file is not an absolute file name, the
+    subdirectory initscripts (rooted in the directory in
+    which the cx_Freeze package is found) will be searched
+    for a file matching the name
+
+.. option:: --target-dir=DIR, --install-dir=DIR
+
+    The directory in which to place the target file and any dependent files
+
+.. option:: --target-name=NAME
+
+    the name of the file to create instead of the base
+    name of the script and the extension of the base binary
+
+.. option:: --no-copy-deps
+
+    do not copy the dependent files (extensions, shared
+    libraries, etc.) to the target directory; this also
+    modifies the default init script to ConsoleKeepPath.py
+    and means that the target executable requires a Python
+    installation to execute properly
+
+.. option:: --default-path=DIRS
+
+   list of paths separated by the standard path separator
+   for the platform which will be used to initialize
+   sys.path prior to running the module finder
+
+.. option:: --include-path=DIRS
+
+    list of paths separated by the standard path separator
+    for the platform which will be used to modify sys.path
+    prior to running the module finder
+
+.. option:: --replace-paths=DIRECTIVES
+
+    replace all the paths in modules found in the given
+    paths with the given replacement string; multiple
+    values are separated by the standard path separator
+    and each value is of the form path=replacement_string;
+    path can be * which means all paths not already
+    specified
+
+.. option:: --include-modules=NAMES
+
+    comma separated list of modules to include
+
+.. option:: --exclude-modules=NAMES
+
+    comma separated list of modules to exclude
+
+.. option:: --ext-list-file=NAME
+
+    name of file in which to place the list of dependent
+    files which were copied into the target directory
+
+.. option:: -z SPEC, --zip-include=SPEC
+
+    name of file to add to the zip file or a specification
+    of the form name=arcname which will specify the
+    archive name to use; multiple --zip-include arguments
+    can be used
+
+.. option:: --icon=ICON
+
+   name of the icon file for the application