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 F7 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 NOTE:
  27    You probably don't want to build most of the other subprojects, unless
  28    you're building an entire Python distribution from scratch, or
  29    specifically making changes to the subsystems they implement, or are
  30    running a Python core buildbot test slave; see SUBPROJECTS below)
  31
  32 When using the Debug setting, the output files have a _d added to
  33 their name:  python30_d.dll, python_d.exe, parser_d.pyd, and so on. Both
  34 the build and rt batch files accept a -d option for debug builds.
  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     NOTE: Tcl/Tk 8.4 doesn't compile for x64.
 127
 128     Build Tcl first
 129     ---------------
 130     Use "Start -> All Programs -> Microsoft Visual Studio 2008
 131          -> Visual Studio Tools -> Visual Studio 2008 Command Prompt"
 132     to get a shell window with the correct environment settings
 133     cd dist\tcl8.4.16\win
 134     nmake -f makefile.vc
 135     nmake -f makefile.vc INSTALLDIR=..\..\tcltk install
 136
 137     XXX Should we compile with OPTS=threads?
 138
 139     Optional:  run tests, via
 140         nmake -f makefile.vc test
 141
 142         On WinXP Pro, wholly up to date as of 30-Aug-2004:
 143         all.tcl:        Total   10678   Passed  9969    Skipped 709     Failed  0
 144         Sourced 129 Test Files.
 145
 146     Build Tk
 147     --------
 148     cd dist\tk8.4.16\win
 149     nmake -f makefile.vc TCLDIR=..\..\tcl8.4.16
 150     nmake -f makefile.vc TCLDIR=..\..\tcl8.4.16 INSTALLDIR=..\..\tcltk install
 151
 152     XXX Should we compile with OPTS=threads?
 153
 154     XXX Our installer copies a lot of stuff out of the Tcl/Tk install
 155     XXX directory.  Is all of that really needed for Python use of Tcl/Tk?
 156
 157     Optional:  run tests, via
 158         nmake -f makefile.vc TCLDIR=..\..\tcl8.4.16 test
 159
 160         On WinXP Pro, wholly up to date as of 30-Aug-2004:
 161         all.tcl:        Total   8420    Passed  6826    Skipped 1581    Failed  13
 162         Sourced 91 Test Files.
 163         Files with failing tests: canvImg.test scrollbar.test textWind.test winWm.test
 164
 165    Built Tix
 166    ---------
 167    cd dist\tix-8.4.0\win
 168    nmake -f python9.mak
 169    nmake -f python9.mak install
 170
 171 bz2
 172     Python wrapper for the libbz2 compression library.  Homepage
 173         http://sources.redhat.com/bzip2/
 174     Download the source from the python.org copy into the dist
 175     directory:
 176
 177     svn export http://svn.python.org/projects/external/bzip2-1.0.3
 178
 179     A custom pre-link step in the bz2 project settings should manage to
 180     build bzip2-1.0.3\libbz2.lib by magic before bz2.pyd (or bz2_d.pyd) is
 181     linked in PCbuild\.
 182     However, the bz2 project is not smart enough to remove anything under
 183     bzip2-1.0.3\ when you do a clean, so if you want to rebuild bzip2.lib
 184     you need to clean up bzip2-1.0.3\ by hand.
 185
 186     All of this managed to build libbz2.lib in
 187     bzip2-1.0.3\$platform-$configuration\, which the Python project links in.
 188
 189
 190 _bsddb
 191     To use the version of bsddb that Python is built with by default, invoke
 192     (in the dist directory)
 193
 194       svn export http://svn.python.org/projects/external/db-4.4.20
 195
 196     Next open the solution file db-4.4.20\build_win32\Berkeley_DB.sln with
 197     Visual Studio and convert the projects to the new format. VS 2008
 198     builds the necessary libraries in a pre-link step of _bsddb. You
 199     have to add "$(VCInstallDir)vcpackages" to the search path first
 200     (Tools -> Options -> Projects and Solutions -> VC++ Directories,
 201      Platform: Win32, Show directories for: Executable files).
 202
 203     The _bsddb subprojects depends only on the db_static project of
 204     Berkeley DB. You have to choose either "Release", "Release AMD64", "Debug"
 205     or "Debug AMD64" as configuration. For the AND64 builds, you need to
 206     create the "x64" platform first (in Solution Platforms\Configuration
 207     Manager...)
 208
 209     Alternatively, if you want to start with the original sources,
 210     go to Sleepycat's download page:
 211         http://www.sleepycat.com/downloads/releasehistorybdb.html
 212
 213     and download version 4.4.20.
 214
 215     With or without strong cryptography? You can choose either with or
 216     without strong cryptography, as per the instructions below.  By
 217     default, Python is built and distributed WITHOUT strong crypto.
 218
 219     Unpack the sources; if you downloaded the non-crypto version, rename
 220     the directory from db-4.4.20.NC to db-4.4.20.
 221
 222     Now apply any patches that apply to your version.
 223
 224     Open
 225         db-4.4.20\docs\ref\build_win\intro.html
 226
 227     and follow the "Windows->Building Berkeley DB with Visual C++ .NET"
 228     instructions for building the Sleepycat
 229     software.  Note that Berkeley_DB.dsw is in the build_win32 subdirectory.
 230     Build the "db_static" project, for "Release" mode.
 231
 232     To run extensive tests, pass "-u bsddb" to regrtest.py.  test_bsddb3.py
 233     is then enabled.  Running in verbose mode may be helpful.
 234
 235 _sqlite3
 236     Python wrapper for SQLite library.
 237
 238     Get the source code through
 239
 240     svn export http://svn.python.org/projects/external/sqlite-source-3.3.4
 241
 242     To use the extension module in a Python build tree, copy sqlite3.dll into
 243     the PCbuild folder. The source directory in svn also contains a .def file
 244     from the binary release of sqlite3.
 245
 246 _ssl
 247     Python wrapper for the secure sockets library.
 248
 249     Get the source code through
 250
 251     svn export http://svn.python.org/projects/external/openssl-0.9.8g
 252
 253     Alternatively, get the latest version from http://www.openssl.org.
 254     You can (theoretically) use any version of OpenSSL you like - the
 255     build process will automatically select the latest version.
 256
 257     You must install the NASM assembler from
 258         http://www.kernel.org/pub/software/devel/nasm/binaries/win32/
 259     for x86 builds.  Put nasmw.exe anywhere in your PATH.
 260
 261     You can also install ActivePerl from
 262         http://www.activestate.com/Products/ActivePerl/
 263     if you like to use the official sources instead of the files from
 264     python's subversion repository. The svn version contains pre-build
 265     makefiles and assembly files.
 266
 267     The build process makes sure that no patented algorithms are included.
 268     For now RC5, MDC2 and IDEA are excluded from the build. You may have
 269     to manually remove $(OBJ_D)\i_*.obj from ms\nt.mak if the build process
 270     complains about missing files or forbidden IDEA. Again the files provided
 271     in the subversion repository are already fixed.
 272
 273     The MSVC project simply invokes PCBuild/build_ssl.py to perform
 274     the build.  This Python script locates and builds your OpenSSL
 275     installation, then invokes a simple makefile to build the final .pyd.
 276
 277     build_ssl.py attempts to catch the most common errors (such as not
 278     being able to find OpenSSL sources, or not being able to find a Perl
 279     that works with OpenSSL) and give a reasonable error message.
 280     If you have a problem that doesn't seem to be handled correctly
 281     (eg, you know you have ActivePerl but we can't find it), please take
 282     a peek at build_ssl.py and suggest patches.  Note that build_ssl.py
 283     should be able to be run directly from the command-line.
 284
 285     build_ssl.py/MSVC isn't clever enough to clean OpenSSL - you must do
 286     this by hand.
 287
 288 Building for Itanium
 289 --------------------
 290
 291 NOTE:
 292 Official support for Itanium builds have been dropped from the build. Please
 293 contact us and provide patches if you are interested in Itanium builds.
 294
 295 The project files support a ReleaseItanium configuration which creates
 296 Win64/Itanium binaries. For this to work, you need to install the Platform
 297 SDK, in particular the 64-bit support. This includes an Itanium compiler
 298 (future releases of the SDK likely include an AMD64 compiler as well).
 299 In addition, you need the Visual Studio plugin for external C compilers,
 300 from http://sf.net/projects/vsextcomp. The plugin will wrap cl.exe, to
 301 locate the proper target compiler, and convert compiler options
 302 accordingly. The project files require atleast version 0.9.
 303
 304 Building for AMD64
 305 ------------------
 306
 307 The build process for AMD64 / x64 is very similar to standard builds. You just
 308 have to set x64 as platform. In addition, the HOST_PYTHON environment variable
 309 must point to a Python interpreter (at least 2.4), to support cross-compilation.
 310
 311 Building Python Using the free MS Toolkit Compiler
 312 --------------------------------------------------
 313
 314 Microsoft has withdrawn the free MS Toolkit Compiler, so this can no longer
 315 be considered a supported option. Instead you can use the free VS C++ Express
 316 Edition.
 317
 318 Profile Guided Optimization
 319 ---------------------------
 320
 321 The solution has two configurations for PGO. The PGInstrument
 322 configuration must be build first. The PGInstrument binaries are
 323 lniked against a profiling library and contain extra debug
 324 information. The PGUpdate configuration takes the profiling data and
 325 generates optimized binaries.
 326
 327 The build_pgo.bat script automates the creation of optimized binaries. It
 328 creates the PGI files, runs the unit test suite or PyBench with the PGI
 329 python and finally creates the optimized files.
 330
 331 http://msdn2.microsoft.com/en-us/library/e7k32f4k(VS.90).aspx
 332
 333 Static library
 334 --------------
 335
 336 The solution has no configuration for static libraries. However it is easy
 337 it build a static library instead of a DLL. You simply have to set the
 338 "Configuration Type" to "Static Library (.lib)" and alter the preprocessor
 339 macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may also have to
 340 change the "Runtime Library" from "Multi-threaded DLL (/MD)" to
 341 "Multi-threaded (/MT)".
 342
 343 Visual Studio properties
 344 ------------------------
 345
 346 The PCbuild solution makes heavy use of Visual Studio property files
 347 (*.vsprops). The properties can be viewed and altered in the Property
 348 Manager (View -> Other Windows -> Property Manager).
 349
 350  * debug (debug macro: _DEBUG)
 351  * pginstrument (PGO)
 352  * pgupdate (PGO)
 353     +-- pginstrument
 354  * pyd (python extension, release build)
 355     +-- release
 356     +-- pyproject
 357  * pyd_d (python extension, debug build)
 358     +-- debug
 359     +-- pyproject
 360  * pyproject (base settings for all projects, user macros like PyDllName)
 361  * release (release macro: NDEBUG)
 362  * x64 (AMD64 / x64 platform specific settings)
 363
 364 The pyproject propertyfile defines _WIN32 and x64 defines _WIN64 and _M_X64
 365 although the macros are set by the compiler, too. The GUI doesn't always know
 366 about the macros and confuse the user with false information.
 367
 368 YOUR OWN EXTENSION DLLs
 369 -----------------------
 370
 371 If you want to create your own extension module DLL, there's an example
 372 with easy-to-follow instructions in ../PC/example/; read the file
 373 readme.txt there first.