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