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   B.  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   A.  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   B.  Edit AppPkg/AppPkg.dsc to enable (uncomment) the Python2710.inf line
  72     within the [Components] section.
  73
  74   C.  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 modules.
  91                |- \lib-dynload      Dynamically loadable Python extensions.
  92                |- \site-packages    Site-specific packages and modules.
  93
  94   NOTE: The name of the directory containing the Python library modules has
  95         changed in order to distinguish it from the library modules for
  96         version 2.7.2.
  97
  98 5. Installing Python
  99 ====================
 100 These directories, on the target system, are populated from the development
 101 system as follows:
 102
 103   * \Efi\Tools receives a copy of Build/AppPkg/DEBUG_VS2015/X64/Python.efi.
 104                                                ^^^^^^^^^^^^
 105     Modify the host path to match your build type and compiler.
 106
 107   * The \Efi\StdLib\etc directory is populated from the StdLib/Efi/StdLib/etc
 108     source directory.
 109
 110   * Directory \Efi\StdLib\lib\python27.10 is populated with packages and modules
 111     from the AppPkg/Applications/Python/Python-2.7.10/Lib directory.
 112     The recommended minimum set of modules (.py, .pyc, and/or .pyo):
 113         os      stat      ntpath      warnings      traceback
 114         site    types     copy_reg    linecache     genericpath
 115
 116   * Python C Extension Modules built as dynamically loadable extensions go into
 117     the \Efi\StdLib\lib\python.27\lib-dynload directory.  This functionality is not
 118     yet implemented.
 119
 120   A script, libprep.bat (libprep.sh), is provided which facilitates the population
 121   of the target Lib directory.  Execute this script from within the
 122   AppPkg/Applications/Python/Python-2.7.10 directory, providing a single argument
 123   which is the path to the destination directory.  The appropriate contents of the
 124   AppPkg/Applications/Python/Python-2.7.10/Lib and
 125   AppPkg/Applications/Python/Python-2.7.10/PyMod-2.7.10/Lib directories will be
 126   recursively copied into the specified destination directory.
 127
 128 6. Example: Enabling socket support
 129 ===================================
 130   1.  enable {"_socket", init_socket}, in Efi\config.c
 131   2.  enable LibraryClasses BsdSocketLib and EfiSocketLib in PythonCore.inf.
 132   3.  Build Python2710
 133           build -a X64 -p AppPkg\AppPkg.dsc
 134   6.  copy Build\AppPkg\DEBUG_VS2005\X64\Python2710.efi to \Efi\Tools on your target system.
 135                         ^^^^^^^^^^^^ Modify as needed
 136
 137 7. Running Python
 138 =================
 139   Python must currently be run from an EFI FAT-32 partition, or volume, under
 140   the UEFI Shell.  At the Shell prompt enter the desired volume name, followed
 141   by a colon ':', then press Enter.  Python can then be executed by typing its
 142   name, followed by any desired options and arguments.
 143
 144   EXAMPLE:
 145       2.0 Shell> fs0:
 146       2.0 FS0:\> python2710
 147       Python 2.7.10 (default, Oct 13 2015, 16:21:53) [C] on uefi
 148       Type "help", "copyright", "credits" or "license" for more information.
 149       >>> exit()
 150       2.0 FS0:\>
 151
 152   NOTE:
 153       Python, as distributed, sends its interactive prompts to stderr.  If
 154       STDERR isn't enabled in UEFI Setup so that it's output goes to the console,
 155       it may appear that Python hangs on startup.  If this happens, one may
 156       be able to rectify the condition by typing "exit()" followed by <enter>
 157       to exit out of Python.  Then, type "exit" at the Shell prompt which should
 158       enter Setup.
 159
 160   NOTE:
 161       Some platforms don't include the Setup utility, or don't allow STDERR to
 162       be modified.  In these cases, Python may be started with the '-#' option
 163       which will cause stderr to be the same as stdout and should allow
 164       Python to be used interactively on those platforms.
 165
 166 8. Supported C Modules
 167 ======================
 168     Module Name               C File(s)
 169   ===============       =============================================
 170   _ast                  Python/Python-ast.c
 171   _bisect               Modules/_bisectmodule.c
 172   _codecs               Modules/_codecsmodule.c
 173   _codecs_cn            Modules/cjkcodecs/_codecs_cn.c
 174   _codecs_hk            Modules/cjkcodecs/_codecs_hk.c
 175   _codecs_iso2022       Modules/cjkcodecs/_codecs_iso2022.c
 176   _codecs_jp            Modules/cjkcodecs/_codecs_jp
 177   _codecs_kr            Modules/cjkcodecs/_codecs_kr
 178   _codecs_tw            Modules/cjkcodecs/_codecs_tw
 179   _collections          Modules/_collectionsmodule.c
 180   _csv                  Modules/_csv.c
 181   _functools            Modules/_functoolsmodule.c
 182   _heapq                Modules/_heapqmodule.c
 183   _io                   Modules/_io/_iomodule.c       Modules/_io/*
 184   _json                 Modules/_json.c
 185   _md5                  Modules/md5module.c           Modules/md5.c
 186   _multibytecodec       Modules/cjkcodecs/_multibytecodec.c
 187   _random               Modules/_randommodule.c
 188   _sha                  Modules/shamodule.c
 189   _sha256               Modules/sha256module.c
 190   _sha512               Modules/sha512module.c
 191   _socket               Modules/socketmodule.c
 192   _sre                  Modules/_sre.c
 193   _struct               Modules/_struct.c
 194   _symtable             Modules/symtablemodule.c
 195   _weakref              Modules/_weakref.c
 196   array                 Modules/arraymodule.c
 197   binascii              Modules/binascii.c
 198   cmath                 Modules/cmathmodule.c
 199   cPickle               Modules/cPickle.c
 200   cStringIO             Modules/cStringIO.c
 201   datetime              Modules/datetimemodule.c
 202   edk2                  Modules/Efi/edk2module.c
 203   errno                 Modules/errnomodule.c
 204   future_builtins       Modules/future_builtins.c
 205   gc                    Modules/gcmodule.c
 206   imp                   Python/import.c
 207   itertools             Modules/itertoolsmodule.c
 208   marshal               Python/marshal.c
 209   math                  Modules/mathmodule.c          Modules/_math.c
 210   operator              Modules/operator.c
 211   parser                Modules/parsermodule.c
 212   select                Modules/selectmodule.c
 213   signal                Modules/signalmodule.c
 214   strop                 Modules/stropmodule.c
 215   time                  Modules/timemodule.c
 216   xxsubtype             Modules/xxsubtype.c
 217   zipimport             Modules/zipimport.c
 218   zlib                  Modules/zlibmodule.c          Modules/zlib/*
 219
 220
 221 9. Tested Python Library Modules
 222 ================================
 223 This is a partial list of the packages and modules of the Python Standard
 224 Library that have been tested or used in some manner.
 225
 226   encodings               genericpath.py            sha.py
 227   importlib               getopt.py                 SimpleHTTPServer.py
 228   json                    hashlib.py                site.py
 229   pydoc_data              heapq.py                  socket.py
 230   xml                     HTMLParser.py             SocketServer.py
 231   abc.py                  inspect.py                sre.py
 232   argparse.py             io.py                     sre_compile.py
 233   ast.py                  keyword.py                sre_constants.py
 234   atexit.py               linecache.py              sre_parse.py
 235   BaseHTTPServer.py       locale.py                 stat.py
 236   binhex.py               md5.py                    string.py
 237   bisect.py               modulefinder.py           StringIO.py
 238   calendar.py             ntpath.py                 struct.py
 239   cmd.py                  numbers.py                textwrap.py
 240   codecs.py               optparse.py               token.py
 241   collections.py          os.py                     tokenize.py
 242   copy.py                 platform.py               traceback.py
 243   copy_reg.py             posixpath.py              types.py
 244   csv.py                  pydoc.py                  warnings.py
 245   dummy_thread.py         random.py                 weakref.py
 246   fileinput.py            re.py                     xmllib.py
 247   formatter.py            repr.py                   zipfile.py
 248   functools.py            runpy.py                  expat
 249
 250 # # #