From be40754e9169b20a74a09734f68035fdfd45561b Mon Sep 17 00:00:00 2001 From: Magnus Hagander Date: Tue, 13 Mar 2007 16:03:36 +0000 Subject: [PATCH] Rewrite win32 install documentation (it's not client only anymore, and it's now complete). Update for the MSVC6/Borland support now being only libpq. Move most of the information about full MSVC build from README file into documentation. --- doc/src/sgml/install-win32.sgml | 386 ++++++++++++++++++++++++++------ doc/src/sgml/installation.sgml | 31 +-- src/tools/msvc/README | 71 +----- 3 files changed, 324 insertions(+), 164 deletions(-) diff --git a/doc/src/sgml/install-win32.sgml b/doc/src/sgml/install-win32.sgml index 79b32c0843..eac355e9a5 100644 --- a/doc/src/sgml/install-win32.sgml +++ b/doc/src/sgml/install-win32.sgml @@ -1,7 +1,7 @@ - + - Client-Only Installation on <productname>Windows</productname> + Installation on <productname>Windows</productname> installation @@ -9,46 +9,331 @@ - Although a complete PostgreSQL installation - for Windows can only be built using - MinGW or - Cygwin, the C client library - (libpq) and the interactive terminal - (psql) can be compiled using other Windows - tool sets. Makefiles are included in the source distribution for - Microsoft Visual C++ and - Borland C++. It should be possible to - compile the libraries manually for other configurations. + It is recommended that most users download the binary distribution for + Windows, available as a Windows Installer package + from the PostgreSQL website. Building from source + is only intended for people developing PostgreSQL + or extensions. - - - Using MinGW or - Cygwin is preferred. If using one of - those tool sets, see . - - + + There are several different ways of building PostgreSQL on + Windows. The complete system can + be built using MinGW or + Visual C++ 2005. It can also be + built for older versions of Windows using + Cygwin. Finally, the client access library + (libpq) can be built using + Visual C++ 6.0 or + Borland C++ for compatibility with statically + linked applications built using these tools. + - To build everything that you can on Windows - using Microsoft Visual C++, change into the + Building using MinGW or + Cygwin uses the normal build system, see + and the FAQs in + doc/FAQ_MINGW and do/FAQ_CYGWIN. + Note that Cygwin is not recommended, and should + only be used for older versions of Windows where + the native build does not work, such as + Windows 98. + + + + Building with <productname>Visual C++ 2005</productname> + + + The tools for building using Visual C++ 2005, + are in the src/tools/msvc directory. When building, + make sure there are no tools from MinGW or + Cygwin present in your system PATH. Also, make + sure you have all the required Visual C++ tools available in the PATH, + usually by starting a Visual Studio Command Prompt + and running the commands from there. All commands should be run from the + src\tools\msvc directory. + + + + Before you build, edit the file config.pl to reflect the + configuration options you want set, including the paths to libraries used. + If you need to set any other environment variables, create a file called + buildenv.bat and put the required commands there. For + example, to add the path for bison when it's not in the PATH, create a file + containing: + + @ECHO OFF + SET PATH=%PATH%;c:\some\where\bison\bin + + + + + Requirements + + PostgreSQL will build using either the professional versions (any edition) + or the free Express edition of + Visual Studio 2005. The following additional products + are required to build the complete package. Use the + config.pl to specify which directories the libraries + are available in. + + + + ActiveState Perl + + ActiveState Perl is required to run the build generation scripts. MinGW + or Cygwin perl will not work. It must also be present in the PATH. + Binaries can be downloaded from + . + + + + + ActiveState TCL + + Required for building PL/TCL. + + + + + Bison and + Flex + + Bison and Flex are required to build from CVS, but not required when + building from a release file. Note that Bison version 2.0 will not + work, but both earlier and later versions do. Bison and Flex can be + downloaded from . + + + + + Microsoft Platform SDK + + It is recommended that you upgrade to the latest available version + of the Microsoft Platform SDK, available + for download from . + + + MIT Kerberos + + Required for Kerberos authentication support. MIT Kerberos can be + downloaded from + . + + + + + libxml2 and + libxslt + + Required for XML support. Binaries can be downloaded from + or source from + . Note that libxml2 requires iconv, + which is available from the same download location. + + + + + openssl + + Required for SSL support. Binaries can be downloaded from + + or source from . + + + + + pthreads + + Required for building the ECPG libraries. + Binaries can be downloaded from + . + + + + + Python + + Required for building PL/Python. Binaries can + be downloaded from . + + + + + zlib + + Required for compression support in pg_dump + and pg_restore. Binaries can be downloaded + from . + + + + + + + + + Building + + + To build all of PostgreSQL in debug configuration (the default), run the + command: + + + build + + + To build all of PostgreSQL in release configuration, run the command: + + + build RELEASE + + + To build just a single project, for example psql, run the commands: + + + build psql + + + build RELEASE psql + + + + + + It is also possible to build from inside the Visual Studio GUI. In this + case, you need to run: + + + perl mkvcbuild.pl + + + from the command prompt, and then open the generated + pgsql.sln (in the root directory of the source tree) + in Visual Studio. + + + + + Cleaning and installing + + + Most of the time, the automatic dependency tracking in Visual Studio will + handle changed files. But if there have been large changes, you may need + to clean the installation. To do this, simply run the + clean.bat command, which will automatically clean out + all generated files. + + + + By default, all files are written into a subdirectory of the + debug or release directories. To + install these files using the standard layout, and also generate the files + required to initialize and use the database, run the command: + + + perl install.pl c:\destination\directory + + + + + + + Building the documentation + + + Building the PostgreSQL documentation in HTML format requires several tools + and files. Create a root directory for all these files, and store them + in the subdirectories in the list below. + + + OpenJade 1.3.1-2 + + Download from + + and uncompress in the subdirectory openjade-1.3.1. + + + + + DocBook DTD 4.2 + + Download from + + and uncompress in the subdirectory docbook. + + + + + DocBook DSSL 1.79 + + Download from + + and uncompress in the subdirectory + docbook-dsssl-1.79. + + + + + ISO character entities + + Download from + and + uncompress in the subdirectory docbook. + + + + Edit the buildenv.bat file, and add a variable for the + location of the root directory, for example: + + @ECHO OFF + SET DOCROOT=c:\docbook + + To build the documentation, run the command + builddoc.bat. Note that this will actually run the + build twice, in order to generate the indexes. The generated HTML files + will be in doc\src\sgml. + + + + + + + Building <application>libpq</application> with + <productname>Visual C++</productname> or + <productname>Borland C++</productname> + + + Using Visual Studio 6.0 or + Borland C++ to build libpq is only recommended + if you need a version with different debug/release flags, or if you need a + static library to link into an application. For normal use the + MinGW or + Visual Studio 2005 version is recommended. + + + + To build the libpq client library using + Visual Studio 6.0, change into the src directory and type the command nmake /f win32.mak - This assumes that you have Visual C++ in - your path. - To build everything using Borland - C++, change into the src directory - and type the command + To build the libpq client library using + Borland C++, change into the + src directory and type the command make -N -DCFG=Release /f bcc32.mak + + Generated files The following files will be built: @@ -80,45 +365,23 @@ - - bin\pg_config\Release\pg_config.exe - bin\psql\Release\psql.exe - bin\pg_dump\Release\pg_dump.exe - bin\pg_dump\Release\pg_dumpall.exe - bin\pg_dump\Release\pg_restore.exe - bin\scripts\Release\clusterdb.exe - bin\scripts\Release\createdb.exe - bin\scripts\Release\createuser.exe - bin\scripts\Release\createlang.exe - bin\scripts\Release\dropdb.exe - bin\scripts\Release\dropuser.exe - bin\scripts\Release\droplang.exe - bin\scripts\Release\vacuumdb.exe - bin\scripts\Release\reindexdb.exe - - - The PostgreSQL client applications and utilities. - - - - Normally you do not need to install any of the client files. You should place the libpq.dll file in the same directory - as your applications .EXE-file. Only if this is for some reason not - possible should you install it in the WINNT\SYSTEM32 - directory (or in WINDOWS\SYSTEM on a Windows 95/98/ME - system). If this file is installed using a setup program, it should + as your applications executable file. Do not install + libpq.dll into your Windows, System or System32 + directory unless absolutely necessary. + If this file is installed using a setup program, it should be installed with version checking using the VERSIONINFO resource included in the file, to ensure that a newer version of the library is not overwritten. - If you plan to do development using libpq + If you are planning to do development using libpq on this machine, you will have to add the src\include and src\interfaces\libpq subdirectories of the source @@ -130,19 +393,6 @@ libpqdll.lib file to your project. (In Visual C++, just right-click on the project and choose to add it.) - - - Free development tools from Microsoft - can be downloaded from - . - You will also need MSVCRT.lib from the platform SDK from - . - You can also download the .NET framework from - . - Once installed, the toolkit binaries must be in your path, and you might - need to add a /lib:<libpath> to point to MSVCRT.lib. - Free Borland C++ compiler tools can be downloaded from - , - and require similar setup. - + + diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index bc7d3aef61..262dbe7130 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,4 +1,4 @@ - + <![%standalone-include[<productname>PostgreSQL</>]]> @@ -141,35 +141,6 @@ su - postgres <application>pg_restore</>. </para> </listitem> - - <listitem> - <para> - <indexterm> - <primary>installation</primary> - <secondary>on Windows</secondary> - </indexterm> - - Additional software is needed to build - <productname>PostgreSQL</productname> on <productname>Windows</>. - You can build <productname>PostgreSQL</productname> for - <productname>NT</>-based versions of <productname>Windows</> - (like Windows XP and 2003) using <productname>MinGW</productname>; - see <filename>doc/FAQ_MINGW</> for details. You can also build - <productname>PostgreSQL</productname> using - <productname>Cygwin</productname>; see <filename>doc/FAQ_CYGWIN</>. - A <productname>Cygwin</productname>-based build will work on older - versions of <productname>Windows</>, but if you have a choice, - we recommend the <productname>MinGW</productname> approach. - While these are the only tool sets recommended for a complete build, - it is possible to build just the C client library - (<application>libpq</application>) and the interactive terminal - (<application>psql</application>) using other <productname>Windows</> - tool sets. For details of that see - <![%standalone-include[the documentation chapter "Client-Only - Installation on Windows"]]> <![%standalone-ignore[<xref - linkend="install-win32">]]>. - </para> - </listitem> </itemizedlist> </para> diff --git a/src/tools/msvc/README b/src/tools/msvc/README index dc1edae6f0..e0123a953f 100644 --- a/src/tools/msvc/README +++ b/src/tools/msvc/README @@ -1,72 +1,11 @@ This directory contains the tools required to build PostgreSQL using -Microsoft Visual Studio 2005. +Microsoft Visual Studio 2005. This builds the whole backend, not just +the libpq frontend library. For more information, see the documentation +chapter "Installation on Windows". -Note that PostgreSQL builds natively with Visual C++. You must therefore -make sure that you do *NOT* have any tools from Cygwin or Mingw present -in the system PATH. Also, make sure you don't have any Cygwin/Mingw -environment variables "leaking" through. - -First, edit config.pl to reflect what "configure options" you want set. - -If you need to modify the environment for calling external tools, such as -flex or bison, create a file called "buildenv.bat". This file will be called -by all scripts before anything is done, so the environment can be set up. -(for example, include SET PATH=%PATH%;c:\some\where\bison\bin) - -Then, to build all of PostgreSQL in debug configuration, run the command - build -from a Visual Studio Command Prompt (to get all environment -variables set correctly). - -To build all of PostgreSQL in release configuration, run - build RELEASE - -To build just a single project, for example psql, run - build psql -or - build RELEASE psql - - -Dependencies ------------- - -The following packages are needed for the different config options: - -pthreads - always required -Download from ftp://sources.redhat.com/pub/pthreads-win32 - -perl - always required -Get ActiveState Perl from www.activestate.com - -flex & bison - required to build from CVS (as opposed to a release tarball) -Download from http://gnuwin32.sourceforge.net. Note that bison version 2.0 -will not work. Use either version 1.875, or version 2.1 or newer. -For flex, use version 2.5.4. - -python - required for pl/python -Get from www.python.org - -tcl - required for pl/tcl -Get ActiveState TCL from www.activestate.com - -openssl - required for SSL support -Get from http://www.slproweb.com/products/Win32OpenSSL.html, or build -from source from www.openssl.org. - -Kerberos - required for Kerberos support -Get from http://web.mit.edu/Kerberos/dist/index.html - -zlib - required for compression support in pg_dump/pg_restore -Get from http://www.zlib.net - -libxml2 and libxslt - required for XML support -Get from http://www.zlatkovic.com/pub/libxml or build from source from -http://xmlsoft.org. Note that libxml2 requires iconv. - - -Code indention --------------- +Notes about code indention +-------------------------- If the perl code is modified, use perltidy on it since pgindent won't touch perl code. Use the following commandline: perltidy -b -bl -nsfs -naws -l=100 *.pl *.pm