AppPkg/Applications/Python/PythonReadMe.txt

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