AppPkg/Applications/Python/PythonReadMe.txt

   1                                 EDK II Python
   2                                     ReadMe
   3                                  Beta Release
   4                                  23 Mar. 2012
   5
   6
   7 1. OVERVIEW
   8 ===========
   9 This document is devoted to general information on building and setup of the
  10 Python environment for UEFI 2.3, the invocation of the interpreter, and things
  11 that make working with Python easier.
  12
  13 It is assumed that you already have either UDK2010 or a current snapshot of
  14 the EDK II sources from www.tianocore.org, and that you can successfully build
  15 packages within that distribution.
  16
  17 2. Release Notes
  18 ================
  19   1)  There is no input line editing.  Backspace, ^C, etc. do not work.
  20   2)  All C extension modules must be statically linked (built in)
  21   3)  The site and os modules must exist as discrete files in ...\lib\python.27
  22
  23 3. Getting and Building the latest version of Python
  24 ======================================================
  25   3.1 Getting Python
  26   ==================
  27   Currently only version 2.7.2 of the CPython distribution is supported.  The
  28   source code can be downloaded from http://www.python.org/download/source/.
  29
  30   A.  Within your EDK II development tree, extract the Python distribution into
  31     AppPkg/Applications/Python.  This should create the
  32     AppPkg/Applications/Python/Python-2.7.2 directory.
  33
  34   B.  Copy the files from PyMod-2.7.2 into the corresponding directories within
  35     the Python-2.7.2 tree.  This will overwrite existing files with files
  36     modified for UEFI usage.
  37
  38   3.2 Building Python
  39   ===================
  40   A.  Edit Efi/config.c to enable the built-in modules you need.
  41         Mandatory Built-in Modules:
  42         edk2      errno       imp         marshal
  43
  44       Additional built-in modules which are required to use the help()
  45       functionality provided by PyDoc, are:
  46         _codecs     _collections    _functools    _random
  47         _sre        _struct         _weakref      binascii
  48         cStringIO   gc              itertools     math
  49         operator    time
  50
  51   B.  Edit AppPkg/AppPkg.dsc to enable (uncomment) the PythonCore.inf line
  52     within the [Components] section.
  53
  54   C.  Build AppPkg, which includes Python, using the standard "build" command:
  55     For example, to build Python for an X64 CPU architecture:
  56                     build -a X64 -p AppPkg\AppPkg.dsc
  57
  58 4. Python-related paths and files
  59 =================================
  60 Python depends upon the existence of several directories and files on the
  61 target system.
  62
  63   \EFI                              Root of the UEFI system area.
  64    |- \Tools                        Location of the Python.efi executable.
  65    |- \Boot                         UEFI specified Boot directory.
  66    |- \StdLib                       Root of the Standard Libraries sub-tree.
  67        |- \etc                      Configuration files used by libraries.
  68        |- \tmp                      Temporary files created by tmpfile(), etc.
  69        |- \lib                      Root of the libraries tree.
  70            |- \python.27            Directory containing the Python library modules.
  71                |- \lib-dynload      Dynamically loadable Python extensions.
  72                |- \site-packages    Site-specific packages and modules.
  73
  74
  75 5. Installing Python
  76 ====================
  77 These directories, on the target system, are populated from the development
  78 system as follows:
  79
  80   * \Efi\Tools receives a copy of Build/AppPkg/DEBUG_VS2005/X64/Python.efi.
  81                                                ^^^^^ ^^^^^^
  82     Modify the host path to match the your build type and compiler.
  83
  84   * The \Efi\StdLib\etc directory is populated from the StdLib/Efi/StdLib/etc
  85     source directory.
  86
  87   * Directory \Efi\StdLib\lib\python.27 is populated with packages and modules
  88     from the AppPkg/Applications/Python/Python-2.7.2/Lib directory.
  89     The recommended minimum set of modules (.py, .pyc, and/or .pyo):
  90         os      stat      ntpath      warnings      traceback
  91         site    types     copy_reg    linecache     genericpath
  92
  93   * Python C Extension Modules built as dynamically loadable extensions go into
  94     the \Efi\StdLib\lib\python.27\lib-dynload directory.
  95
  96
  97 6. Example: Enabling socket support
  98 ===================================
  99   1.  enable {"_socket", init_socket}, in Efi\config.c
 100   2.  enable Python-2.7.2/Modules/socketmodule.c in PythonCore.inf.
 101   3.  copy socket.py over to /Efi/StdLib/lib/python.27 on your target system.
 102   4.  Make sure dependent modules are present(.py) or built in(.c):
 103         functools, types, os, sys, warnings, cStringIO, StringIO, errno
 104
 105   5.  build -a X64 -p AppPkg\AppPkg.dsc
 106   6.  copy Build\AppPkg\DEBUG_VS2005\X64\Python.efi to \Efi\Tools on your target system.
 107                                 ^^^^ Modify as needed
 108
 109
 110 7. Supported C Modules
 111 ======================
 112     Module Name               C File(s)
 113   ===============       =============================================
 114   _ast                  Python/Python-ast.c
 115   _bisect               Modules/_bisectmodule.c
 116   _codecs               Modules/_codecsmodule.c
 117   _codecs_cn            Modules/cjkcodecs/_codecs_cn.c
 118   _codecs_hk            Modules/cjkcodecs/_codecs_hk.c
 119   _codecs_iso2022       Modules/cjkcodecs/_codecs_iso2022.c
 120   _codecs_jp            Modules/cjkcodecs/_codecs_jp
 121   _codecs_kr            Modules/cjkcodecs/_codecs_kr
 122   _codecs_tw            Modules/cjkcodecs/_codecs_tw
 123   _collections          Modules/_collectionsmodule.c
 124   _csv                  Modules/_csv.c
 125   _functools            Modules/_functoolsmodule.c
 126   _heapq                Modules/_heapqmodule.c
 127   _io                   Modules/_io/_iomodule.c       Modules/_io/*
 128   _json                 Modules/_json.c
 129   _md5                  Modules/md5module.c           Modules/md5.c
 130   _multibytecodec       Modules/cjkcodecs/_multibytecodec.c
 131   _random               Modules/_randommodule.c
 132   _sha                  Modules/shamodule.c
 133   _sha256               Modules/sha256module.c
 134   _sha512               Modules/sha512module.c
 135   _socket               Modules/socketmodule.c
 136   _sre                  Modules/_sre.c
 137   _struct               Modules/_struct.c
 138   _symtable             Modules/symtablemodule.c
 139   _weakref              Modules/_weakref.c
 140   array                 Modules/arraymodule.c
 141   binascii              Modules/binascii.c
 142   cmath                 Modules/cmathmodule.c
 143   cPickle               Modules/cPickle.c
 144   cStringIO             Modules/cStringIO.c
 145   datetime              Modules/datetimemodule.c
 146   edk2                  Modules/Efi/edk2module.c
 147   errno                 Modules/errnomodule.c
 148   future_builtins       Modules/future_builtins.c
 149   gc                    Modules/gcmodule.c
 150   imp                   Python/import.c
 151   itertools             Modules/itertoolsmodule.c
 152   marshal               Python/marshal.c
 153   math                  Modules/mathmodule.c          Modules/_math.c
 154   operator              Modules/operator.c
 155   parser                Modules/parsermodule.c
 156   select                Modules/selectmodule.c
 157   signal                Modules/signalmodule.c
 158   strop                 Modules/stropmodule.c
 159   time                  Modules/timemodule.c
 160   xxsubtype             Modules/xxsubtype.c
 161   zipimport             Modules/zipimport.c
 162   zlib                  Modules/zlibmodule.c          Modules/zlib/*
 163
 164
 165 8. Tested Python Library Modules
 166 ================================
 167 This is a partial list of the packages and modules of the Python Standard
 168 Library that have been tested or used in some manner.
 169
 170   encodings               genericpath.py            sha.py
 171   importlib               getopt.py                 SimpleHTTPServer.py
 172   json                    hashlib.py                site.py
 173   pydoc_data              heapq.py                  socket.py
 174   xml                     HTMLParser.py             SocketServer.py
 175   abc.py                  inspect.py                sre.py
 176   argparse.py             io.py                     sre_compile.py
 177   ast.py                  keyword.py                sre_constants.py
 178   atexit.py               linecache.py              sre_parse.py
 179   BaseHTTPServer.py       locale.py                 stat.py
 180   binhex.py               md5.py                    string.py
 181   bisect.py               modulefinder.py           StringIO.py
 182   calendar.py             ntpath.py                 struct.py
 183   cmd.py                  numbers.py                textwrap.py
 184   codecs.py               optparse.py               token.py
 185   collections.py          os.py                     tokenize.py
 186   copy.py                 platform.py               traceback.py
 187   copy_reg.py             posixpath.py              types.py
 188   csv.py                  pydoc.py                  warnings.py
 189   dummy_thread.py         random.py                 weakref.py
 190   fileinput.py            re.py                     xmllib.py
 191   formatter.py            repr.py                   zipfile.py
 192   functools.py            runpy.py
 193
 194 # # #