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.
This commit is contained in:
Magnus Hagander 2007-03-13 16:03:36 +00:00
parent f4ee82e3d3
commit be40754e91
3 changed files with 324 additions and 164 deletions

View File

@ -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>
<tip>
<para>
Using <productname>MinGW</productname> or
<productname>Cygwin</productname> is preferred. If using one of
those tool sets, see <xref linkend="installation">.
</para>
</tip>
<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>
To build everything that you can on <productname>Windows</productname>
using <productname>Microsoft Visual C++</productname>, change into the
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>
<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>
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>
</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&amp;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&amp;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>
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:&lt;libpath&gt;</> 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>

View File

@ -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>

View File

@ -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