1src/tools/msvc/README
2
3MSVC build
4==========
5
6This directory contains the tools required to build PostgreSQL using
7Microsoft Visual Studio 2005 - 2019. This builds the whole backend, not just
8the libpq frontend library. For more information, see the documentation
9chapter "Installation on Windows" and the description below.
10
11
12Notes about Visual Studio Express
13---------------------------------
14To build PostgreSQL using Visual Studio Express, the Microsoft Windows SDK
15has to be installed. Since this is not included in the product
16originally, extra steps are needed to make it work.
17
18First, download and install a supported version of the Microsoft Windows SDK
19from www.microsoft.com (v6.0 or greater).
20
21Locate the files vcprojectengine.dll.express.config and
22vcprojectengine.dll.config in the vc\vcpackages directory of
23the Visual C++ Express installation. In these files, add the paths
24to the Platform SDK to the Include, Library and Path tags. Be sure
25to add them to the beginning of the list.
26
27This should work for both GUI and commandline builds, but a restart
28may be necessary.
29
30If you are using a recent version of the Microsoft Windows SDK that includes
31the compilers and build tools you probably don't even need Visual Studio
32Express to build PostgreSQL.
33
34
35Structure of the build tools
36----------------------------
37The tools for building PostgreSQL using Microsoft Visual Studio currently
38consist of the following files:
39
40- Configuration files -
41config_default.pl      default configuration arguments
42
43A typical build environment has two more files, buildenv.pl and config.pl
44that contain the user's build environment settings and configuration
45arguments.
46
47
48- User tools -
49build.pl               tool to build the binaries
50builddoc.pl            tool to build the docs
51clean.bat              batch file for cleaning up generated files
52install.pl             tool to install the generated files
53mkvcbuild.pl           tool to generate the Visual Studio build files
54vcregress.pl           tool to run the regression tests
55
56
57- Internal tools -
58gendef.pl              internal tool to generate .DEF files
59pgbison.pl             internal tool to process .y files using bison
60pgflex.pl              internal tool to process .l files using flex
61
62Many of those .pl files also have a corresponding .bat-wrapper that doesn't
63contain any additional logic.
64
65
66- Internal modules -
67Install.pm             module containing the install logic
68Mkvcbuild.pm           module containing the code to generate the Visual
69                       Studio build (project/solution) files
70MSBuildProject.pm      module containing the code to generate MSBuild based
71                       project files (Visual Studio 2010 or greater)
72Project.pm             module containing the common code to generate the
73                       Visual Studio project files. Also provides the
74                       common interface of all project file generators
75Solution.pm            module containing the code to generate the Visual
76                       Studio solution files.
77VCBuildProject.pm      module containing the code to generate VCBuild based
78                       project files (Visual Studio 2005/2008)
79VSObjectFactory.pm     factory module providing the code to create the
80                       appropriate project/solution files for the current
81                       environment
82
83
84Description of the internals of the Visual Studio build process
85---------------------------------------------------------------
86By typing 'build' the user starts the build.bat wrapper which simply passes
87it's arguments to build.pl.
88In build.pl the user's buildenv.pl is used to set up the build environment
89(i. e. path to bison and flex). In addition his config.pl file is merged into
90config_default.pl to create the configuration arguments.
91These configuration arguments are passed over to Mkvcbuild::mkvcbuild
92(Mkvcbuild.pm) which creates the Visual Studio project and solution files.
93It does this by using VSObjectFactory::CreateSolution to create an object
94implementing the Solution interface (this could be either a VS2005Solution,
95a VS2008Solution, a VS2010Solution or a VS2012Solution or a VS2013Solution,
96or a VS2015Solution or a VS2017Solution or a VS2019Solution, all in
97Solution.pm, depending on the user's build environment) and adding objects
98implementing the corresponding Project interface (VC2005Project or
99VC2008Project from VCBuildProject.pm or VC2010Project or VC2012Project or
100VC2013Project or VC2015Project or VC2017Project or VC2019Project from
101MSBuildProject.pm) to it.
102When Solution::Save is called, the implementations of Solution and Project
103save their content in the appropriate format.
104The final step of starting the appropriate build program (msbuild or vcbuild)
105is performed in build.pl again.
106