[mirror_edk2.git] / AppPkg / Applications / Python / PythonReadMe.txt

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