mirror of
https://github.com/jart/cosmopolitan.git
synced 2025-07-05 02:38:31 +00:00
python-3.6.zip added from Github
README.cosmo contains the necessary links.
This commit is contained in:
parent
75fc601ff5
commit
0c4c56ff39
4219 changed files with 1968626 additions and 0 deletions
296
third_party/python/Tools/freeze/README
vendored
Normal file
296
third_party/python/Tools/freeze/README
vendored
Normal file
|
@ -0,0 +1,296 @@
|
|||
THE FREEZE SCRIPT
|
||||
=================
|
||||
|
||||
(Directions for Windows are at the end of this file.)
|
||||
|
||||
|
||||
What is Freeze?
|
||||
---------------
|
||||
|
||||
Freeze make it possible to ship arbitrary Python programs to people
|
||||
who don't have Python. The shipped file (called a "frozen" version of
|
||||
your Python program) is an executable, so this only works if your
|
||||
platform is compatible with that on the receiving end (this is usually
|
||||
a matter of having the same major operating system revision and CPU
|
||||
type).
|
||||
|
||||
The shipped file contains a Python interpreter and large portions of
|
||||
the Python run-time. Some measures have been taken to avoid linking
|
||||
unneeded modules, but the resulting binary is usually not small.
|
||||
|
||||
The Python source code of your program (and of the library modules
|
||||
written in Python that it uses) is not included in the binary --
|
||||
instead, the compiled byte-code (the instruction stream used
|
||||
internally by the interpreter) is incorporated. This gives some
|
||||
protection of your Python source code, though not much -- a
|
||||
disassembler for Python byte-code is available in the standard Python
|
||||
library. At least someone running "strings" on your binary won't see
|
||||
the source.
|
||||
|
||||
|
||||
How does Freeze know which modules to include?
|
||||
----------------------------------------------
|
||||
|
||||
Previous versions of Freeze used a pretty simple-minded algorithm to
|
||||
find the modules that your program uses, essentially searching for
|
||||
lines starting with the word "import". It was pretty easy to trick it
|
||||
into making mistakes, either missing valid import statements, or
|
||||
mistaking string literals (e.g. doc strings) for import statements.
|
||||
|
||||
This has been remedied: Freeze now uses the regular Python parser to
|
||||
parse the program (and all its modules) and scans the generated byte
|
||||
code for IMPORT instructions. It may still be confused -- it will not
|
||||
know about calls to the __import__ built-in function, or about import
|
||||
statements constructed on the fly and executed using the 'exec'
|
||||
statement, and it will consider import statements even when they are
|
||||
unreachable (e.g. "if 0: import foobar").
|
||||
|
||||
This new version of Freeze also knows about Python's new package
|
||||
import mechanism, and uses exactly the same rules to find imported
|
||||
modules and packages. One exception: if you write 'from package
|
||||
import *', Python will look into the __all__ variable of the package
|
||||
to determine which modules are to be imported, while Freeze will do a
|
||||
directory listing.
|
||||
|
||||
One tricky issue: Freeze assumes that the Python interpreter and
|
||||
environment you're using to run Freeze is the same one that would be
|
||||
used to run your program, which should also be the same whose sources
|
||||
and installed files you will learn about in the next section. In
|
||||
particular, your PYTHONPATH setting should be the same as for running
|
||||
your program locally. (Tip: if the program doesn't run when you type
|
||||
"python hello.py" there's little chance of getting the frozen version
|
||||
to run.)
|
||||
|
||||
|
||||
How do I use Freeze?
|
||||
--------------------
|
||||
|
||||
Normally, you should be able to use it as follows:
|
||||
|
||||
python freeze.py hello.py
|
||||
|
||||
where hello.py is your program and freeze.py is the main file of
|
||||
Freeze (in actuality, you'll probably specify an absolute pathname
|
||||
such as /usr/joe/python/Tools/freeze/freeze.py).
|
||||
|
||||
|
||||
What do I do next?
|
||||
------------------
|
||||
|
||||
Freeze creates a number of files: frozen.c, config.c and Makefile,
|
||||
plus one file for each Python module that gets included named
|
||||
M_<module>.c. To produce the frozen version of your program, you can
|
||||
simply type "make". This should produce a binary file. If the
|
||||
filename argument to Freeze was "hello.py", the binary will be called
|
||||
"hello".
|
||||
|
||||
Note: you can use the -o option to freeze to specify an alternative
|
||||
directory where these files are created. This makes it easier to
|
||||
clean up after you've shipped the frozen binary. You should invoke
|
||||
"make" in the given directory.
|
||||
|
||||
|
||||
Freezing Tkinter programs
|
||||
-------------------------
|
||||
|
||||
Unfortunately, it is currently not possible to freeze programs that
|
||||
use Tkinter without a Tcl/Tk installation. The best way to ship a
|
||||
frozen Tkinter program is to decide in advance where you are going
|
||||
to place the Tcl and Tk library files in the distributed setup, and
|
||||
then declare these directories in your frozen Python program using
|
||||
the TCL_LIBRARY, TK_LIBRARY and TIX_LIBRARY environment variables.
|
||||
|
||||
For example, assume you will ship your frozen program in the directory
|
||||
<root>/bin/windows-x86 and will place your Tcl library files
|
||||
in <root>/lib/tcl8.2 and your Tk library files in <root>/lib/tk8.2. Then
|
||||
placing the following lines in your frozen Python script before importing
|
||||
Tkinter or Tix would set the environment correctly for Tcl/Tk/Tix:
|
||||
|
||||
import os
|
||||
import os.path
|
||||
RootDir = os.path.dirname(os.path.dirname(os.getcwd()))
|
||||
|
||||
import sys
|
||||
if sys.platform == "win32":
|
||||
sys.path = ['', '..\\..\\lib\\python-2.0']
|
||||
os.environ['TCL_LIBRARY'] = RootDir + '\\lib\\tcl8.2'
|
||||
os.environ['TK_LIBRARY'] = RootDir + '\\lib\\tk8.2'
|
||||
os.environ['TIX_LIBRARY'] = RootDir + '\\lib\\tix8.1'
|
||||
elif sys.platform == "linux2":
|
||||
sys.path = ['', '../../lib/python-2.0']
|
||||
os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
|
||||
os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
|
||||
os.environ['TIX_LIBRARY'] = RootDir + '/lib/tix8.1'
|
||||
elif sys.platform == "solaris":
|
||||
sys.path = ['', '../../lib/python-2.0']
|
||||
os.environ['TCL_LIBRARY'] = RootDir + '/lib/tcl8.2'
|
||||
os.environ['TK_LIBRARY'] = RootDir + '/lib/tk8.2'
|
||||
os.environ['TIX_LIBRARY'] = RootDir + '/lib/tix8.1'
|
||||
|
||||
This also adds <root>/lib/python-2.0 to your Python path
|
||||
for any Python files such as _tkinter.pyd you may need.
|
||||
|
||||
Note that the dynamic libraries (such as tcl82.dll tk82.dll python20.dll
|
||||
under Windows, or libtcl8.2.so and libtcl8.2.so under Unix) are required
|
||||
at program load time, and are searched by the operating system loader
|
||||
before Python can be started. Under Windows, the environment
|
||||
variable PATH is consulted, and under Unix, it may be the
|
||||
environment variable LD_LIBRARY_PATH and/or the system
|
||||
shared library cache (ld.so). An additional preferred directory for
|
||||
finding the dynamic libraries is built into the .dll or .so files at
|
||||
compile time - see the LIB_RUNTIME_DIR variable in the Tcl makefile.
|
||||
The OS must find the dynamic libraries or your frozen program won't start.
|
||||
Usually I make sure that the .so or .dll files are in the same directory
|
||||
as the executable, but this may not be foolproof.
|
||||
|
||||
A workaround to installing your Tcl library files with your frozen
|
||||
executable would be possible, in which the Tcl/Tk library files are
|
||||
incorporated in a frozen Python module as string literals and written
|
||||
to a temporary location when the program runs; this is currently left
|
||||
as an exercise for the reader. An easier approach is to freeze the
|
||||
Tcl/Tk/Tix code into the dynamic libraries using the Tcl ET code,
|
||||
or the Tix Stand-Alone-Module code. Of course, you can also simply
|
||||
require that Tcl/Tk is required on the target installation, but be
|
||||
careful that the version corresponds.
|
||||
|
||||
There are some caveats using frozen Tkinter applications:
|
||||
Under Windows if you use the -s windows option, writing
|
||||
to stdout or stderr is an error.
|
||||
The Tcl [info nameofexecutable] will be set to where the
|
||||
program was frozen, not where it is run from.
|
||||
The global variables argc and argv do not exist.
|
||||
|
||||
|
||||
A warning about shared library modules
|
||||
--------------------------------------
|
||||
|
||||
When your Python installation uses shared library modules such as
|
||||
_tkinter.pyd, these will not be incorporated in the frozen program.
|
||||
Again, the frozen program will work when you test it, but it won't
|
||||
work when you ship it to a site without a Python installation.
|
||||
|
||||
Freeze prints a warning when this is the case at the end of the
|
||||
freezing process:
|
||||
|
||||
Warning: unknown modules remain: ...
|
||||
|
||||
When this occurs, the best thing to do is usually to rebuild Python
|
||||
using static linking only. Or use the approach described in the previous
|
||||
section to declare a library path using sys.path, and place the modules
|
||||
such as _tkinter.pyd there.
|
||||
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
If you have trouble using Freeze for a large program, it's probably
|
||||
best to start playing with a really simple program first (like the file
|
||||
hello.py). If you can't get that to work there's something
|
||||
fundamentally wrong -- perhaps you haven't installed Python. To do a
|
||||
proper install, you should do "make install" in the Python root
|
||||
directory.
|
||||
|
||||
|
||||
Usage under Windows 95 or NT
|
||||
----------------------------
|
||||
|
||||
Under Windows 95 or NT, you *must* use the -p option and point it to
|
||||
the top of the Python source tree.
|
||||
|
||||
WARNING: the resulting executable is not self-contained; it requires
|
||||
the Python DLL, currently PYTHON20.DLL (it does not require the
|
||||
standard library of .py files though). It may also require one or
|
||||
more extension modules loaded from .DLL or .PYD files; the module
|
||||
names are printed in the warning message about remaining unknown
|
||||
modules.
|
||||
|
||||
The driver script generates a Makefile that works with the Microsoft
|
||||
command line C compiler (CL). To compile, run "nmake"; this will
|
||||
build a target "hello.exe" if the source was "hello.py". Only the
|
||||
files frozenmain.c and frozen.c are used; no config.c is generated or
|
||||
used, since the standard DLL is used.
|
||||
|
||||
In order for this to work, you must have built Python using the VC++
|
||||
(Developer Studio) 5.0 compiler. The provided project builds
|
||||
python20.lib in the subdirectory pcbuild\Release of thje Python source
|
||||
tree, and this is where the generated Makefile expects it to be. If
|
||||
this is not the case, you can edit the Makefile or (probably better)
|
||||
winmakemakefile.py (e.g., if you are using the 4.2 compiler, the
|
||||
python20.lib file is generated in the subdirectory vc40 of the Python
|
||||
source tree).
|
||||
|
||||
It is possible to create frozen programs that don't have a console
|
||||
window, by specifying the option '-s windows'. See the Usage below.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Here is a list of all of the options (taken from freeze.__doc__):
|
||||
|
||||
usage: freeze [options...] script [module]...
|
||||
|
||||
Options:
|
||||
-p prefix: This is the prefix used when you ran ``make install''
|
||||
in the Python build directory.
|
||||
(If you never ran this, freeze won't work.)
|
||||
The default is whatever sys.prefix evaluates to.
|
||||
It can also be the top directory of the Python source
|
||||
tree; then -P must point to the build tree.
|
||||
|
||||
-P exec_prefix: Like -p but this is the 'exec_prefix', used to
|
||||
install objects etc. The default is whatever sys.exec_prefix
|
||||
evaluates to, or the -p argument if given.
|
||||
If -p points to the Python source tree, -P must point
|
||||
to the build tree, if different.
|
||||
|
||||
-e extension: A directory containing additional .o files that
|
||||
may be used to resolve modules. This directory
|
||||
should also have a Setup file describing the .o files.
|
||||
On Windows, the name of a .INI file describing one
|
||||
or more extensions is passed.
|
||||
More than one -e option may be given.
|
||||
|
||||
-o dir: Directory where the output files are created; default '.'.
|
||||
|
||||
-m: Additional arguments are module names instead of filenames.
|
||||
|
||||
-a package=dir: Additional directories to be added to the package's
|
||||
__path__. Used to simulate directories added by the
|
||||
package at runtime (eg, by OpenGL and win32com).
|
||||
More than one -a option may be given for each package.
|
||||
|
||||
-l file: Pass the file to the linker (windows only)
|
||||
|
||||
-d: Debugging mode for the module finder.
|
||||
|
||||
-q: Make the module finder totally quiet.
|
||||
|
||||
-h: Print this help message.
|
||||
|
||||
-x module Exclude the specified module.
|
||||
|
||||
-i filename: Include a file with additional command line options. Used
|
||||
to prevent command lines growing beyond the capabilities of
|
||||
the shell/OS. All arguments specified in filename
|
||||
are read and the -i option replaced with the parsed
|
||||
params (note - quoting args in this file is NOT supported)
|
||||
|
||||
-s subsystem: Specify the subsystem (For Windows only.);
|
||||
'console' (default), 'windows', 'service' or 'com_dll'
|
||||
|
||||
-w: Toggle Windows (NT or 95) behavior.
|
||||
(For debugging only -- on a win32 platform, win32 behavior
|
||||
is automatic.)
|
||||
|
||||
Arguments:
|
||||
|
||||
script: The Python script to be executed by the resulting binary.
|
||||
|
||||
module ...: Additional Python modules (referenced by pathname)
|
||||
that will be included in the resulting binary. These
|
||||
may be .py or .pyc files. If -m is specified, these are
|
||||
module names that are search in the path instead.
|
||||
|
||||
|
||||
|
||||
--Guido van Rossum (home page: http://www.python.org/~guido/)
|
Loading…
Add table
Add a link
Reference in a new issue