From be40754e9169b20a74a09734f68035fdfd45561b Mon Sep 17 00:00:00 2001
From: Magnus Hagander <magnus@hagander.net>
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 | 382 ++++++++++++++++++++++++++------
doc/src/sgml/installation.sgml | 31 +--
src/tools/msvc/README | 71 +-----
3 files changed, 322 insertions(+), 162 deletions(-)
diff --git a/doc/src/sgml/install-win32.sgml b/doc/src/sgml/install-win32.sgml
index 79b32c08433..eac355e9a55 100644
--- a/doc/src/sgml/install-win32.sgml
+++ b/doc/src/sgml/install-win32.sgml
@@ -1,7 +1,7 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.30 2007/02/02 16:10:08 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.31 2007/03/13 16:03:35 mha Exp $ -->
<chapter id="install-win32">
- <title>Client-Only Installation on <productname>Windows</productname></title>
+ <title>Installation on <productname>Windows</productname></title>
<indexterm>
<primary>installation</primary>
@@ -9,46 +9,331 @@
</indexterm>
<para>
- Although a complete <productname>PostgreSQL</productname> installation
- for <productname>Windows</> can only be built using
- <productname>MinGW</productname> or
- <productname>Cygwin</productname>, the C client library
- (<application>libpq</application>) and the interactive terminal
- (<application>psql</application>) can be compiled using other Windows
- tool sets. Makefiles are included in the source distribution for
- <productname>Microsoft Visual C++</productname> and
- <productname>Borland C++</productname>. 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 <productname>Windows Installer</productname> package
+ from the <productname>PostgreSQL</productname> website. Building from source
+ is only intended for people developing <productname>PostgreSQL</productname>
+ or extensions.
+ </para>
+
+ <para>
+ There are several different ways of building PostgreSQL on
+ <productname>Windows</productname>. The complete system can
+ be built using <productname>MinGW</productname> or
+ <productname>Visual C++ 2005</productname>. It can also be
+ built for older versions of <productname>Windows</productname> using
+ <productname>Cygwin</productname>. Finally, the client access library
+ (<application>libpq</application>) can be built using
+ <productname>Visual C++ 6.0</productname> or
+ <productname>Borland C++</productname> for compatibility with statically
+ linked applications built using these tools.
+ </para>
+
+ <para>
+ Building using <productname>MinGW</productname> or
+ <productname>Cygwin</productname> uses the normal build system, see
+ <xref linkend="installation"> and the FAQs in
+ <filename>doc/FAQ_MINGW</filename> and <filename>do/FAQ_CYGWIN</filename>.
+ Note that <productname>Cygwin</productname> is not recommended, and should
+ only be used for older versions of <productname>Windows</productname> where
+ the native build does not work, such as
+ <productname>Windows 98</productname>.
+ </para>
+
+ <sect1>
+ <title>Building with <productname>Visual C++ 2005</productname></title>
+
+ <para>
+ The tools for building using <productname>Visual C++ 2005</productname>,
+ are in the <filename>src/tools/msvc</filename> directory. When building,
+ make sure there are no tools from <productname>MinGW</productname> or
+ <productname>Cygwin</productname> present in your system PATH. Also, make
+ sure you have all the required Visual C++ tools available in the PATH,
+ usually by starting a <application>Visual Studio Command Prompt</application>
+ and running the commands from there. All commands should be run from the
+ <filename>src\tools\msvc</filename> directory.
+ </para>
+
+ <para>
+ Before you build, edit the file <filename>config.pl</filename> 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
+ <filename>buildenv.bat</filename> 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:
+ <screen>
+ @ECHO OFF
+ SET PATH=%PATH%;c:\some\where\bison\bin
+ </screen>
</para>
- <tip>
+ <sect2>
+ <title>Requirements</title>
+ <para>
+ PostgreSQL will build using either the professional versions (any edition)
+ or the free Express edition of
+ <productname>Visual Studio 2005</productname>. The following additional products
+ are required to build the complete package. Use the
+ <filename>config.pl</filename> to specify which directories the libraries
+ are available in.
+
+ <variablelist>
+ <varlistentry>
+ <term><productname>ActiveState Perl</productname></term>
+ <listitem><para>
+ 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
+ <ulink url="http://www.activestate.com"></>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><productname>ActiveState TCL</productname></term>
+ <listitem><para>
+ Required for building <application>PL/TCL</application>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><productname>Bison</productname> and
+ <productname>Flex</productname></term>
+ <listitem><para>
+ 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 <ulink url="http://gnuwin32.sourceforge.net"></>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><productname>Microsoft Platform SDK</productname></term>
+ <listitem><para>
+ It is recommended that you upgrade to the latest available version
+ of the <productname>Microsoft Platform SDK</productname>, available
+ for download from <ulink url="http://www.microsoft.com/downloads/"></>.
+ </para></listitem>
+ </varlistentry
+
+ <varlistentry>
+ <term><productname>MIT Kerberos</productname></term>
+ <listitem><para>
+ Required for Kerberos authentication support. MIT Kerberos can be
+ downloaded from
+ <ulink url="http://web.mit.edu/Kerberos/dist/index.html"></>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><productname>libxml2</productname> and
+ <productname>libxslt</productname></term>
+ <listitem><para>
+ Required for XML support. Binaries can be downloaded from
+ <ulink url="http://zlatkovic.com/pub/libxml"></> or source from
+ <ulink url="http://xmlsoft.org"></>. Note that libxml2 requires iconv,
+ which is available from the same download location.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><productname>openssl</productname></term>
+ <listitem><para>
+ Required for SSL support. Binaries can be downloaded from
+ <ulink url="http://www.slproweb.com/products/Win32OpenSSL.html"></>
+ or source from <ulink url="http://www.openssl.org"></>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><productname>pthreads</productname></term>
+ <listitem><para>
+ Required for building the <application>ECPG</application> libraries.
+ Binaries can be downloaded from
+ <ulink url="ftp://sources.redhat.com/pub/pthreads-win32"></>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><productname>Python</productname></term>
+ <listitem><para>
+ Required for building <application>PL/Python</application>. Binaries can
+ be downloaded from <ulink url="http://www.python.org"></>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><productname>zlib</productname></term>
+ <listitem><para>
+ Required for compression support in <application>pg_dump</application>
+ and <application>pg_restore</application>. Binaries can be downloaded
+ from <ulink url="http://www.zlib.net"></>.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Building</title>
+
+ <para>
+ To build all of PostgreSQL in debug configuration (the default), run the
+ command:
+ <screen>
+ <userinput>
+ build
+ </userinput>
+ </screen>
+ To build all of PostgreSQL in release configuration, run the command:
+ <screen>
+ <userinput>
+ build RELEASE
+ </userinput>
+ </screen>
+ To build just a single project, for example psql, run the commands:
+ <screen>
+ <userinput>
+ build psql
+ </userinput>
+ <userinput>
+ build RELEASE psql
+ </userinput>
+ </screen>
+ </para>
+
<para>
- Using <productname>MinGW</productname> or
- <productname>Cygwin</productname> is preferred. If using one of
- those tool sets, see <xref linkend="installation">.
+ It is also possible to build from inside the Visual Studio GUI. In this
+ case, you need to run:
+ <screen>
+ <userinput>
+ perl mkvcbuild.pl
+ </userinput>
+ </screen>
+ from the command prompt, and then open the generated
+ <filename>pgsql.sln</filename> (in the root directory of the source tree)
+ in Visual Studio.
</para>
- </tip>
+ </sect2>
+
+ <sect2>
+ <title>Cleaning and installing</title>
+
+ <para>
+ 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
+ <filename>clean.bat</filename> command, which will automatically clean out
+ all generated files.
+ </para>
+
+ <para>
+ By default, all files are written into a subdirectory of the
+ <filename>debug</filename> or <filename>release</filename> directories. To
+ install these files using the standard layout, and also generate the files
+ required to initialize and use the database, run the command:
+ <screen>
+ <userinput>
+ perl install.pl c:\destination\directory
+ </userinput>
+ </screen>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Building the documentation</title>
+
+ <para>
+ 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.
+ <variablelist>
+ <varlistentry>
+ <term>OpenJade 1.3.1-2</term>
+ <listitem><para>
+ Download from
+ <ulink url="http://sourceforge.net/project/downloading.php?groupname=openjade&filename=openjade-1_3_1-2-bin.zip"></>
+ and uncompress in the subdirectory <filename>openjade-1.3.1</filename>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DocBook DTD 4.2</term>
+ <listitem><para>
+ Download from
+ <ulink url="http://www.oasis-open.org/docbook/sgml/4.2/docbook-4.2.zip"></>
+ and uncompress in the subdirectory <filename>docbook</filename>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DocBook DSSL 1.79</term>
+ <listitem><para>
+ Download from
+ <ulink url="http://sourceforge.net/project/downloading.php?groupname=docbook&filename=docbook-dsssl-1.79.zip"></>
+ and uncompress in the subdirectory
+ <filename>docbook-dsssl-1.79</filename>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ISO character entities</term>
+ <listitem><para>
+ Download from
+ <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip"></> and
+ uncompress in the subdirectory <filename>docbook</filename>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ Edit the <filename>buildenv.bat</filename> file, and add a variable for the
+ location of the root directory, for example:
+ <screen>
+ @ECHO OFF
+ SET DOCROOT=c:\docbook
+ </screen>
+ To build the documentation, run the command
+ <filename>builddoc.bat</filename>. Note that this will actually run the
+ build twice, in order to generate the indexes. The generated HTML files
+ will be in <filename>doc\src\sgml</filename>.
+ </para>
+ </sect2>
+
+ </sect1>
+
+ <sect1>
+ <title>Building <application>libpq</application> with
+ <productname>Visual C++</productname> or
+ <productname>Borland C++</productname></title>
<para>
- To build everything that you can on <productname>Windows</productname>
- using <productname>Microsoft Visual C++</productname>, change into the
+ Using <productname>Visual Studio 6.0</productname> or
+ <productname>Borland C++</productname> 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
+ <productname>MinGW</productname> or
+ <productname>Visual Studio 2005</productname> version is recommended.
+ </para>
+
+ <para>
+ To build the <application>libpq</application> client library using
+ <productname>Visual Studio 6.0</productname>, change into the
<filename>src</filename> directory and type the command
<screen>
<userinput>nmake /f win32.mak</userinput>
</screen>
- This assumes that you have <productname>Visual C++</productname> in
- your path.
</para>
<para>
- To build everything using <productname>Borland
- C++</productname>, change into the <filename>src</filename> directory
- and type the command
+ To build the <application>libpq</application> client library using
+ <productname>Borland C++</productname>, change into the
+ <filename>src</filename> directory and type the command
<screen>
<userinput>make -N -DCFG=Release /f bcc32.mak</userinput>
</screen>
</para>
+ <sect2>
+ <title>Generated files</title>
<para>
The following files will be built:
@@ -80,45 +365,23 @@
</listitem>
</varlistentry>
- <varlistentry>
- <term><filename>bin\pg_config\Release\pg_config.exe</filename></term>
- <term><filename>bin\psql\Release\psql.exe</filename></term>
- <term><filename>bin\pg_dump\Release\pg_dump.exe</filename></term>
- <term><filename>bin\pg_dump\Release\pg_dumpall.exe</filename></term>
- <term><filename>bin\pg_dump\Release\pg_restore.exe</filename></term>
- <term><filename>bin\scripts\Release\clusterdb.exe</filename></term>
- <term><filename>bin\scripts\Release\createdb.exe</filename></term>
- <term><filename>bin\scripts\Release\createuser.exe</filename></term>
- <term><filename>bin\scripts\Release\createlang.exe</filename></term>
- <term><filename>bin\scripts\Release\dropdb.exe</filename></term>
- <term><filename>bin\scripts\Release\dropuser.exe</filename></term>
- <term><filename>bin\scripts\Release\droplang.exe</filename></term>
- <term><filename>bin\scripts\Release\vacuumdb.exe</filename></term>
- <term><filename>bin\scripts\Release\reindexdb.exe</filename></term>
- <listitem>
- <para>
- The <productname>PostgreSQL</productname> client applications and utilities.
- </para>
- </listitem>
- </varlistentry>
-
</variablelist>
</para>
<para>
Normally you do not need to install any of the client files. You should
place the <filename>libpq.dll</filename> 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 <filename>WINNT\SYSTEM32</filename>
- directory (or in <filename>WINDOWS\SYSTEM</filename> 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
+ <filename>libpq.dll</filename> 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
<symbol>VERSIONINFO</symbol> resource included in the file, to
ensure that a newer version of the library is not overwritten.
</para>
<para>
- If you plan to do development using <application>libpq</application>
+ If you are planning to do development using <application>libpq</application>
on this machine, you will have to add the
<filename>src\include</filename> and
<filename>src\interfaces\libpq</filename> subdirectories of the source
@@ -130,19 +393,6 @@
<filename>libpqdll.lib</filename> file to your project. (In Visual
C++, just right-click on the project and choose to add it.)
</para>
-
- <para>
- Free development tools from <productname>Microsoft</productname>
- can be downloaded from
- <ulink url="http://msdn.microsoft.com/visualc/vctoolkit2003/"></>.
- You will also need <filename>MSVCRT.lib</> from the platform SDK from
- <ulink url="http://www.microsoft.com/msdownload/platformsdk/sdkupdate/"></>.
- You can also download the <application>.NET</> framework from
- <ulink url="http://msdn.microsoft.com/netframework/downloads/updates/default.aspx"></>.
- Once installed, the toolkit binaries must be in your path, and you might
- need to add a <literal>/lib:<libpath></> to point to <filename>MSVCRT.lib</>.
- Free <productname>Borland C++</productname> compiler tools can be downloaded from
- <ulink url="http://www.borland.com/products/downloads/download_cbuilder.html#"></>,
- and require similar setup.
- </para>
+ </sect2>
+ </sect1>
</chapter>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index bc7d3aef615..262dbe7130a 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.285 2007/02/21 15:12:39 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.286 2007/03/13 16:03:36 mha Exp $ -->
<chapter id="installation">
<title><![%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 dc1edae6f0b..e0123a953f5 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
--
GitLab