PCbuild/readme.txt

   1 Building Python using VC++ 9.0
   2 ------------------------------
   3
   4 This directory is used to build Python for Win32 platforms, e.g. Windows
   5 2000, XP and Vista.  It requires Microsoft Visual C++ 9.0
   6 (a.k.a. Visual Studio .NET 2008).
   7 (For other Windows platforms and compilers, see ../PC/readme.txt.)
   8
   9 All you need to do is open the workspace "pcbuild.sln" in Visual Studio,
  10 select the desired combination of configuration and platform and eventually
  11 build the solution. Unless you are going to debug a problem in the core or
  12 you are going to create an optimized build you want to select "Release" as
  13 configuration.
  14
  15 The PCbuild directory is compatible with all versions of Visual Studio from
  16 VS C++ Express Edition over the standard edition up to the professional
  17 edition. However the express edition does support features like solution
  18 folders or profile guided optimization (PGO). The missing bits and pieces
  19 won't stop you from building Python.
  20
  21 The solution is configured to build the projects in the correct order. "Build
  22 Solution" or F6 takes care of dependencies except for x64 builds. To make
  23 cross compiling x64 builds on a 32bit OS possible the x64 builds require a
  24 32bit version of Python.
  25
  26
  27 NOTE:
  28    You probably don't want to build most of the other subprojects, unless
  29    you're building an entire Python distribution from scratch, or
  30    specifically making changes to the subsystems they implement, or are
  31    running a Python core buildbot test slave; see SUBPROJECTS below)
  32
  33 When using the Debug setting, the output files have a _d added to
  34 their name:  python30_d.dll, python_d.exe, parser_d.pyd, and so on.
  35
  36 The 32bit builds end up in the solution folder PCbuild while the x64 builds
  37 land in the amd64 subfolder. The PGI and PGO builds for profile guided
  38 optimization end up in their own folders, too.
  39
  40 Legacy support
  41 --------------
  42
  43 You can find build directories for older versions of Visual Studio and
  44 Visual C++ in the PC directory. The legacy build directories are no longer
  45 actively maintained and may not work out of the box.
  46
  47 PC/VC6/
  48     Visual C++ 6.0
  49 PC/VS7.1/
  50     Visual Studio 2003 (7.1)
  51 PCbuild8/
  52     Visual Studio 2005 (8.0)
  53
  54
  55 C RUNTIME
  56 ---------
  57
  58 Visual Studio 2008 uses version 9 of the C runtime (MSVCRT9).  The executables
  59 are linked to a CRT "side by side" assembly which must be present on the target
  60 machine.  This is avalible under the VC/Redist folder of your visual studio
  61 distribution. On XP and later operating systems that support
  62 side-by-side assemblies it is not enough to have the msvcrt80.dll present,
  63 it has to be there as a whole assembly, that is, a folder with the .dll
  64 and a .manifest.  Also, a check is made for the correct version.
  65 Therefore, one should distribute this assembly with the dlls, and keep
  66 it in the same directory.  For compatibility with older systems, one should
  67 also set the PATH to this directory so that the dll can be found.
  68 For more info, see the Readme in the VC/Redist folder.
  69
  70 SUBPROJECTS
  71 -----------
  72 These subprojects should build out of the box.  Subprojects other than the
  73 main ones (pythoncore, python, pythonw) generally build a DLL (renamed to
  74 .pyd) from a specific module so that users don't have to load the code
  75 supporting that module unless they import the module.
  76
  77 pythoncore
  78     .dll and .lib
  79 python
  80     .exe
  81 pythonw
  82     pythonw.exe, a variant of python.exe that doesn't pop up a DOS box
  83 _socket
  84     socketmodule.c
  85 _testcapi
  86     tests of the Python C API, run via Lib/test/test_capi.py, and
  87     implemented by module Modules/_testcapimodule.c
  88 pyexpat
  89     Python wrapper for accelerated XML parsing, which incorporates stable
  90     code from the Expat project:  http://sourceforge.net/projects/expat/
  91 select
  92     selectmodule.c
  93 unicodedata
  94     large tables of Unicode data
  95 winsound
  96     play sounds (typically .wav files) under Windows
  97
  98 The following subprojects will generally NOT build out of the box. They
  99 wrap code Python doesn't control, and you'll need to download the base
 100 packages first and unpack them into siblings of PCbuilds's parent
 101 directory; for example, if your PCbuild is  ..\dist\py3k\PCbuild\,
 102 unpack into new subdirectories of ..\dist\.
 103
 104 _tkinter
 105     Python wrapper for the Tk windowing system.  Requires building
 106     Tcl/Tk first.  Following are instructions for Tcl/Tk 8.4.16.
 107
 108     NOTE: The 64 build builds must land in tcltk64 instead of tcltk.
 109
 110     Get source
 111     ----------
 112     In the dist directory, run
 113     svn export http://svn.python.org/projects/external/tcl8.4.16
 114     svn export http://svn.python.org/projects/external/tk8.4.16
 115     svn export http://svn.python.org/projects/external/tix-8.4.0
 116
 117     Build with build_tkinter.py
 118     ---------------------------
 119     The PCbuild directory contains a Python script which automates all
 120     steps. Run the script in a Visual Studio 2008 command prompt with
 121
 122       python build_tkinter.py Win32
 123
 124     Use x64 instead of Win32 for the x64 platform.
 125
 126     Build Tcl first
 127     ---------------
 128     Use "Start -> All Programs -> Microsoft Visual Studio 2008
 129          -> Visual Studio Tools -> Visual Studio 2008 Command Prompt"
 130     to get a shell window with the correct environment settings
 131     cd dist\tcl8.4.16\win
 132     nmake -f makefile.vc
 133     nmake -f makefile.vc INSTALLDIR=..\..\tcltk install
 134
 135     XXX Should we compile with OPTS=threads?
 136
 137     Optional:  run tests, via
 138         nmake -f makefile.vc test
 139
 140         On WinXP Pro, wholly up to date as of 30-Aug-2004:
 141         all.tcl:        Total   10678   Passed  9969    Skipped 709     Failed  0
 142         Sourced 129 Test Files.
 143
 144     Build Tk
 145     --------
 146     cd dist\tk8.4.16\win
 147     nmake -f makefile.vc TCLDIR=..\..\tcl8.4.16
 148     nmake -f makefile.vc TCLDIR=..\..\tcl8.4.16 INSTALLDIR=..\..\tcltk install
 149
 150     XXX Should we compile with OPTS=threads?
 151
 152     XXX Our installer copies a lot of stuff out of the Tcl/Tk install
 153     XXX directory.  Is all of that really needed for Python use of Tcl/Tk?
 154
 155     Optional:  run tests, via
 156         nmake -f makefile.vc TCLDIR=..\..\tcl8.4.16 test
 157
 158         On WinXP Pro, wholly up to date as of 30-Aug-2004:
 159         all.tcl:        Total   8420    Passed  6826    Skipped 1581    Failed  13
 160         Sourced 91 Test Files.
 161         Files with failing tests: canvImg.test scrollbar.test textWind.test winWm.test
 162
 163    Built Tix
 164    ---------
 165    cd dist\tix-8.4.0\win
 166    nmake -f python9.mak
 167    nmake -f python9.mak install
 168
 169 bz2
 170     Python wrapper for the libbz2 compression library.  Homepage
 171         http://sources.redhat.com/bzip2/
 172     Download the source from the python.org copy into the dist
 173     directory:
 174
 175     svn export http://svn.python.org/projects/external/bzip2-1.0.3
 176
 177     A custom pre-link step in the bz2 project settings should manage to
 178     build bzip2-1.0.3\libbz2.lib by magic before bz2.pyd (or bz2_d.pyd) is
 179     linked in PCbuild\.
 180     However, the bz2 project is not smart enough to remove anything under
 181     bzip2-1.0.3\ when you do a clean, so if you want to rebuild bzip2.lib
 182     you need to clean up bzip2-1.0.3\ by hand.
 183
 184     All of this managed to build libbz2.lib in
 185     bzip2-1.0.3\$platform-$configuration\, which the Python project links in.
 186
 187
 188 _bsddb
 189     To use the version of bsddb that Python is built with by default, invoke
 190     (in the dist directory)
 191
 192       svn export http://svn.python.org/projects/external/db-4.4.20
 193
 194     Next open the solution file db-4.4.20\build_win32\Berkeley_DB.sln with
 195     Visual Studio and convert the projects to the new format. The standard
 196     and professional version of VS 2008 builds the necessary libraries
 197     in a pre-link step of _bsddb. However the express edition is missing
 198     some pieces and you have to build the libs yourself.
 199
 200     The _bsddb subprojects depends only on the db_static project of
 201     Berkeley DB. You have to choose either "Release", "Release AMD64", "Debug"
 202     or "Debug AMD64" as configuration.
 203
 204     Alternatively, if you want to start with the original sources,
 205     go to Sleepycat's download page:
 206         http://www.sleepycat.com/downloads/releasehistorybdb.html
 207
 208     and download version 4.4.20.
 209
 210     With or without strong cryptography? You can choose either with or
 211     without strong cryptography, as per the instructions below.  By
 212     default, Python is built and distributed WITHOUT strong crypto.
 213
 214     Unpack the sources; if you downloaded the non-crypto version, rename
 215     the directory from db-4.4.20.NC to db-4.4.20.
 216
 217     Now apply any patches that apply to your version.
 218
 219     Open
 220         db-4.4.20\docs\ref\build_win\intro.html
 221
 222     and follow the "Windows->Building Berkeley DB with Visual C++ .NET"
 223     instructions for building the Sleepycat
 224     software.  Note that Berkeley_DB.dsw is in the build_win32 subdirectory.
 225     Build the "db_static" project, for "Release" mode.
 226
 227     To run extensive tests, pass "-u bsddb" to regrtest.py.  test_bsddb3.py
 228     is then enabled.  Running in verbose mode may be helpful.
 229
 230 _sqlite3
 231     Python wrapper for SQLite library.
 232
 233     Get the source code through
 234
 235     svn export http://svn.python.org/projects/external/sqlite-source-3.3.4
 236
 237     To use the extension module in a Python build tree, copy sqlite3.dll into
 238     the PCbuild folder. The source directory in svn also contains a .def file
 239     from the binary release of sqlite3.
 240
 241 _ssl
 242     Python wrapper for the secure sockets library.
 243
 244     Get the source code through
 245
 246     svn export http://svn.python.org/projects/external/openssl-0.9.8g
 247
 248     Alternatively, get the latest version from http://www.openssl.org.
 249     You can (theoretically) use any version of OpenSSL you like - the
 250     build process will automatically select the latest version.
 251
 252     You must install the NASM assembler from
 253         http://www.kernel.org/pub/software/devel/nasm/binaries/win32/
 254     for x86 builds.  Put nasmw.exe anywhere in your PATH.
 255
 256     You can also install ActivePerl from
 257         http://www.activestate.com/Products/ActivePerl/
 258     if you like to use the official sources instead of the files from
 259     python's subversion repository. The svn version contains pre-build
 260     makefiles and assembly files.
 261
 262     The build process makes sure that no patented algorithms are included.
 263     For now RC5, MDC2 and IDEA are excluded from the build. You may have
 264     to manually remove $(OBJ_D)\i_*.obj from ms\nt.mak if the build process
 265     complains about missing files or forbidden IDEA. Again the files provided
 266     in the subversion repository are already fixed.
 267
 268     The MSVC project simply invokes PCBuild/build_ssl.py to perform
 269     the build.  This Python script locates and builds your OpenSSL
 270     installation, then invokes a simple makefile to build the final .pyd.
 271
 272     build_ssl.py attempts to catch the most common errors (such as not
 273     being able to find OpenSSL sources, or not being able to find a Perl
 274     that works with OpenSSL) and give a reasonable error message.
 275     If you have a problem that doesn't seem to be handled correctly
 276     (eg, you know you have ActivePerl but we can't find it), please take
 277     a peek at build_ssl.py and suggest patches.  Note that build_ssl.py
 278     should be able to be run directly from the command-line.
 279
 280     build_ssl.py/MSVC isn't clever enough to clean OpenSSL - you must do
 281     this by hand.
 282
 283 Building for Itanium
 284 --------------------
 285
 286 NOTE:
 287 Official support for Itanium builds have been dropped from the build. Please
 288 contact as and provide patches if you are interested in Itanium builds.
 289
 290 The project files support a ReleaseItanium configuration which creates
 291 Win64/Itanium binaries. For this to work, you need to install the Platform
 292 SDK, in particular the 64-bit support. This includes an Itanium compiler
 293 (future releases of the SDK likely include an AMD64 compiler as well).
 294 In addition, you need the Visual Studio plugin for external C compilers,
 295 from http://sf.net/projects/vsextcomp. The plugin will wrap cl.exe, to
 296 locate the proper target compiler, and convert compiler options
 297 accordingly. The project files require atleast version 0.9.
 298
 299 Building for AMD64
 300 ------------------
 301
 302 The build process for AMD64 / x64 is very similar to standard builds. You just
 303 have to set x64 as platform.
 304
 305 Building Python Using the free MS Toolkit Compiler
 306 --------------------------------------------------
 307
 308 Microsoft has withdrawn the free MS Toolkit Compiler, so this can no longer
 309 be considered a supported option. Instead you can use the free VS C++ Express
 310 Edition.
 311
 312 Profile Guided Optimization
 313 ---------------------------
 314
 315 The solution has two configurations for PGO. The PGInstrument
 316 configuration must be build first. The PGInstrument binaries are
 317 lniked against a profiling library and contain extra debug
 318 information. The PGUpdate configuration takes the profiling data and
 319 generates optimized binaries.
 320
 321 The build_pgo.bat script automates the creation of optimized binaries. It
 322 creates the PGI files, runs the unit test suite or PyBench with the PGI
 323 python and finally creates the optimized files.
 324
 325 http://msdn2.microsoft.com/en-us/library/e7k32f4k(VS.90).aspx
 326
 327 Static library
 328 --------------
 329
 330 The solution has no configuration for static libraries. However it is easy
 331 it build a static library instead of a DLL. You simply have to set the
 332 "Configuration Type" to "Static Library (.lib)" and alter the preprocessor
 333 macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may also have to
 334 change the "Runtime Library" from "Multi-threaded DLL (/MD)" to
 335 "Multi-threaded (/MT)".
 336
 337 Visual Studio properties
 338 ------------------------
 339
 340 The PCbuild solution makes heavy use of Visual Studio property files
 341 (*.vsprops). The properties can be viewed and altered in the Property
 342 Manager (View -> Other Windows -> Property Manager).
 343
 344  * debug (debug macro: _DEBUG)
 345  * pginstrument (PGO)
 346  * pgupdate (PGO)
 347     +-- pginstrument
 348  * pyd (python extension, release build)
 349     +-- release
 350     +-- pyproject
 351  * pyd_d (python extension, debug build)
 352     +-- debug
 353     +-- pyproject
 354  * pyproject (base settings for all projects, user macros like PyDllName)
 355  * release (release macro: NDEBUG)
 356  * x64 (AMD64 / x64 platform specific settings)
 357
 358 The pyproject propertyfile defines _WIN32 and x64 defines _WIN64 and _M_X64
 359 although the macros are set by the compiler, too. The GUI doesn't always know
 360 about the macros and confuse the user with false information.
 361
 362 YOUR OWN EXTENSION DLLs
 363 -----------------------
 364
 365 If you want to create your own extension module DLL, there's an example
 366 with easy-to-follow instructions in ../PC/example/; read the file
 367 readme.txt there first.