AppPkg/Applications/Python/Python-2.7.10/Py2710ReadMe.txt

   1                                 EDK II Python
   2                                    ReadMe
   3                                 Version 2.7.10
   4                                  Release 1.00
   5                                   3 Nov. 2015
   6
   7
   8 1. OVERVIEW
   9 ===========
  10 This document is devoted to general information on building and setup of the
  11 Python environment for UEFI, the invocation of the interpreter, and things
  12 that make working with Python easier.
  13
  14 It is assumed that you already have UDK2010 or later, or a current snapshot of
  15 the EDK II sources from www.tianocore.org, and that you can successfully build
  16 packages within that distribution.
  17
  18 2. Release Notes
  19 ================
  20   1)  All C extension modules must be statically linked (built in)
  21   2)  The site and os modules must exist as discrete files in ...\lib\python27.10
  22   3)  User-specific configurations are not supported.
  23   4)  Environment variables are not supported.
  24
  25 3. Getting and Building Python
  26 ======================================================
  27   3.1 Getting Python
  28   ==================
  29   This file describes the UEFI port of version 2.7.10 of the CPython distribution.
  30   For development ease, a subset of the Python 2.7.10 distribution has been
  31   included as part of the AppPkg/Applications/Python/Python-2.7.10 source tree.
  32   If this is sufficient, you may skip to section 3.2, Building Python.
  33
  34   If a full distribution is desired, it can be merged into the Python-2.7.10
  35   source tree.  Directory AppPkg/Applications/Python/Python-2.7.10 corresponds
  36   to the root directory of the CPython 2.7.10 distribution.  The full
  37   CPython 2.7.10 source code may be downloaded from
  38   http://www.python.org/ftp/python/2.7.10/.
  39
  40   A.  Within your EDK II development tree, extract the Python distribution into
  41     AppPkg/Applications/Python/Python-2.7.10.  This should merge the additional
  42     files into the source tree.  It will also create the following directories:
  43         Demo      Doc         Grammar     Mac       Misc
  44         PC        PCbuild     RISCOS      Tools
  45
  46     The greatest change will be within the Python-2.7.10/Lib directory where
  47     many more packages and modules will be added.  These additional components
  48     may not have been ported to EDK II yet.
  49
  50   3.2 Building Python
  51   ===================
  52   A.  From the AppPkg/Applications/Python/Python-2.7.10 directory, execute the
  53     srcprep.bat (srcprep.sh) script to copy the header files from within the
  54     PyMod-2.7.10 sub-tree into their corresponding directories within the
  55     distribution.  This step only needs to be performed prior to the first
  56     build of Python, or if one of the header files within the PyMod tree has been
  57     modified.
  58
  59   B.  Edit PyMod-2.7.10\Modules\config.c to enable the built-in modules you need.
  60     By default, it is configured for the minimally required set of modules.
  61       Mandatory Built-in Modules:
  62         edk2      errno       imp         marshal
  63
  64       Additional built-in modules which are required to use the help()
  65       functionality provided by PyDoc, are:
  66         _codecs     _collections    _functools    _random
  67         _sre        _struct         _weakref      binascii
  68         cStringIO   gc              itertools     math
  69         operator    time
  70
  71   C.  Edit AppPkg/AppPkg.dsc to enable (uncomment) the Python2710.inf line
  72     within the [Components] section.
  73
  74   D.  Build AppPkg using the standard "build" command:
  75     For example, to build Python for an X64 CPU architecture:
  76                     build -a X64 -p AppPkg\AppPkg.dsc
  77
  78 4. Python-related paths and files
  79 =================================
  80 Python depends upon the existence of several directories and files on the
  81 target system.
  82
  83   \EFI                              Root of the UEFI system area.
  84    |- \Tools                        Location of the Python.efi executable.
  85    |- \Boot                         UEFI specified Boot directory.
  86    |- \StdLib                       Root of the Standard Libraries sub-tree.
  87        |- \etc                      Configuration files used by libraries.
  88        |- \tmp                      Temporary files created by tmpfile(), etc.
  89        |- \lib                      Root of the libraries tree.
  90            |- \python27.10          Directory containing the Python library
  91                |                    modules.
  92                |- \lib-dynload      Dynamically loadable Python extensions.
  93                |- \site-packages    Site-specific packages and modules.
  94
  95   NOTE: The name of the directory containing the Python library modules has
  96         changed in order to distinguish it from the library modules for
  97         version 2.7.2.
  98
  99 5. Installing Python
 100 ====================
 101 These directories, on the target system, are populated from the development
 102 system as follows:
 103
 104   * \Efi\Tools receives a copy of Build/AppPkg/DEBUG_VS2015/X64/Python2710.efi.
 105                                                ^^^^^^^^^^^^^^^^
 106     Modify the host path to match your build type and compiler.
 107
 108   * The \Efi\StdLib\etc directory is populated from the StdLib/Efi/StdLib/etc
 109     source directory.
 110
 111   * Directory \Efi\StdLib\lib\python27.10 is populated with packages and modules
 112     from the AppPkg/Applications/Python/Python-2.7.10/Lib directory.
 113     The recommended minimum set of modules (.py, .pyc, and/or .pyo):
 114         os      stat      ntpath      warnings      traceback
 115         site    types     copy_reg    linecache     genericpath
 116
 117   * Python C Extension Modules built as dynamically loadable extensions go into
 118     the \Efi\StdLib\lib\python.27\lib-dynload directory.  This functionality is not
 119     yet implemented.
 120
 121   A script, libprep.bat (libprep.sh), is provided which facilitates the population
 122   of the target Lib directory.  Execute this script from within the
 123   AppPkg/Applications/Python/Python-2.7.10 directory, providing a single argument
 124   which is the path to the destination directory.  The appropriate contents of the
 125   AppPkg/Applications/Python/Python-2.7.10/Lib and
 126   AppPkg/Applications/Python/Python-2.7.10/PyMod-2.7.10/Lib directories will be
 127   recursively copied into the specified destination directory.
 128
 129 6. Example: Enabling socket support
 130 ===================================
 131   1.  enable {"_socket", init_socket}, in Efi\config.c
 132   2.  enable LibraryClasses BsdSocketLib and EfiSocketLib in PythonCore.inf.
 133   3.  Build Python2710
 134           build -a X64 -p AppPkg\AppPkg.dsc
 135   6.  copy Build\AppPkg\DEBUG_VS2005\X64\Python2710.efi to \Efi\Tools on your
 136       target system. Replace "DEBUG_VS2005\X64", in the source path, with
 137       values appropriate for your tool chain and processor architecture.
 138
 139 7. Running Python
 140 =================
 141   Python must currently be run from an EFI FAT-32 partition, or volume, under
 142   the UEFI Shell.  At the Shell prompt enter the desired volume name, followed
 143   by a colon ':', then press Enter.  Python can then be executed by typing its
 144   name, followed by any desired options and arguments.
 145
 146   EXAMPLE:
 147       2.0 Shell> fs0:
 148       2.0 FS0:\> python2710
 149       Python 2.7.10 (default, Oct 13 2015, 16:21:53) [C] on uefi
 150       Type "help", "copyright", "credits" or "license" for more information.
 151       >>> exit()
 152       2.0 FS0:\>
 153
 154   NOTE:
 155       Python, as distributed, sends its interactive prompts to stderr.  If
 156       STDERR isn't enabled in UEFI Setup so that it's output goes to the
 157       console, it may appear that Python hangs on startup.  If this happens,
 158       one may be able to rectify the condition by typing "exit()" followed
 159       by <enter> to exit out of Python.  Then, type "exit" at the Shell prompt
 160       which should enter Setup where you can use the Boot Maintenance
 161       Manager to modify your Console settings.
 162
 163   NOTE:
 164       Some platforms don't include the Setup utility, or don't allow STDERR to
 165       be modified.  In these cases, Python may be started with the '-#' option
 166       which will cause stderr to be the same as stdout and should allow
 167       Python to be used interactively on those platforms.
 168
 169       Depending upon the version of Shell you are using, it may be necessary
 170       to escape the '#' character so that the Shell doesn't interpret it as
 171       the start of a comment.  The escape character is '^'.
 172       Example:
 173           python -^# -V
 174
 175 8. Supported C Modules
 176 ======================
 177     Module Name               C File(s)
 178   ===============       =============================================
 179   _ast                  Python/Python-ast.c
 180   _bisect               Modules/_bisectmodule.c
 181   _codecs               Modules/_codecsmodule.c
 182   _codecs_cn            Modules/cjkcodecs/_codecs_cn.c
 183   _codecs_hk            Modules/cjkcodecs/_codecs_hk.c
 184   _codecs_iso2022       Modules/cjkcodecs/_codecs_iso2022.c
 185   _codecs_jp            Modules/cjkcodecs/_codecs_jp
 186   _codecs_kr            Modules/cjkcodecs/_codecs_kr
 187   _codecs_tw            Modules/cjkcodecs/_codecs_tw
 188   _collections          Modules/_collectionsmodule.c
 189   _csv                  Modules/_csv.c
 190   _functools            Modules/_functoolsmodule.c
 191   _heapq                Modules/_heapqmodule.c
 192   _io                   Modules/_io/_iomodule.c       Modules/_io/*
 193   _json                 Modules/_json.c
 194   _md5                  Modules/md5module.c           Modules/md5.c
 195   _multibytecodec       Modules/cjkcodecs/_multibytecodec.c
 196   _random               Modules/_randommodule.c
 197   _sha                  Modules/shamodule.c
 198   _sha256               Modules/sha256module.c
 199   _sha512               Modules/sha512module.c
 200   _socket               Modules/socketmodule.c
 201   _sre                  Modules/_sre.c
 202   _struct               Modules/_struct.c
 203   _symtable             Modules/symtablemodule.c
 204   _weakref              Modules/_weakref.c
 205   array                 Modules/arraymodule.c
 206   binascii              Modules/binascii.c
 207   cmath                 Modules/cmathmodule.c
 208   cPickle               Modules/cPickle.c
 209   cStringIO             Modules/cStringIO.c
 210   datetime              Modules/datetimemodule.c
 211   edk2                  Modules/Efi/edk2module.c
 212   errno                 Modules/errnomodule.c
 213   future_builtins       Modules/future_builtins.c
 214   gc                    Modules/gcmodule.c
 215   imp                   Python/import.c
 216   itertools             Modules/itertoolsmodule.c
 217   marshal               Python/marshal.c
 218   math                  Modules/mathmodule.c          Modules/_math.c
 219   operator              Modules/operator.c
 220   parser                Modules/parsermodule.c
 221   select                Modules/selectmodule.c
 222   signal                Modules/signalmodule.c
 223   strop                 Modules/stropmodule.c
 224   time                  Modules/timemodule.c
 225   xxsubtype             Modules/xxsubtype.c
 226   zipimport             Modules/zipimport.c
 227   zlib                  Modules/zlibmodule.c          Modules/zlib/*
 228
 229
 230 9. Tested Python Library Modules
 231 ================================
 232 This is a partial list of the packages and modules of the Python Standard
 233 Library that have been tested or used in some manner.
 234
 235   encodings               genericpath.py            sha.py
 236   importlib               getopt.py                 SimpleHTTPServer.py
 237   json                    hashlib.py                site.py
 238   pydoc_data              heapq.py                  socket.py
 239   xml                     HTMLParser.py             SocketServer.py
 240   abc.py                  inspect.py                sre.py
 241   argparse.py             io.py                     sre_compile.py
 242   ast.py                  keyword.py                sre_constants.py
 243   atexit.py               linecache.py              sre_parse.py
 244   BaseHTTPServer.py       locale.py                 stat.py
 245   binhex.py               md5.py                    string.py
 246   bisect.py               modulefinder.py           StringIO.py
 247   calendar.py             ntpath.py                 struct.py
 248   cmd.py                  numbers.py                textwrap.py
 249   codecs.py               optparse.py               token.py
 250   collections.py          os.py                     tokenize.py
 251   copy.py                 platform.py               traceback.py
 252   copy_reg.py             posixpath.py              types.py
 253   csv.py                  pydoc.py                  warnings.py
 254   dummy_thread.py         random.py                 weakref.py
 255   fileinput.py            re.py                     xmllib.py
 256   formatter.py            repr.py                   zipfile.py
 257   functools.py            runpy.py                  expat
 258
 259 # # #