Home | History | Annotate | only in /external/python/cpython3/Misc
Up to higher level directory
NameDateSize
ACKS22-Oct-202026.2K
coverity_model.c22-Oct-20204.1K
gdbinit22-Oct-20204.7K
HISTORY22-Oct-20201.3M
indent.pro22-Oct-2020557
NEWS.d/22-Oct-2020
Porting22-Oct-202063
python-config.in22-Oct-20202K
python-config.sh.in22-Oct-20202.9K
python-wing3.wpr22-Oct-2020555
python-wing4.wpr22-Oct-2020835
python-wing5.wpr22-Oct-2020835
python.man22-Oct-202015.8K
python.pc.in22-Oct-2020293
README22-Oct-20201.4K
README.AIX22-Oct-20204.7K
README.coverity22-Oct-2020845
README.valgrind22-Oct-20204.5K
SpecialBuilds.txt22-Oct-20209.7K
svnmap.txt22-Oct-20204.1M
valgrind-python.supp22-Oct-20208.2K
vgrindefs22-Oct-2020500

README

      1 Python Misc subdirectory
      2 ========================
      3 
      4 This directory contains files that wouldn't fit in elsewhere.  Some
      5 documents are only of historic importance.
      6 
      7 Files found here
      8 ----------------
      9 
     10 ACKS                    Acknowledgements
     11 gdbinit                 Handy stuff to put in your .gdbinit file, if you use gdb
     12 HISTORY                 News from previous releases -- oldest last
     13 indent.pro              GNU indent profile approximating my C style
     14 NEWS                    News for this release (for some meaning of "this")
     15 Porting                 Mini-FAQ on porting to new platforms
     16 python-config.in        Python script template for python-config
     17 python.man              UNIX man page for the python interpreter
     18 python.pc.in            Package configuration info template for pkg-config
     19 python-wing*.wpr        Wing IDE project file
     20 README                  The file you're reading now
     21 README.AIX              Information about using Python on AIX
     22 README.coverity         Information about running Coverity's Prevent on Python
     23 README.valgrind         Information for Valgrind users, see valgrind-python.supp
     24 SpecialBuilds.txt       Describes extra symbols you can set for debug builds
     25 svnmap.txt              Map of old SVN revs and branches to hg changeset ids,
     26                         help history-digging
     27 valgrind-python.supp    Valgrind suppression file, see README.valgrind
     28 vgrindefs               Python configuration for vgrind (a generic pretty printer)
     29

README.AIX

      1 
      2 This documentation tries to help people who intend to use Python on
      3 AIX.
      4 
      5 There used to be many issues with Python on AIX, but the major ones
      6 have been corrected for version 3.2, so that Python should now work
      7 rather well on this platform. The remaining known issues are listed in
      8 this document.
      9 
     10 
     11 ======================================================================
     12 			   Compiling Python
     13 ----------------------------------------------------------------------
     14 
     15 You can compile Python with gcc or the native AIX compiler. The native
     16 compiler used to give better performances on this system with older
     17 versions of Python.  With Python 3.2 it may not be the case anymore,
     18 as this compiler does not allow compiling Python with computed gotos.
     19 Some benchmarks need to be done.
     20 
     21 Compiling with gcc:
     22 
     23 cd Python-3.2
     24 CC=gcc OPT="-O2" ./configure --enable-shared
     25 make
     26 
     27 There are various aliases for the native compiler.  The recommended
     28 alias for compiling Python is 'xlc_r', which provides a better level of
     29 compatibility and handles thread initialization properly.
     30 
     31 It is a good idea to add the '-qmaxmem=70000' option, otherwise the
     32 compiler considers various files too complex to optimize.
     33 
     34 Compiling with xlc:
     35 
     36 cd Python-3.2
     37 CC=xlc_r OPT="-O2 -qmaxmem=70000" ./configure --without-computed-gotos --enable-shared
     38 make
     39 
     40 Note:
     41 On AIX 5.3 and earlier, you will also need to specify the
     42 "--disable-ipv6" flag to configure. This has been corrected in AIX
     43 6.1.
     44 
     45 
     46 ======================================================================
     47 			  Memory Limitations
     48 ----------------------------------------------------------------------
     49 
     50 Note: this section may not apply when compiling Python as a 64 bit
     51 application.
     52 
     53 By default on AIX each program gets one segment register for its data
     54 segment. As each segment register covers 256 MiB, a Python program that
     55 would use more than 256 MiB will raise a MemoryError.  The standard
     56 Python test suite is one such application.
     57 
     58 To allocate more segment registers to Python, you must use the linker
     59 option -bmaxdata or the ldedit tool to specify the number of bytes you
     60 need in the data segment.
     61 
     62 For example, if you want to allow 512 MiB of memory for Python (this is
     63 enough for the test suite to run without MemoryErrors), you should run
     64 the following command at the end of compilation:
     65 
     66 ldedit -b maxdata:0x20000000 ./python
     67 
     68 You can allow up to 2 GiB of memory for Python by using the value
     69 0x80000000 for maxdata.
     70 
     71 It is also possible to go beyond 2 GiB of memory by activating Large
     72 Page Use. You should consult the IBM documentation if you need to use
     73 this option. You can also follow the discussion of this problem
     74 in issue 11212 at bugs.python.org.
     75 
     76 http://publib.boulder.ibm.com/infocenter/aix/v6r1/index.jsp?topic=/com.ibm.aix.cmds/doc/aixcmds3/ldedit.htm
     77 
     78 
     79 ======================================================================
     80 			     Known issues
     81 ----------------------------------------------------------------------
     82 
     83 Those issues are currently affecting Python on AIX:
     84 
     85 * Python has not been fully tested on AIX when compiled as a 64 bit
     86   application.
     87 
     88 * issue 3526: the memory used by a Python process will never be
     89   released to the system. If you have a Python application on AIX that
     90   uses a lot of memory, you should read this issue and you may
     91   consider using the provided patch that implements a custom malloc
     92   implementation
     93 
     94 * issue 11192: test_socket fails
     95 
     96 * issue 11190: test_locale fails
     97 
     98 * issue 11193: test_subprocess fails
     99 
    100 * issue 9920: minor arithmetic issues in cmath
    101 
    102 * issue 11215: test_fileio fails
    103 
    104 
    105 
    106 ======================================================================
    107 		Implementation details for developers
    108 ----------------------------------------------------------------------
    109 
    110 Python and python modules can now be built as shared libraries on AIX
    111 as usual.
    112 
    113 AIX shared libraries require that an "export" and "import" file be
    114 provided at compile time to list all extern symbols which may be
    115 shared between modules.  The "export" file (named python.exp) for the
    116 modules and the libraries that belong to the Python core is created by
    117 the "makexp_aix" script before performing the link of the python
    118 binary. It lists all global symbols (exported during the link) of the
    119 modules and the libraries that make up the python executable.
    120 
    121 When shared library modules (.so files) are made, a second shell
    122 script is invoked.  This script is named "ld_so_aix" and is also
    123 provided with the distribution in the Modules subdirectory.  This
    124 script acts as an "ld" wrapper which hides the explicit management of
    125 "export" and "import" files; it adds the appropriate arguments (in the
    126 appropriate order) to the link command that creates the shared module.
    127 Among other things, it specifies that the "python.exp" file is an
    128 "import" file for the shared module.
    129 
    130 This mechanism should be transparent.
    131

README.coverity

      1 
      2 Coverity has a static analysis tool (Prevent) which is similar to Klocwork.
      3 They run their tool on the Python source code (SVN head) on a daily basis.
      4 The results are available at:
      5 
      6      http://scan.coverity.com/
      7 
      8 About 20 people have access to the analysis reports.  Other
      9 people can be added by request.
     10 
     11 Prevent was first run on the Python 2.5 source code in March 2006.
     12 There were originally about 100 defects reported.  Some of these
     13 were false positives.  Over 70 issues were uncovered.
     14 
     15 Each warning has a unique id and comments that can be made on it.
     16 When checking in changes due to a warning, the unique id
     17 as reported by the tool was added to the SVN commit message.
     18 
     19 False positives were annotated so that the comments can
     20 be reviewed and reversed if the analysis was incorrect.
     21 
     22 Contact python-dev (a] python.org for more information.
     23

README.valgrind

      1 This document describes some caveats about the use of Valgrind with
      2 Python.  Valgrind is used periodically by Python developers to try
      3 to ensure there are no memory leaks or invalid memory reads/writes.
      4 
      5 UPDATE: Python 3.6 now supports PYTHONMALLOC=malloc environment variable which
      6 can be used to force the usage of the malloc() allocator of the C library.
      7 
      8 If you don't want to read about the details of using Valgrind, there
      9 are still two things you must do to suppress the warnings.  First,
     10 you must use a suppressions file.  One is supplied in
     11 Misc/valgrind-python.supp.  Second, you must do one of the following:
     12 
     13   * Uncomment Py_USING_MEMORY_DEBUGGER in Objects/obmalloc.c,
     14     then rebuild Python
     15   * Uncomment the lines in Misc/valgrind-python.supp that
     16     suppress the warnings for PyObject_Free and PyObject_Realloc
     17 
     18 If you want to use Valgrind more effectively and catch even more
     19 memory leaks, you will need to configure python --without-pymalloc.
     20 PyMalloc allocates a few blocks in big chunks and most object
     21 allocations don't call malloc, they use chunks doled about by PyMalloc
     22 from the big blocks.  This means Valgrind can't detect
     23 many allocations (and frees), except for those that are forwarded
     24 to the system malloc.  Note: configuring python --without-pymalloc
     25 makes Python run much slower, especially when running under Valgrind.
     26 You may need to run the tests in batches under Valgrind to keep
     27 the memory usage down to allow the tests to complete.  It seems to take
     28 about 5 times longer to run --without-pymalloc.
     29 
     30 Apr 15, 2006:
     31   test_ctypes causes Valgrind 3.1.1 to fail (crash).
     32   test_socket_ssl should be skipped when running valgrind.
     33 	The reason is that it purposely uses uninitialized memory.
     34 	This causes many spurious warnings, so it's easier to just skip it.
     35 
     36 
     37 Details:
     38 --------
     39 Python uses its own small-object allocation scheme on top of malloc,
     40 called PyMalloc.
     41 
     42 Valgrind may show some unexpected results when PyMalloc is used.
     43 Starting with Python 2.3, PyMalloc is used by default.  You can disable
     44 PyMalloc when configuring python by adding the --without-pymalloc option.
     45 If you disable PyMalloc, most of the information in this document and
     46 the supplied suppressions file will not be useful.  As discussed above,
     47 disabling PyMalloc can catch more problems.
     48 
     49 If you use valgrind on a default build of Python,  you will see
     50 many errors like:
     51 
     52         ==6399== Use of uninitialised value of size 4
     53         ==6399== at 0x4A9BDE7E: PyObject_Free (obmalloc.c:711)
     54         ==6399== by 0x4A9B8198: dictresize (dictobject.c:477)
     55 
     56 These are expected and not a problem.  Tim Peters explains
     57 the situation:
     58 
     59         PyMalloc needs to know whether an arbitrary address is one
     60 	that's managed by it, or is managed by the system malloc.
     61 	The current scheme allows this to be determined in constant
     62 	time, regardless of how many memory areas are under pymalloc's
     63 	control.
     64 
     65         The memory pymalloc manages itself is in one or more "arenas",
     66 	each a large contiguous memory area obtained from malloc.
     67 	The base address of each arena is saved by pymalloc
     68 	in a vector.  Each arena is carved into "pools", and a field at
     69 	the start of each pool contains the index of that pool's arena's
     70 	base address in that vector.
     71 
     72         Given an arbitrary address, pymalloc computes the pool base
     73 	address corresponding to it, then looks at "the index" stored
     74 	near there.  If the index read up is out of bounds for the
     75 	vector of arena base addresses pymalloc maintains, then
     76 	pymalloc knows for certain that this address is not under
     77 	pymalloc's control.  Otherwise the index is in bounds, and
     78 	pymalloc compares
     79 
     80             the arena base address stored at that index in the vector
     81 
     82         to
     83 
     84             the arbitrary address pymalloc is investigating
     85 
     86         pymalloc controls this arbitrary address if and only if it lies
     87         in the arena the address's pool's index claims it lies in.
     88 
     89         It doesn't matter whether the memory pymalloc reads up ("the
     90 	index") is initialized.  If it's not initialized, then
     91 	whatever trash gets read up will lead pymalloc to conclude
     92 	(correctly) that the address isn't controlled by it, either
     93 	because the index is out of bounds, or the index is in bounds
     94 	but the arena it represents doesn't contain the address.
     95 
     96         This determination has to be made on every call to one of
     97 	pymalloc's free/realloc entry points, so its speed is critical
     98 	(Python allocates and frees dynamic memory at a ferocious rate
     99 	-- everything in Python, from integers to "stack frames",
    100 	lives in the heap).
    101