Adds documentation for the new Windows embedded package.
This commit is contained in:
Steve Dower
parent
70e543b266
commit
eb3c16d38c
|
|
@ -42,9 +42,11 @@ After starting the installer, one of two options may be selected:
|
|||
If you select "Install Now":
|
||||
|
||||
* You will *not* need to be an administrator (unless a system update for the
|
||||
C Runtime Library is required)
|
||||
C Runtime Library is required or you install the :ref:`launcher` for all
|
||||
users)
|
||||
* Python will be installed into your user directory
|
||||
* The :ref:`launcher` will *also* be installed into your user directory
|
||||
* The :ref:`launcher` will be installed according to the option at the bottom
|
||||
of the first pace
|
||||
* The standard library, test suite, launcher and pip will be installed
|
||||
* If selected, the install directory will be added to your :envvar:`PATH`
|
||||
* Shortcuts will only be visible for the current user
|
||||
|
|
@ -60,7 +62,7 @@ installation". In this case:
|
|||
* Python will be installed into the Program Files directory
|
||||
* The :ref:`launcher` will be installed into the Windows directory
|
||||
* Optional features may be selected during installation
|
||||
* The standard library will be pre-compiled to bytecode
|
||||
* The standard library can be pre-compiled to bytecode
|
||||
* If selected, the install directory will be added to the system :envvar:`PATH`
|
||||
* Shortcuts are available for all users
|
||||
|
||||
|
|
@ -649,6 +651,8 @@ target Python.
|
|||
|
||||
|
||||
|
||||
.. finding_modules:
|
||||
|
||||
Finding modules
|
||||
===============
|
||||
|
||||
|
|
@ -718,6 +722,8 @@ following advice will prevent conflicts with other installations:
|
|||
* Include a ``pyvenv.cfg`` file alongside your executable containing
|
||||
``applocal = true``. This will ensure that your own directory will be used to
|
||||
resolve paths even if you have included the standard library in a ZIP file.
|
||||
It will also ignore user site-packages and other paths listed in the
|
||||
registry.
|
||||
|
||||
* If you are loading :file:`python3.dll` or :file:`python35.dll` in your own
|
||||
executable, explicitly call :c:func:`Py_SetPath` or (at least)
|
||||
|
|
@ -733,7 +739,9 @@ following advice will prevent conflicts with other installations:
|
|||
|
||||
These will ensure that the files in a system-wide installation will not take
|
||||
precedence over the copy of the standard library bundled with your application.
|
||||
Otherwise, your users may experience problems using your application.
|
||||
Otherwise, your users may experience problems using your application. Note that
|
||||
the first suggestion is the best, as the other may still be susceptible to
|
||||
non-standard paths in the registry and user site-packages.
|
||||
|
||||
Additional modules
|
||||
==================
|
||||
|
|
@ -822,6 +830,83 @@ For extension modules, consult :ref:`building-on-windows`.
|
|||
by Trent Apted et al, 2007
|
||||
|
||||
|
||||
Embedded Distribution
|
||||
=====================
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
The embedded distribution is a ZIP file containing a minimal Python environment.
|
||||
It is intended for acting as part of another application, rather than being
|
||||
directly accessed by end-users.
|
||||
|
||||
When extracted, the embedded distribution is (almost) fully isolated from the
|
||||
user's system, including environment variables, system registry settings, and
|
||||
installed packages. The standard library is included as pre-compiled and
|
||||
optimized ``.pyc`` files in a ZIP, and ``python3.dll``, ``python35.dll``,
|
||||
``python.exe`` and ``pythonw.exe`` are all provided. Tcl/tk (including all
|
||||
dependants, such as Idle), pip and the Python documentation are not included.
|
||||
|
||||
.. note::
|
||||
|
||||
The embedded distribution does not include the `Microsoft C Runtime
|
||||
<http://www.microsoft.com/en-us/download/details.aspx?id=48145>`_ and it is
|
||||
the responsibility of the application installer to provide this. The
|
||||
runtime may have already been installed on a user's system previously or
|
||||
automatically via Windows Update, and can be detected by finding
|
||||
``ucrtbase.dll`` in the system directory.
|
||||
|
||||
Third-party packages should be installed by the application installer alongside
|
||||
the embedded distribution. Using pip to manage dependencies as for a regular
|
||||
Python installation is not supported with this distribution, though with some
|
||||
care it may be possible to include and use pip for automatic updates. In
|
||||
general, third-party packages should be treated as part of the application
|
||||
("vendoring") so that the developer can ensure compatibility with newer
|
||||
versions before providing updates to users.
|
||||
|
||||
The two recommended use cases for this distribution are described below.
|
||||
|
||||
Python Application
|
||||
------------------
|
||||
|
||||
An application written in Python does not necessarily require users to be aware
|
||||
of that fact. The embedded distribution may be used in this case to include a
|
||||
private version of Python in an install package. Depending on how transparent it
|
||||
should be (or conversely, how professional it should appear), there are two
|
||||
options.
|
||||
|
||||
Using a specialized executable as a launcher requires some coding, but provides
|
||||
the most transparent experience for users. With a customized launcher, there are
|
||||
no obvious indications that the program is running on Python: icons can be
|
||||
customized, company and version information can be specified, and file
|
||||
associations behave properly. In most cases, a custom launcher should simply be
|
||||
able to call ``Py_Main`` with a hard-coded command line.
|
||||
|
||||
The simpler approach is to provide a batch file or generated shortcut that
|
||||
directly calls the ``python.exe`` or ``pythonw.exe`` with the required
|
||||
command-line arguments. In this case, the application will appear to be Python
|
||||
and not its actual name, and users may have trouble distinguishing it from other
|
||||
running Python processes or file associations.
|
||||
|
||||
With the latter approach, packages should be installed as directories alongside
|
||||
the Python executable to ensure they are available on the path. With the
|
||||
specialized launcher, packages can be located in other locations as there is an
|
||||
opportunity to specify the search path before launching the application.
|
||||
|
||||
Embedding Python
|
||||
----------------
|
||||
|
||||
Applications written in native code often require some form of scripting
|
||||
language, and the embedded Python distribution can be used for this purpose. In
|
||||
general, the majority of the application is in native code, and some part will
|
||||
either invoke ``python.exe`` or directly use ``python3.dll``. For either case,
|
||||
extracting the embedded distribution to a subdirectory of the application
|
||||
installation is sufficient to provide a loadable Python interpreter.
|
||||
|
||||
As with the application use, packages can be installed to any location as there
|
||||
is an opportunity to specify search paths before initializing the interpreter.
|
||||
Otherwise, there is no fundamental differences between using the embedded
|
||||
distribution and a regular installation.
|
||||
|
||||
Other resources
|
||||
===============
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue