Debian Codegraph @

doc/src/sgml/installation.sgml

raw
1 <!-- doc/src/sgml/installation.sgml -->
2
3 <chapter id="installation">
4 <title>Installation from Source Code</title>
5
6 <indexterm zone="installation">
7 <primary>installation</primary>
8 </indexterm>
9
10 <para>
11 This chapter describes the installation of
12 <productname>PostgreSQL</productname> using the source code
13 distribution. If you are installing a pre-packaged distribution,
14 such as an RPM or Debian package, ignore this chapter
15 and see <xref linkend="install-binaries" /> instead.
16 </para>
17
18 <sect1 id="install-requirements">
19 <title>Requirements</title>
20
21 <para>
22 In general, a modern Unix-compatible platform should be able to run
23 <productname>PostgreSQL</productname>.
24 The platforms that had received specific testing at the
25 time of release are described in <xref linkend="supported-platforms"/>
26 below.
27 </para>
28
29 <para>
30 The following software packages are required for building
31 <productname>PostgreSQL</productname>:
32
33 <itemizedlist>
34 <listitem>
35 <para>
36 <indexterm>
37 <primary>make</primary>
38 </indexterm>
39
40 <acronym>GNU</acronym> <application>make</application> version 3.81 or newer is required; other
41 <application>make</application> programs or older <acronym>GNU</acronym> <application>make</application> versions will <emphasis>not</emphasis> work.
42 (<acronym>GNU</acronym> <application>make</application> is sometimes installed under
43 the name <filename>gmake</filename>.) To test for <acronym>GNU</acronym>
44 <application>make</application> enter:
45 <screen>
46 <userinput>make --version</userinput>
47 </screen>
48 </para>
49 </listitem>
50
51 <listitem>
52 <para>
53 <indexterm>
54 <primary>Meson</primary>
55 </indexterm>
56
57 Alternatively, <productname>PostgreSQL</productname> can be built using
58 <ulink url="https://mesonbuild.com/">Meson</ulink>. This is the only
59 option for building <productname>PostgreSQL</productname> on Windows
60 using <productname>Visual Studio</productname>. For other platforms,
61 using <application>Meson</application> is currently experimental. If
62 you choose to use <application>Meson</application>, then you don't need
63 <acronym>GNU</acronym> <application>make</application>, but the other
64 requirements below still apply.
65 </para>
66
67 <para>
68 The minimum required version of <application>Meson</application> is 0.54.
69 </para>
70 </listitem>
71
72 <listitem>
73 <para>
74 You need an <acronym>ISO</acronym>/<acronym>ANSI</acronym> C compiler (at least
75 C99-compliant). Recent
76 versions of <productname>GCC</productname> are recommended, but
77 <productname>PostgreSQL</productname> is known to build using a wide variety
78 of compilers from different vendors.
79 </para>
80 </listitem>
81
82 <listitem>
83 <para>
84 <application>tar</application> is required to unpack the source
85 distribution, in addition to either
86 <application>gzip</application> or <application>bzip2</application>.
87 </para>
88 </listitem>
89
90 <listitem>
91 <para>
92 <indexterm>
93 <primary>flex</primary>
94 </indexterm>
95 <indexterm>
96 <primary>lex</primary>
97 </indexterm>
98 <indexterm>
99 <primary>bison</primary>
100 </indexterm>
101 <indexterm>
102 <primary>yacc</primary>
103 </indexterm>
104
105 <application>Flex</application> and <application>Bison</application> are
106 required. Other <application>lex</application> and
107 <application>yacc</application> programs cannot be used.
108 <application>Bison</application> needs to be at least version 2.3.
109 </para>
110 </listitem>
111
112 <listitem>
113 <para>
114 <indexterm>
115 <primary>perl</primary>
116 </indexterm>
117
118 <application>Perl</application> 5.14 or later is needed during the build
119 process and to run some test suites. (This requirement is separate from
120 the requirements for building <application>PL/Perl</application>; see
121 below.)
122 </para>
123 </listitem>
124
125 <listitem>
126 <para>
127 <indexterm>
128 <primary>readline</primary>
129 </indexterm>
130 <indexterm>
131 <primary>libedit</primary>
132 </indexterm>
133
134 The <acronym>GNU</acronym> <productname>Readline</productname> library is used by
135 default. It allows <application>psql</application> (the
136 PostgreSQL command line SQL interpreter) to remember each
137 command you type, and allows you to use arrow keys to recall and
138 edit previous commands. This is very helpful and is strongly
139 recommended. If you don't want to use it then you must specify
140 the <option>--without-readline</option> option to
141 <filename>configure</filename>. As an alternative, you can often use the
142 BSD-licensed <filename>libedit</filename> library, originally
143 developed on <productname>NetBSD</productname>. The
144 <filename>libedit</filename> library is
145 GNU <productname>Readline</productname>-compatible and is used if
146 <filename>libreadline</filename> is not found, or if
147 <option>--with-libedit-preferred</option> is used as an
148 option to <filename>configure</filename>. If you are using a package-based
149 Linux distribution, be aware that you need both the
150 <literal>readline</literal> and <literal>readline-devel</literal> packages, if
151 those are separate in your distribution.
152 </para>
153 </listitem>
154
155 <listitem>
156 <para>
157 <indexterm>
158 <primary>zlib</primary>
159 </indexterm>
160
161 The <productname>zlib</productname> compression library is
162 used by default. If you don't want to use it then you must
163 specify the <option>--without-zlib</option> option to
164 <filename>configure</filename>. Using this option disables
165 support for compressed archives in <application>pg_dump</application> and
166 <application>pg_restore</application>.
167 </para>
168 </listitem>
169
170 <listitem>
171 <para>
172 The ICU library is used by default. If you don't want to use it then you must specify the <option>--without-icu</option> option to <filename>configure</filename>. Using this option disables support for ICU collation features (see <xref linkend="collation"/>).
173 </para>
174 <para>
175 ICU support requires the <productname>ICU4C</productname> package to be
176 installed. The minimum required version of
177 <productname>ICU4C</productname> is currently 4.2.
178 </para>
179
180 <para>
181 By default,
182 <productname>pkg-config</productname><indexterm><primary>pkg-config</primary></indexterm>
183 will be used to find the required compilation options. This is
184 supported for <productname>ICU4C</productname> version 4.6 and later.
185 For older versions, or if <productname>pkg-config</productname> is not
186 available, the variables <envar>ICU_CFLAGS</envar> and
187 <envar>ICU_LIBS</envar> can be specified to
188 <filename>configure</filename>, like in this example:
189 <programlisting>
190 ./configure ... ICU_CFLAGS='-I/some/where/include' ICU_LIBS='-L/some/where/lib -licui18n -licuuc -licudata'
191 </programlisting>
192 (If <productname>ICU4C</productname> is in the default search path
193 for the compiler, then you still need to specify nonempty strings in
194 order to avoid use of <productname>pkg-config</productname>, for
195 example, <literal>ICU_CFLAGS=' '</literal>.)
196 </para>
197 </listitem>
198 </itemizedlist>
199 </para>
200
201 <para>
202 The following packages are optional. They are not required in the
203 default configuration, but they are needed when certain build
204 options are enabled, as explained below:
205
206 <itemizedlist>
207 <listitem>
208 <para>
209 To build the server programming language
210 <application>PL/Perl</application> you need a full
211 <productname>Perl</productname> installation, including the
212 <filename>libperl</filename> library and the header files.
213 The minimum required version is <productname>Perl</productname> 5.14.
214 Since <application>PL/Perl</application> will be a shared
215 library, the <indexterm><primary>libperl</primary></indexterm>
216 <filename>libperl</filename> library must be a shared library
217 also on most platforms. This appears to be the default in
218 recent <productname>Perl</productname> versions, but it was not
219 in earlier versions, and in any case it is the choice of whomever
220 installed Perl at your site. <filename>configure</filename> will fail
221 if building <application>PL/Perl</application> is selected but it cannot
222 find a shared <filename>libperl</filename>. In that case, you will have
223 to rebuild and install <productname>Perl</productname> manually to be
224 able to build <application>PL/Perl</application>. During the
225 configuration process for <productname>Perl</productname>, request a
226 shared library.
227 </para>
228
229 <para>
230 If you intend to make more than incidental use of
231 <application>PL/Perl</application>, you should ensure that the
232 <productname>Perl</productname> installation was built with the
233 <literal>usemultiplicity</literal> option enabled (<literal>perl -V</literal>
234 will show whether this is the case).
235 </para>
236 </listitem>
237
238 <listitem>
239 <para>
240 To build the <application>PL/Python</application> server programming
241 language, you need a <productname>Python</productname>
242 installation with the header files and
243 the <application>sysconfig</application> module. The minimum
244 supported version is <productname>Python</productname> 3.6.8.
245 </para>
246
247 <para>
248 Since <application>PL/Python</application> will be a shared
249 library, the <indexterm><primary>libpython</primary></indexterm>
250 <filename>libpython</filename> library must be a shared library
251 also on most platforms. This is not the case in a default
252 <productname>Python</productname> installation built from source, but a
253 shared library is available in many operating system
254 distributions. <filename>configure</filename> will fail if
255 building <application>PL/Python</application> is selected but it cannot
256 find a shared <filename>libpython</filename>. That might mean that you
257 either have to install additional packages or rebuild (part of) your
258 <productname>Python</productname> installation to provide this shared
259 library. When building from source, run <productname>Python</productname>'s
260 configure with the <literal>--enable-shared</literal> flag.
261 </para>
262 </listitem>
263
264 <listitem>
265 <para>
266 To build the <application>PL/Tcl</application>
267 procedural language, you of course need a <productname>Tcl</productname>
268 installation. The minimum required version is
269 <productname>Tcl</productname> 8.4.
270 </para>
271 </listitem>
272
273 <listitem>
274 <para>
275 To enable Native Language Support (<acronym>NLS</acronym>), that
276 is, the ability to display a program's messages in a language
277 other than English, you need an implementation of the
278 <application>Gettext</application> <acronym>API</acronym>. Some operating
279 systems have this built-in (e.g., <systemitem
280 class="osname">Linux</systemitem>, <systemitem class="osname">NetBSD</systemitem>,
281 <systemitem class="osname">Solaris</systemitem>), for other systems you
282 can download an add-on package from <ulink
283 url="https://www.gnu.org/software/gettext/"></ulink>.
284 If you are using the <application>Gettext</application> implementation in
285 the <acronym>GNU</acronym> C library, then you will additionally
286 need the <productname>GNU Gettext</productname> package for some
287 utility programs. For any of the other implementations you will
288 not need it.
289 </para>
290 </listitem>
291
292 <listitem>
293 <para>
294 You need <productname>OpenSSL</productname>, if you want to support
295 encrypted client connections. <productname>OpenSSL</productname> is
296 also required for random number generation on platforms that do not
297 have <filename>/dev/urandom</filename> (except Windows). The minimum
298 required version is 1.1.1.
299 </para>
300 <para>
301 Additionally, <productname>LibreSSL</productname> is supported using the
302 <productname>OpenSSL</productname> compatibility layer. The minimum
303 required version is 3.4 (from <systemitem class="osname">OpenBSD</systemitem>
304 version 7.0).
305 </para>
306 </listitem>
307
308 <listitem>
309 <para>
310 You need <application>MIT Kerberos</application> (for GSSAPI),
311 <productname>OpenLDAP</productname>, and/or <application>PAM</application>,
312 if you want to support authentication using those services.
313 </para>
314 </listitem>
315
316 <listitem>
317 <para>
318 You need <productname>Curl</productname> to build an optional module
319 which implements the <link linkend="libpq-oauth">OAuth Device
320 Authorization flow</link> for client applications.
321 </para>
322 </listitem>
323
324 <listitem>
325 <para>
326 You need <productname>LZ4</productname>, if you want to support
327 compression of data with that method; see
328 <xref linkend="guc-default-toast-compression"/> and
329 <xref linkend="guc-wal-compression"/>.
330 </para>
331 </listitem>
332
333 <listitem>
334 <para>
335 You need <productname>Zstandard</productname>, if you want to support
336 compression of data with that method; see
337 <xref linkend="guc-wal-compression"/>.
338 The minimum required version is 1.4.0.
339 </para>
340 </listitem>
341
342 <listitem>
343 <para>
344 To build the <productname>PostgreSQL</productname> documentation,
345 there is a separate set of requirements; see
346 <xref linkend="docguide-toolsets"/>.
347 </para>
348 </listitem>
349 </itemizedlist>
350 </para>
351
352 <para>
353 If you need to get a <acronym>GNU</acronym> package, you can find
354 it at your local <acronym>GNU</acronym> mirror site (see <ulink
355 url="https://www.gnu.org/prep/ftp"></ulink>
356 for a list) or at <ulink
357 url="ftp://ftp.gnu.org/gnu/"></ulink>.
358 </para>
359 </sect1>
360
361 <sect1 id="install-getsource">
362 <title>Getting the Source</title>
363
364 <para>
365 The <productname>PostgreSQL</productname> source code for released versions
366 can be obtained from the download section of our website:
367 <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
368 Download the
369 <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
370 or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
371 file you're interested in, then unpack it:
372 <screen>
373 <userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
374 </screen>
375 This will create a directory
376 <filename>postgresql-<replaceable>version</replaceable></filename> under
377 the current directory with the <productname>PostgreSQL</productname> sources.
378 Change into that directory for the rest of the installation procedure.
379 </para>
380
381 <para>
382 Alternatively, you can use the Git version control system; see
383 <xref linkend="git"/> for more information.
384 </para>
385 </sect1>
386
387 <sect1 id="install-make">
388 <title>Building and Installation with Autoconf and Make</title>
389
390 <sect2 id="install-short-make">
391 <title>Short Version</title>
392
393 <para>
394 <synopsis>
395 ./configure
396 make
397 su
398 make install
399 adduser postgres
400 mkdir -p /usr/local/pgsql/data
401 chown postgres /usr/local/pgsql/data
402 su - postgres
403 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
404 /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
405 /usr/local/pgsql/bin/createdb test
406 /usr/local/pgsql/bin/psql test
407 </synopsis>
408 The long version is the rest of this
409 <phrase>section</phrase>.
410 </para>
411 </sect2>
412
413
414 <sect2 id="install-procedure-make">
415 <title>Installation Procedure</title>
416
417 <procedure>
418
419 <step id="configure">
420 <title>Configuration</title>
421
422 <indexterm zone="configure">
423 <primary>configure</primary>
424 </indexterm>
425
426 <para>
427 The first step of the installation procedure is to configure the
428 source tree for your system and choose the options you would like.
429 This is done by running the <filename>configure</filename> script. For a
430 default installation simply enter:
431 <screen>
432 <userinput>./configure</userinput>
433 </screen>
434 This script will run a number of tests to determine values for various
435 system dependent variables and detect any quirks of your
436 operating system, and finally will create several files in the
437 build tree to record what it found.
438 </para>
439
440 <para>
441 You can also run <filename>configure</filename> in a directory outside
442 the source tree, and then build there, if you want to keep the build
443 directory separate from the original source files. This procedure is
444 called a
445 <indexterm><primary>VPATH</primary></indexterm><firstterm>VPATH</firstterm>
446 build. Here's how:
447 <screen>
448 <userinput>mkdir build_dir</userinput>
449 <userinput>cd build_dir</userinput>
450 <userinput>/path/to/source/tree/configure [options go here]</userinput>
451 <userinput>make</userinput>
452 </screen>
453 </para>
454
455 <para>
456 The default configuration will build the server and utilities, as
457 well as all client applications and interfaces that require only a
458 C compiler. All files will be installed under
459 <filename>/usr/local/pgsql</filename> by default.
460 </para>
461
462 <para>
463 You can customize the build and installation process by supplying one
464 or more command line options to <filename>configure</filename>.
465 Typically you would customize the install location, or the set of
466 optional features that are built. <filename>configure</filename>
467 has a large number of options, which are described in
468 <xref linkend="configure-options"/>.
469 </para>
470
471 <para>
472 Also, <filename>configure</filename> responds to certain environment
473 variables, as described in <xref linkend="configure-envvars"/>.
474 These provide additional ways to customize the configuration.
475 </para>
476 </step>
477
478 <step id="build">
479 <title>Build</title>
480
481 <para>
482 To start the build, type either of:
483 <screen>
484 <userinput>make</userinput>
485 <userinput>make all</userinput>
486 </screen>
487 (Remember to use <acronym>GNU</acronym> <application>make</application>.)
488 The build will take a few minutes depending on your
489 hardware.
490 </para>
491
492 <para>
493 If you want to build everything that can be built, including the
494 documentation (HTML and man pages), and the additional modules
495 (<filename>contrib</filename>), type instead:
496 <screen>
497 <userinput>make world</userinput>
498 </screen>
499 </para>
500
501 <para>
502 If you want to build everything that can be built, including the
503 additional modules (<filename>contrib</filename>), but without
504 the documentation, type instead:
505 <screen>
506 <userinput>make world-bin</userinput>
507 </screen>
508 </para>
509
510 <para>
511 If you want to invoke the build from another makefile rather than
512 manually, you must unset <varname>MAKELEVEL</varname> or set it to zero,
513 for instance like this:
514 <programlisting>
515 build-postgresql:
516 $(MAKE) -C postgresql MAKELEVEL=0 all
517 </programlisting>
518 Failure to do that can lead to strange error messages, typically about
519 missing header files.
520 </para>
521 </step>
522
523 <step>
524 <title>Regression Tests</title>
525
526 <indexterm>
527 <primary>regression test</primary>
528 </indexterm>
529
530 <para>
531 If you want to test the newly built server before you install it,
532 you can run the regression tests at this point. The regression
533 tests are a test suite to verify that <productname>PostgreSQL</productname>
534 runs on your machine in the way the developers expected it
535 to. Type:
536 <screen>
537 <userinput>make check</userinput>
538 </screen>
539 (This won't work as root; do it as an unprivileged user.)
540 See <xref linkend="regress"/> for
541 detailed information about interpreting the test results. You can
542 repeat this test at any later time by issuing the same command.
543 </para>
544 </step>
545
546 <step id="install">
547 <title>Installing the Files</title>
548
549 <note>
550 <para>
551 If you are upgrading an existing system be sure to read
552 <xref linkend="upgrading"/>,
553 which has instructions about upgrading a
554 cluster.
555 </para>
556 </note>
557
558 <para>
559 To install <productname>PostgreSQL</productname> enter:
560 <screen>
561 <userinput>make install</userinput>
562 </screen>
563 This will install files into the directories that were specified
564 in <xref linkend="configure"/>. Make sure that you have appropriate
565 permissions to write into that area. Normally you need to do this
566 step as root. Alternatively, you can create the target
567 directories in advance and arrange for appropriate permissions to
568 be granted.
569 </para>
570
571 <para>
572 To install the documentation (HTML and man pages), enter:
573 <screen>
574 <userinput>make install-docs</userinput>
575 </screen>
576 </para>
577
578 <para>
579 If you built the world above, type instead:
580 <screen>
581 <userinput>make install-world</userinput>
582 </screen>
583 This also installs the documentation.
584 </para>
585
586 <para>
587 If you built the world without the documentation above, type instead:
588 <screen>
589 <userinput>make install-world-bin</userinput>
590 </screen>
591 </para>
592
593 <para>
594 You can use <literal>make install-strip</literal> instead of
595 <literal>make install</literal> to strip the executable files and
596 libraries as they are installed. This will save some space. If
597 you built with debugging support, stripping will effectively
598 remove the debugging support, so it should only be done if
599 debugging is no longer needed. <literal>install-strip</literal>
600 tries to do a reasonable job saving space, but it does not have
601 perfect knowledge of how to strip every unneeded byte from an
602 executable file, so if you want to save all the disk space you
603 possibly can, you will have to do manual work.
604 </para>
605
606 <para>
607 The standard installation provides all the header files needed for client
608 application development as well as for server-side program
609 development, such as custom functions or data types written in C.
610 </para>
611
612 <formalpara>
613 <title>Client-only installation:</title>
614 <para>
615 If you want to install only the client applications and
616 interface libraries, then you can use these commands:
617 <screen>
618 <userinput>make -C src/bin install</userinput>
619 <userinput>make -C src/include install</userinput>
620 <userinput>make -C src/interfaces install</userinput>
621 <userinput>make -C doc install</userinput>
622 </screen>
623 <filename>src/bin</filename> has a few binaries for server-only use,
624 but they are small.
625 </para>
626 </formalpara>
627 </step>
628 </procedure>
629
630 <formalpara>
631 <title>Uninstallation:</title>
632 <para>
633 To undo the installation use the command <command>make
634 uninstall</command>. However, this will not remove any created directories.
635 </para>
636 </formalpara>
637
638 <formalpara>
639 <title>Cleaning:</title>
640
641 <para>
642 After the installation you can free disk space by removing the built
643 files from the source tree with the command <command>make
644 clean</command>. This will preserve the files made by the <command>configure</command>
645 program, so that you can rebuild everything with <command>make</command>
646 later on. To reset the source tree to the state in which it was
647 distributed, use <command>make distclean</command>. If you are going to
648 build for several platforms within the same source tree you must do
649 this and re-configure for each platform. (Alternatively, use
650 a separate build tree for each platform, so that the source tree
651 remains unmodified.)
652 </para>
653 </formalpara>
654
655 <para>
656 If you perform a build and then discover that your <command>configure</command>
657 options were wrong, or if you change anything that <command>configure</command>
658 investigates (for example, software upgrades), then it's a good
659 idea to do <command>make distclean</command> before reconfiguring and
660 rebuilding. Without this, your changes in configuration choices
661 might not propagate everywhere they need to.
662 </para>
663 </sect2>
664
665 <sect2 id="configure-options">
666 <title><filename>configure</filename> Options</title>
667
668 <indexterm zone="configure-options">
669 <primary>configure options</primary>
670 </indexterm>
671
672 <para>
673 <command>configure</command>'s command line options are explained below.
674 This list is not exhaustive (use <literal>./configure --help</literal>
675 to get one that is). The options not covered here are meant for
676 advanced use-cases such as cross-compilation, and are documented in
677 the standard Autoconf documentation.
678 </para>
679
680 <sect3 id="configure-options-locations">
681 <title>Installation Locations</title>
682
683 <para>
684 These options control where <literal>make install</literal> will put
685 the files. The <option>--prefix</option> option is sufficient for
686 most cases. If you have special needs, you can customize the
687 installation subdirectories with the other options described in this
688 section. Beware however that changing the relative locations of the
689 different subdirectories may render the installation non-relocatable,
690 meaning you won't be able to move it after installation.
691 (The <literal>man</literal> and <literal>doc</literal> locations are
692 not affected by this restriction.) For relocatable installs, you
693 might want to use the <literal>--disable-rpath</literal> option
694 described later.
695 </para>
696
697 <variablelist>
698 <varlistentry id="configure-option-prefix">
699 <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
700 <listitem>
701 <para>
702 Install all files under the directory <replaceable>PREFIX</replaceable>
703 instead of <filename>/usr/local/pgsql</filename>. The actual
704 files will be installed into various subdirectories; no files
705 will ever be installed directly into the
706 <replaceable>PREFIX</replaceable> directory.
707 </para>
708 </listitem>
709 </varlistentry>
710
711 <varlistentry id="configure-option-exec-prefix">
712 <term><option>--exec-prefix=<replaceable>EXEC-PREFIX</replaceable></option></term>
713 <listitem>
714 <para>
715 You can install architecture-dependent files under a
716 different prefix, <replaceable>EXEC-PREFIX</replaceable>, than what
717 <replaceable>PREFIX</replaceable> was set to. This can be useful to
718 share architecture-independent files between hosts. If you
719 omit this, then <replaceable>EXEC-PREFIX</replaceable> is set equal to
720 <replaceable>PREFIX</replaceable> and both architecture-dependent and
721 independent files will be installed under the same tree,
722 which is probably what you want.
723 </para>
724 </listitem>
725 </varlistentry>
726
727 <varlistentry id="configure-option-bindir">
728 <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
729 <listitem>
730 <para>
731 Specifies the directory for executable programs. The default
732 is <filename><replaceable>EXEC-PREFIX</replaceable>/bin</filename>, which
733 normally means <filename>/usr/local/pgsql/bin</filename>.
734 </para>
735 </listitem>
736 </varlistentry>
737
738 <varlistentry id="configure-option-sysconfdir">
739 <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
740 <listitem>
741 <para>
742 Sets the directory for various configuration files,
743 <filename><replaceable>PREFIX</replaceable>/etc</filename> by default.
744 </para>
745 </listitem>
746 </varlistentry>
747
748 <varlistentry id="configure-option-libdir">
749 <term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
750 <listitem>
751 <para>
752 Sets the location to install libraries and dynamically loadable
753 modules. The default is
754 <filename><replaceable>EXEC-PREFIX</replaceable>/lib</filename>.
755 </para>
756 </listitem>
757 </varlistentry>
758
759 <varlistentry id="configure-option-includedir">
760 <term><option>--includedir=<replaceable>DIRECTORY</replaceable></option></term>
761 <listitem>
762 <para>
763 Sets the directory for installing C and C++ header files. The
764 default is <filename><replaceable>PREFIX</replaceable>/include</filename>.
765 </para>
766 </listitem>
767 </varlistentry>
768
769 <varlistentry id="configure-option-datarootdir">
770 <term><option>--datarootdir=<replaceable>DIRECTORY</replaceable></option></term>
771 <listitem>
772 <para>
773 Sets the root directory for various types of read-only data
774 files. This only sets the default for some of the following
775 options. The default is
776 <filename><replaceable>PREFIX</replaceable>/share</filename>.
777 </para>
778 </listitem>
779 </varlistentry>
780
781 <varlistentry id="configure-option-datadir">
782 <term><option>--datadir=<replaceable>DIRECTORY</replaceable></option></term>
783 <listitem>
784 <para>
785 Sets the directory for read-only data files used by the
786 installed programs. The default is
787 <filename><replaceable>DATAROOTDIR</replaceable></filename>. Note that this has
788 nothing to do with where your database files will be placed.
789 </para>
790 </listitem>
791 </varlistentry>
792
793 <varlistentry id="configure-option-localedir">
794 <term><option>--localedir=<replaceable>DIRECTORY</replaceable></option></term>
795 <listitem>
796 <para>
797 Sets the directory for installing locale data, in particular
798 message translation catalog files. The default is
799 <filename><replaceable>DATAROOTDIR</replaceable>/locale</filename>.
800 </para>
801 </listitem>
802 </varlistentry>
803
804 <varlistentry id="configure-option-mandir">
805 <term><option>--mandir=<replaceable>DIRECTORY</replaceable></option></term>
806 <listitem>
807 <para>
808 The man pages that come with <productname>PostgreSQL</productname> will be installed under
809 this directory, in their respective
810 <filename>man<replaceable>x</replaceable></filename> subdirectories.
811 The default is <filename><replaceable>DATAROOTDIR</replaceable>/man</filename>.
812 </para>
813 </listitem>
814 </varlistentry>
815
816 <varlistentry id="configure-option-docdir">
817 <term><option>--docdir=<replaceable>DIRECTORY</replaceable></option></term>
818 <listitem>
819 <para>
820 Sets the root directory for installing documentation files,
821 except <quote>man</quote> pages. This only sets the default for
822 the following options. The default value for this option is
823 <filename><replaceable>DATAROOTDIR</replaceable>/doc/postgresql</filename>.
824 </para>
825 </listitem>
826 </varlistentry>
827
828 <varlistentry id="configure-option-htmldir">
829 <term><option>--htmldir=<replaceable>DIRECTORY</replaceable></option></term>
830 <listitem>
831 <para>
832 The HTML-formatted documentation for
833 <productname>PostgreSQL</productname> will be installed under
834 this directory. The default is
835 <filename><replaceable>DATAROOTDIR</replaceable></filename>.
836 </para>
837 </listitem>
838 </varlistentry>
839 </variablelist>
840
841 <note>
842 <para>
843 Care has been taken to make it possible to install
844 <productname>PostgreSQL</productname> into shared installation locations
845 (such as <filename>/usr/local/include</filename>) without
846 interfering with the namespace of the rest of the system. First,
847 the string <quote><literal>/postgresql</literal></quote> is
848 automatically appended to <varname>datadir</varname>,
849 <varname>sysconfdir</varname>, and <varname>docdir</varname>,
850 unless the fully expanded directory name already contains the
851 string <quote><literal>postgres</literal></quote> or
852 <quote><literal>pgsql</literal></quote>. For example, if you choose
853 <filename>/usr/local</filename> as prefix, the documentation will
854 be installed in <filename>/usr/local/doc/postgresql</filename>,
855 but if the prefix is <filename>/opt/postgres</filename>, then it
856 will be in <filename>/opt/postgres/doc</filename>. The public C
857 header files of the client interfaces are installed into
858 <varname>includedir</varname> and are namespace-clean. The
859 internal header files and the server header files are installed
860 into private directories under <varname>includedir</varname>. See
861 the documentation of each interface for information about how to
862 access its header files. Finally, a private subdirectory will
863 also be created, if appropriate, under <varname>libdir</varname>
864 for dynamically loadable modules.
865 </para>
866 </note>
867
868 </sect3>
869
870 <sect3 id="configure-options-features">
871 <title><productname>PostgreSQL</productname> Features</title>
872
873 <para>
874 The options described in this section enable building of
875 various <productname>PostgreSQL</productname> features that are not
876 built by default. Most of these are non-default only because they
877 require additional software, as described in
878 <xref linkend="install-requirements"/>.
879 </para>
880
881 <variablelist>
882
883 <varlistentry id="configure-option-enable-nls">
884 <term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
885 <listitem>
886 <para>
887 Enables Native Language Support (<acronym>NLS</acronym>),
888 that is, the ability to display a program's messages in a
889 language other than English.
890 <replaceable>LANGUAGES</replaceable> is an optional space-separated
891 list of codes of the languages that you want supported, for
892 example <literal>--enable-nls='de fr'</literal>. (The intersection
893 between your list and the set of actually provided
894 translations will be computed automatically.) If you do not
895 specify a list, then all available translations are
896 installed.
897 </para>
898
899 <para>
900 To use this option, you will need an implementation of the
901 <application>Gettext</application> API.
902 </para>
903 </listitem>
904 </varlistentry>
905
906 <varlistentry id="configure-option-with-perl">
907 <term><option>--with-perl</option></term>
908 <listitem>
909 <para>
910 Build the <application>PL/Perl</application> server-side language.
911 </para>
912 </listitem>
913 </varlistentry>
914
915 <varlistentry id="configure-option-with-python">
916 <term><option>--with-python</option></term>
917 <listitem>
918 <para>
919 Build the <application>PL/Python</application> server-side language.
920 </para>
921 </listitem>
922 </varlistentry>
923
924 <varlistentry id="configure-option-with-tcl">
925 <term><option>--with-tcl</option></term>
926 <listitem>
927 <para>
928 Build the <application>PL/Tcl</application> server-side language.
929 </para>
930 </listitem>
931 </varlistentry>
932
933 <varlistentry id="configure-option-with-tclconfig">
934 <term><option>--with-tclconfig=<replaceable>DIRECTORY</replaceable></option></term>
935 <listitem>
936 <para>
937 Tcl installs the file <filename>tclConfig.sh</filename>, which
938 contains configuration information needed to build modules
939 interfacing to Tcl. This file is normally found automatically
940 at a well-known location, but if you want to use a different
941 version of Tcl you can specify the directory in which to look
942 for <filename>tclConfig.sh</filename>.
943 </para>
944 </listitem>
945 </varlistentry>
946
947 <varlistentry id="configure-with-llvm">
948 <term><option>--with-llvm</option></term>
949 <listitem>
950 <para>
951 Build with support for <productname>LLVM</productname> based
952 <acronym>JIT</acronym> compilation (see <xref linkend="jit"/>). This
953 requires the <productname>LLVM</productname> library to be installed.
954 The minimum required version of <productname>LLVM</productname> is
955 currently 14.
956 </para>
957 <para>
958 <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
959 will be used to find the required compilation options.
960 <command>llvm-config</command> will be searched for in your
961 <envar>PATH</envar>. If that would not yield the desired program,
962 use <envar>LLVM_CONFIG</envar> to specify a path to the correct
963 <command>llvm-config</command>. For example
964 <programlisting>
965 ./configure ... --with-llvm LLVM_CONFIG='/path/to/llvm/bin/llvm-config'
966 </programlisting>
967 </para>
968
969 <para>
970 <productname>LLVM</productname> support requires a compatible
971 <command>clang</command> compiler (specified, if necessary, using the
972 <envar>CLANG</envar> environment variable), and a working C++
973 compiler (specified, if necessary, using the <envar>CXX</envar>
974 environment variable).
975 </para>
976 </listitem>
977 </varlistentry>
978
979 <varlistentry id="configure-option-with-lz4">
980 <term><option>--with-lz4</option></term>
981 <listitem>
982 <para>
983 Build with <productname>LZ4</productname> compression support.
984 </para>
985 </listitem>
986 </varlistentry>
987
988 <varlistentry id="configure-option-with-zstd">
989 <term><option>--with-zstd</option></term>
990 <listitem>
991 <para>
992 Build with <productname>Zstandard</productname> compression support.
993 </para>
994 </listitem>
995 </varlistentry>
996
997 <varlistentry id="configure-option-with-ssl">
998 <term><option>--with-ssl=<replaceable>LIBRARY</replaceable></option>
999 <indexterm>
1000 <primary>OpenSSL</primary>
1001 <seealso>SSL</seealso>
1002 </indexterm>
1003 </term>
1004 <listitem>
1005 <para>
1006 Build with support for <acronym>SSL</acronym> (encrypted)
1007 connections. The only <replaceable>LIBRARY</replaceable>
1008 supported is <option>openssl</option>, which is used for both
1009 <productname>OpenSSL</productname>
1010 and <productname>LibreSSL</productname>. This requires the
1011 <productname>OpenSSL</productname> package to be installed.
1012 <filename>configure</filename> will check for the required
1013 header files and libraries to make sure that your
1014 <productname>OpenSSL</productname> installation is sufficient
1015 before proceeding.
1016 </para>
1017 </listitem>
1018 </varlistentry>
1019
1020 <varlistentry id="configure-option-with-openssl">
1021 <term><option>--with-openssl</option></term>
1022 <listitem>
1023 <para>
1024 Obsolete equivalent of <literal>--with-ssl=openssl</literal>.
1025 </para>
1026 </listitem>
1027 </varlistentry>
1028
1029 <varlistentry id="configure-option-with-gssapi">
1030 <term><option>--with-gssapi</option></term>
1031 <listitem>
1032 <para>
1033 Build with support for GSSAPI authentication. MIT Kerberos is required
1034 to be installed for GSSAPI. On many systems, the GSSAPI system (a part
1035 of the MIT Kerberos installation) is not installed in a location
1036 that is searched by default (e.g., <filename>/usr/include</filename>,
1037 <filename>/usr/lib</filename>), so you must use the options
1038 <option>--with-includes</option> and <option>--with-libraries</option> in
1039 addition to this option. <filename>configure</filename> will check
1040 for the required header files and libraries to make sure that
1041 your GSSAPI installation is sufficient before proceeding.
1042 </para>
1043 </listitem>
1044 </varlistentry>
1045
1046 <varlistentry id="configure-option-with-ldap">
1047 <term><option>--with-ldap</option></term>
1048 <listitem>
1049 <para>
1050 Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
1051 support for authentication and connection parameter lookup (see
1052 <phrase id="install-ldap-links"><xref linkend="libpq-ldap"/> and
1053 <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
1054 this requires the <productname>OpenLDAP</productname> package to be
1055 installed. On Windows, the default <productname>WinLDAP</productname>
1056 library is used. <filename>configure</filename> will check for the required
1057 header files and libraries to make sure that your
1058 <productname>OpenLDAP</productname> installation is sufficient before
1059 proceeding.
1060 </para>
1061 </listitem>
1062 </varlistentry>
1063
1064 <varlistentry id="configure-option-with-pam">
1065 <term><option>--with-pam</option></term>
1066 <listitem>
1067 <para>
1068 Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
1069 (Pluggable Authentication Modules) support.
1070 </para>
1071 </listitem>
1072 </varlistentry>
1073
1074 <varlistentry id="configure-option-with-bsd-auth">
1075 <term><option>--with-bsd-auth</option></term>
1076 <listitem>
1077 <para>
1078 Build with BSD Authentication support.
1079 (The BSD Authentication framework is
1080 currently only available on OpenBSD.)
1081 </para>
1082 </listitem>
1083 </varlistentry>
1084
1085 <varlistentry id="configure-option-with-systemd">
1086 <term><option>--with-systemd</option></term>
1087 <listitem>
1088 <para>
1089 Build with support
1090 for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
1091 service notifications. This improves integration if the server
1092 is started under <application>systemd</application> but has no impact
1093 otherwise; see <xref linkend="server-start"/> for more
1094 information. <application>libsystemd</application> and the
1095 associated header files need to be installed to use this option.
1096 </para>
1097 </listitem>
1098 </varlistentry>
1099
1100 <varlistentry id="configure-option-with-bonjour">
1101 <term><option>--with-bonjour</option></term>
1102 <listitem>
1103 <para>
1104 Build with support for Bonjour automatic service discovery.
1105 This requires Bonjour support in your operating system.
1106 Recommended on macOS.
1107 </para>
1108 </listitem>
1109 </varlistentry>
1110
1111 <varlistentry id="configure-option-with-uuid">
1112 <term><option>--with-uuid=<replaceable>LIBRARY</replaceable></option></term>
1113 <listitem>
1114 <para>
1115 Build the <xref linkend="uuid-ossp"/> module
1116 (which provides functions to generate UUIDs), using the specified
1117 UUID library.<indexterm><primary>UUID</primary></indexterm>
1118 <replaceable>LIBRARY</replaceable> must be one of:
1119 </para>
1120 <itemizedlist>
1121 <listitem>
1122 <para>
1123 <option>bsd</option> to use the UUID functions found in FreeBSD
1124 and some other BSD-derived systems
1125 </para>
1126 </listitem>
1127 <listitem>
1128 <para>
1129 <option>e2fs</option> to use the UUID library created by
1130 the <literal>e2fsprogs</literal> project; this library is present in most
1131 Linux systems and in macOS, and can be obtained for other
1132 platforms as well
1133 </para>
1134 </listitem>
1135 <listitem>
1136 <para>
1137 <option>ossp</option> to use the <ulink
1138 url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
1139 </para>
1140 </listitem>
1141 </itemizedlist>
1142 </listitem>
1143 </varlistentry>
1144
1145 <varlistentry id="configure-option-with-ossp-uuid">
1146 <term><option>--with-ossp-uuid</option></term>
1147 <listitem>
1148 <para>
1149 Obsolete equivalent of <literal>--with-uuid=ossp</literal>.
1150 </para>
1151 </listitem>
1152 </varlistentry>
1153
1154 <varlistentry id="configure-option-with-libcurl">
1155 <term><option>--with-libcurl</option></term>
1156 <listitem>
1157 <para>
1158 Build with libcurl support for OAuth 2.0 client flows.
1159 Libcurl version 7.61.0 or later is required for this feature.
1160 Building with this will check for the required header files
1161 and libraries to make sure that your <productname>curl</productname>
1162 installation is sufficient before proceeding.
1163 </para>
1164 </listitem>
1165 </varlistentry>
1166
1167 <varlistentry id="configure-option-with-libnuma">
1168 <term><option>--with-libnuma</option></term>
1169 <listitem>
1170 <para>
1171 Build with libnuma support for basic NUMA support.
1172 Only supported on platforms for which the <productname>libnuma</productname>
1173 library is implemented.
1174 </para>
1175 </listitem>
1176 </varlistentry>
1177
1178 <varlistentry id="configure-option-with-liburing">
1179 <term><option>--with-liburing</option></term>
1180 <listitem>
1181 <para>
1182 Build with liburing, enabling io_uring support for asynchronous I/O.
1183 </para>
1184 <para>
1185 To detect the required compiler and linker options, PostgreSQL will
1186 query <command>pkg-config</command>.
1187 </para>
1188 <para>
1189 To use a liburing installation that is in an unusual location, you
1190 can set <command>pkg-config</command>-related environment
1191 variables (see its documentation).
1192 </para>
1193 </listitem>
1194 </varlistentry>
1195
1196 <varlistentry id="configure-option-with-libxml">
1197 <term><option>--with-libxml</option></term>
1198 <listitem>
1199 <para>
1200 Build with libxml2, enabling SQL/XML support. Libxml2 version 2.6.23 or
1201 later is required for this feature.
1202 </para>
1203
1204 <para>
1205 To detect the required compiler and linker options, PostgreSQL will
1206 query <command>pkg-config</command>, if that is installed and knows
1207 about libxml2. Otherwise the program <command>xml2-config</command>,
1208 which is installed by libxml2, will be used if it is found. Use
1209 of <command>pkg-config</command> is preferred, because it can deal
1210 with multi-architecture installations better.
1211 </para>
1212
1213 <para>
1214 To use a libxml2 installation that is in an unusual location, you
1215 can set <command>pkg-config</command>-related environment
1216 variables (see its documentation), or set the environment variable
1217 <envar>XML2_CONFIG</envar> to point to
1218 the <command>xml2-config</command> program belonging to the libxml2
1219 installation, or set the variables <envar>XML2_CFLAGS</envar>
1220 and <envar>XML2_LIBS</envar>. (If <command>pkg-config</command> is
1221 installed, then to override its idea of where libxml2 is you must
1222 either set <envar>XML2_CONFIG</envar> or set
1223 both <envar>XML2_CFLAGS</envar> and <envar>XML2_LIBS</envar> to
1224 nonempty strings.)
1225 </para>
1226 </listitem>
1227 </varlistentry>
1228
1229 <varlistentry id="configure-option-with-libxslt">
1230 <term><option>--with-libxslt</option></term>
1231 <listitem>
1232 <para>
1233 Build with libxslt, enabling the
1234 <xref linkend="xml2"/>
1235 module to perform XSL transformations of XML.
1236 <option>--with-libxml</option> must be specified as well.
1237 </para>
1238 </listitem>
1239 </varlistentry>
1240
1241 <varlistentry id="configure-option-with-sepgsql">
1242 <term><option>--with-selinux</option></term>
1243 <listitem>
1244 <para>
1245 Build with SElinux support, enabling the <xref linkend="sepgsql"/>
1246 extension.
1247 </para>
1248 </listitem>
1249 </varlistentry>
1250
1251 </variablelist>
1252
1253 </sect3>
1254
1255 <sect3 id="configure-options-anti-features">
1256 <title>Anti-Features</title>
1257
1258 <para>
1259 The options described in this section allow disabling
1260 certain <productname>PostgreSQL</productname> features that are built
1261 by default, but which might need to be turned off if the required
1262 software or system features are not available. Using these options is
1263 not recommended unless really necessary.
1264 </para>
1265
1266 <variablelist>
1267
1268 <varlistentry id="configure-option-without-icu">
1269 <term><option>--without-icu</option></term>
1270 <listitem>
1271 <para>
1272 Build without support for the
1273 <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
1274 library, disabling the use of ICU collation features (see <xref
1275 linkend="collation"/>).
1276 </para>
1277 </listitem>
1278 </varlistentry>
1279
1280 <varlistentry id="configure-option-without-readline">
1281 <term><option>--without-readline</option></term>
1282 <listitem>
1283 <para>
1284 Prevents use of the <application>Readline</application> library
1285 (and <application>libedit</application> as well). This option disables
1286 command-line editing and history in
1287 <application>psql</application>.
1288 </para>
1289 </listitem>
1290 </varlistentry>
1291
1292 <varlistentry id="configure-option-with-libedit-preferred">
1293 <term><option>--with-libedit-preferred</option></term>
1294 <listitem>
1295 <para>
1296 Favors the use of the BSD-licensed <application>libedit</application> library
1297 rather than GPL-licensed <application>Readline</application>. This option
1298 is significant only if you have both libraries installed; the
1299 default in that case is to use <application>Readline</application>.
1300 </para>
1301 </listitem>
1302 </varlistentry>
1303
1304 <varlistentry id="configure-option-without-zlib">
1305 <term><option>--without-zlib</option></term>
1306 <listitem>
1307 <para>
1308 <indexterm>
1309 <primary>zlib</primary>
1310 </indexterm>
1311 Prevents use of the <application>Zlib</application> library.
1312 This disables
1313 support for compressed archives in <application>pg_dump</application>
1314 and <application>pg_restore</application>.
1315 </para>
1316 </listitem>
1317 </varlistentry>
1318
1319 </variablelist>
1320
1321 </sect3>
1322
1323 <sect3 id="configure-options-build-process">
1324 <title>Build Process Details</title>
1325
1326 <variablelist>
1327
1328 <varlistentry id="configure-option-with-includes">
1329 <term><option>--with-includes=<replaceable>DIRECTORIES</replaceable></option></term>
1330 <listitem>
1331 <para>
1332 <replaceable>DIRECTORIES</replaceable> is a colon-separated list of
1333 directories that will be added to the list the compiler
1334 searches for header files. If you have optional packages
1335 (such as GNU <application>Readline</application>) installed in a non-standard
1336 location,
1337 you have to use this option and probably also the corresponding
1338 <option>--with-libraries</option> option.
1339 </para>
1340 <para>
1341 Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</literal>.
1342 </para>
1343 </listitem>
1344 </varlistentry>
1345
1346 <varlistentry id="configure-option-with-libraries">
1347 <term><option>--with-libraries=<replaceable>DIRECTORIES</replaceable></option></term>
1348 <listitem>
1349 <para>
1350 <replaceable>DIRECTORIES</replaceable> is a colon-separated list of
1351 directories to search for libraries. You will probably have
1352 to use this option (and the corresponding
1353 <option>--with-includes</option> option) if you have packages
1354 installed in non-standard locations.
1355 </para>
1356 <para>
1357 Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</literal>.
1358 </para>
1359 </listitem>
1360 </varlistentry>
1361
1362 <varlistentry id="configure-option-with-system-tzdata">
1363 <term><option>--with-system-tzdata=<replaceable>DIRECTORY</replaceable></option>
1364 <indexterm>
1365 <primary>time zone data</primary>
1366 </indexterm>
1367 </term>
1368 <listitem>
1369 <para>
1370 <productname>PostgreSQL</productname> includes its own time zone database,
1371 which it requires for date and time operations. This time zone
1372 database is in fact compatible with the IANA time zone
1373 database provided by many operating systems such as FreeBSD,
1374 Linux, and Solaris, so it would be redundant to install it again.
1375 When this option is used, the system-supplied time zone database
1376 in <replaceable>DIRECTORY</replaceable> is used instead of the one
1377 included in the PostgreSQL source distribution.
1378 <replaceable>DIRECTORY</replaceable> must be specified as an
1379 absolute path. <filename>/usr/share/zoneinfo</filename> is a
1380 likely directory on some operating systems. Note that the
1381 installation routine will not detect mismatching or erroneous time
1382 zone data. If you use this option, you are advised to run the
1383 regression tests to verify that the time zone data you have
1384 pointed to works correctly with <productname>PostgreSQL</productname>.
1385 </para>
1386
1387 <indexterm><primary>cross compilation</primary></indexterm>
1388
1389 <para>
1390 This option is mainly aimed at binary package distributors
1391 who know their target operating system well. The main
1392 advantage of using this option is that the PostgreSQL package
1393 won't need to be upgraded whenever any of the many local
1394 daylight-saving time rules change. Another advantage is that
1395 PostgreSQL can be cross-compiled more straightforwardly if the
1396 time zone database files do not need to be built during the
1397 installation.
1398 </para>
1399 </listitem>
1400 </varlistentry>
1401
1402 <varlistentry id="configure-option-with-extra-version">
1403 <term><option>--with-extra-version=<replaceable>STRING</replaceable></option></term>
1404 <listitem>
1405 <para>
1406 Append <replaceable>STRING</replaceable> to the PostgreSQL version number. You
1407 can use this, for example, to mark binaries built from unreleased Git
1408 snapshots or containing custom patches with an extra version string,
1409 such as a <command>git describe</command> identifier or a
1410 distribution package release number.
1411 </para>
1412 </listitem>
1413 </varlistentry>
1414
1415 <varlistentry id="configure-option-disable-rpath">
1416 <term><option>--disable-rpath</option></term>
1417 <listitem>
1418 <para>
1419 Do not mark <productname>PostgreSQL</productname>'s executables
1420 to indicate that they should search for shared libraries in the
1421 installation's library directory (see <option>--libdir</option>).
1422 On most platforms, this marking uses an absolute path to the
1423 library directory, so that it will be unhelpful if you relocate
1424 the installation later. However, you will then need to provide
1425 some other way for the executables to find the shared libraries.
1426 Typically this requires configuring the operating system's
1427 dynamic linker to search the library directory; see
1428 <xref linkend="install-post-shlibs"/> for more detail.
1429 </para>
1430 </listitem>
1431 </varlistentry>
1432
1433 </variablelist>
1434
1435 </sect3>
1436
1437 <sect3 id="configure-options-misc">
1438 <title>Miscellaneous</title>
1439
1440 <para>
1441 It's fairly common, particularly for test builds, to adjust the
1442 default port number with <option>--with-pgport</option>.
1443 The other options in this section are recommended only for advanced
1444 users.
1445 </para>
1446
1447 <variablelist>
1448
1449 <varlistentry id="configure-option-with-pgport">
1450 <term><option>--with-pgport=<replaceable>NUMBER</replaceable></option></term>
1451 <listitem>
1452 <para>
1453 Set <replaceable>NUMBER</replaceable> as the default port number for
1454 server and clients. The default is 5432. The port can always
1455 be changed later on, but if you specify it here then both
1456 server and clients will have the same default compiled in,
1457 which can be very convenient. Usually the only good reason
1458 to select a non-default value is if you intend to run multiple
1459 <productname>PostgreSQL</productname> servers on the same machine.
1460 </para>
1461 </listitem>
1462 </varlistentry>
1463
1464 <varlistentry id="configure-option-with-krb-srvnam">
1465 <term><option>--with-krb-srvnam=<replaceable>NAME</replaceable></option></term>
1466 <listitem>
1467 <para>
1468 The default name of the Kerberos service principal used
1469 by GSSAPI.
1470 <literal>postgres</literal> is the default. There's usually no
1471 reason to change this unless you are building for a Windows
1472 environment, in which case it must be set to upper case
1473 <literal>POSTGRES</literal>.
1474 </para>
1475 </listitem>
1476 </varlistentry>
1477
1478 <varlistentry id="configure-option-with-segsize">
1479 <term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term>
1480 <listitem>
1481 <para>
1482 Set the <firstterm>segment size</firstterm>, in gigabytes. Large tables are
1483 divided into multiple operating-system files, each of size equal
1484 to the segment size. This avoids problems with file size limits
1485 that exist on many platforms. The default segment size, 1 gigabyte,
1486 is safe on all supported platforms. If your operating system has
1487 <quote>largefile</quote> support (which most do, nowadays), you can use
1488 a larger segment size. This can be helpful to reduce the number of
1489 file descriptors consumed when working with very large tables.
1490 But be careful not to select a value larger than is supported
1491 by your platform and the file systems you intend to use. Other
1492 tools you might wish to use, such as <application>tar</application>, could
1493 also set limits on the usable file size.
1494 It is recommended, though not absolutely required, that this value
1495 be a power of 2.
1496 Note that changing this value breaks on-disk database compatibility,
1497 meaning you cannot use <command>pg_upgrade</command> to upgrade to
1498 a build with a different segment size.
1499 </para>
1500 </listitem>
1501 </varlistentry>
1502
1503 <varlistentry id="configure-option-with-blocksize">
1504 <term><option>--with-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
1505 <listitem>
1506 <para>
1507 Set the <firstterm>block size</firstterm>, in kilobytes. This is the unit
1508 of storage and I/O within tables. The default, 8 kilobytes,
1509 is suitable for most situations; but other values may be useful
1510 in special cases.
1511 The value must be a power of 2 between 1 and 32 (kilobytes).
1512 Note that changing this value breaks on-disk database compatibility,
1513 meaning you cannot use <command>pg_upgrade</command> to upgrade to
1514 a build with a different block size.
1515 </para>
1516 </listitem>
1517 </varlistentry>
1518
1519 <varlistentry id="configure-option-with-wal-blocksize">
1520 <term><option>--with-wal-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
1521 <listitem>
1522 <para>
1523 Set the <firstterm>WAL block size</firstterm>, in kilobytes. This is the unit
1524 of storage and I/O within the WAL log. The default, 8 kilobytes,
1525 is suitable for most situations; but other values may be useful
1526 in special cases.
1527 The value must be a power of 2 between 1 and 64 (kilobytes).
1528 Note that changing this value breaks on-disk database compatibility,
1529 meaning you cannot use <command>pg_upgrade</command> to upgrade to
1530 a build with a different WAL block size.
1531 </para>
1532 </listitem>
1533 </varlistentry>
1534
1535 </variablelist>
1536
1537 </sect3>
1538
1539 <sect3 id="configure-options-devel">
1540 <title>Developer Options</title>
1541
1542 <para>
1543 Most of the options in this section are only of interest for
1544 developing or debugging <productname>PostgreSQL</productname>.
1545 They are not recommended for production builds, except
1546 for <option>--enable-debug</option>, which can be useful to enable
1547 detailed bug reports in the unlucky event that you encounter a bug.
1548 On platforms supporting DTrace, <option>--enable-dtrace</option>
1549 may also be reasonable to use in production.
1550 </para>
1551
1552 <para>
1553 When building an installation that will be used to develop code inside
1554 the server, it is recommended to use at least the
1555 options <option>--enable-debug</option>
1556 and <option>--enable-cassert</option>.
1557 </para>
1558
1559 <variablelist>
1560
1561 <varlistentry id="configure-option-enable-debug">
1562 <term><option>--enable-debug</option></term>
1563 <listitem>
1564 <para>
1565 Compiles all programs and libraries with debugging symbols.
1566 This means that you can run the programs in a debugger
1567 to analyze problems. This enlarges the size of the installed
1568 executables considerably, and on non-GCC compilers it usually
1569 also disables compiler optimization, causing slowdowns. However,
1570 having the symbols available is extremely helpful for dealing
1571 with any problems that might arise. Currently, this option is
1572 recommended for production installations only if you use GCC.
1573 But you should always have it on if you are doing development work
1574 or running a beta version.
1575 </para>
1576 </listitem>
1577 </varlistentry>
1578
1579 <varlistentry id="configure-option-enable-cassert">
1580 <term><option>--enable-cassert</option></term>
1581 <listitem>
1582 <para>
1583 Enables <firstterm>assertion</firstterm> checks in the server, which test for
1584 many <quote>cannot happen</quote> conditions. This is invaluable for
1585 code development purposes, but the tests can slow down the
1586 server significantly.
1587 Also, having the tests turned on won't necessarily enhance the
1588 stability of your server! The assertion checks are not categorized
1589 for severity, and so what might be a relatively harmless bug will
1590 still lead to server restarts if it triggers an assertion
1591 failure. This option is not recommended for production use, but
1592 you should have it on for development work or when running a beta
1593 version.
1594 </para>
1595 </listitem>
1596 </varlistentry>
1597
1598 <varlistentry id="configure-option-enable-tap-tests">
1599 <term><option>--enable-tap-tests</option></term>
1600 <listitem>
1601 <para>
1602 Enable tests using the Perl TAP tools. This requires a Perl
1603 installation and the Perl module <literal>IPC::Run</literal>.
1604 See <xref linkend="regress-tap"/> for more information.
1605 </para>
1606 </listitem>
1607 </varlistentry>
1608
1609 <varlistentry id="configure-option-enable-depend">
1610 <term><option>--enable-depend</option></term>
1611 <listitem>
1612 <para>
1613 Enables automatic dependency tracking. With this option, the
1614 makefiles are set up so that all affected object files will
1615 be rebuilt when any header file is changed. This is useful
1616 if you are doing development work, but is just wasted overhead
1617 if you intend only to compile once and install. At present,
1618 this option only works with GCC.
1619 </para>
1620 </listitem>
1621 </varlistentry>
1622
1623 <varlistentry id="configure-option-enable-coverage">
1624 <term><option>--enable-coverage</option></term>
1625 <listitem>
1626 <para>
1627 If using GCC, all programs and libraries are compiled with
1628 code coverage testing instrumentation. When run, they
1629 generate files in the build directory with code coverage
1630 metrics.
1631 See <xref linkend="regress-coverage"/>
1632 for more information. This option is for use only with GCC
1633 and when doing development work.
1634 </para>
1635 </listitem>
1636 </varlistentry>
1637
1638 <varlistentry id="configure-option-enable-profiling">
1639 <term><option>--enable-profiling</option></term>
1640 <listitem>
1641 <para>
1642 If using GCC, all programs and libraries are compiled so they
1643 can be profiled. On backend exit, a subdirectory will be created
1644 that contains the <filename>gmon.out</filename> file containing
1645 profile data.
1646 This option is for use only with GCC and when doing development work.
1647 </para>
1648 </listitem>
1649 </varlistentry>
1650
1651 <varlistentry id="configure-option-enable-dtrace">
1652 <term><option>--enable-dtrace</option></term>
1653 <listitem>
1654 <para>
1655 <indexterm>
1656 <primary>DTrace</primary>
1657 </indexterm>
1658 Compiles <productname>PostgreSQL</productname> with support for the
1659 dynamic tracing tool DTrace.
1660 See <xref linkend="dynamic-trace"/> for more information.
1661 </para>
1662
1663 <para>
1664 To point to the <command>dtrace</command> program, the
1665 environment variable <envar>DTRACE</envar> can be set. This
1666 will often be necessary because <command>dtrace</command> is
1667 typically installed under <filename>/usr/sbin</filename>,
1668 which might not be in your <envar>PATH</envar>.
1669 </para>
1670
1671 <para>
1672 Extra command-line options for the <command>dtrace</command> program
1673 can be specified in the environment variable
1674 <envar>DTRACEFLAGS</envar>. On Solaris,
1675 to include DTrace support in a 64-bit binary, you must specify
1676 <literal>DTRACEFLAGS="-64"</literal>. For example,
1677 using the GCC compiler:
1678 <screen>
1679 ./configure CC='gcc -m64' --enable-dtrace DTRACEFLAGS='-64' ...
1680 </screen>
1681 Using Sun's compiler:
1682 <screen>
1683 ./configure CC='/opt/SUNWspro/bin/cc -xtarget=native64' --enable-dtrace DTRACEFLAGS='-64' ...
1684 </screen>
1685 </para>
1686 </listitem>
1687 </varlistentry>
1688
1689 <varlistentry id="configure-option-enable-injection-points">
1690 <term><option>--enable-injection-points</option></term>
1691 <listitem>
1692 <para>
1693 Compiles <productname>PostgreSQL</productname> with support for
1694 injection points in the server. Injection points allow to run
1695 user-defined code from within the server in pre-defined code paths.
1696 This helps in testing and in the investigation of concurrency scenarios
1697 in a controlled fashion. This option is disabled by default. See
1698 <xref linkend="xfunc-addin-injection-points"/> for more details. This
1699 option is intended to be used only by developers for testing.
1700 </para>
1701 </listitem>
1702 </varlistentry>
1703
1704 <varlistentry id="configure-option-with-segsize-blocks">
1705 <term><option>--with-segsize-blocks=SEGSIZE_BLOCKS</option></term>
1706 <listitem>
1707 <para>
1708 Specify the relation segment size in blocks. If both
1709 <option>--with-segsize</option> and this option are specified, this
1710 option wins.
1711
1712 This option is only for developers, to test segment related code.
1713 </para>
1714 </listitem>
1715 </varlistentry>
1716
1717 </variablelist>
1718
1719 </sect3>
1720
1721 </sect2>
1722
1723 <sect2 id="configure-envvars">
1724 <title><filename>configure</filename> Environment Variables</title>
1725
1726 <indexterm zone="configure-envvars">
1727 <primary>configure environment variables</primary>
1728 </indexterm>
1729
1730 <para>
1731 In addition to the ordinary command-line options described above,
1732 <filename>configure</filename> responds to a number of environment
1733 variables.
1734 You can specify environment variables on the
1735 <filename>configure</filename> command line, for example:
1736 <screen>
1737 <userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</userinput>
1738 </screen>
1739 In this usage an environment variable is little different from a
1740 command-line option.
1741 You can also set such variables beforehand:
1742 <screen>
1743 <userinput>export CC=/opt/bin/gcc</userinput>
1744 <userinput>export CFLAGS='-O2 -pipe'</userinput>
1745 <userinput>./configure</userinput>
1746 </screen>
1747 This usage can be convenient because many programs' configuration
1748 scripts respond to these variables in similar ways.
1749 </para>
1750
1751 <para>
1752 The most commonly used of these environment variables are
1753 <envar>CC</envar> and <envar>CFLAGS</envar>.
1754 If you prefer a C compiler different from the one
1755 <filename>configure</filename> picks, you can set the
1756 variable <envar>CC</envar> to the program of your choice.
1757 By default, <filename>configure</filename> will pick
1758 <filename>gcc</filename> if available, else the platform's
1759 default (usually <filename>cc</filename>). Similarly, you can override the
1760 default compiler flags if needed with the <envar>CFLAGS</envar> variable.
1761 </para>
1762
1763 <para>
1764 Here is a list of the significant variables that can be set in
1765 this manner:
1766
1767 <variablelist>
1768 <varlistentry id="configure-envvars-bison">
1769 <term><envar>BISON</envar></term>
1770 <listitem>
1771 <para>
1772 Bison program
1773 </para>
1774 </listitem>
1775 </varlistentry>
1776
1777 <varlistentry id="configure-envvars-cc">
1778 <term><envar>CC</envar></term>
1779 <listitem>
1780 <para>
1781 C compiler
1782 </para>
1783 </listitem>
1784 </varlistentry>
1785
1786 <varlistentry id="configure-envvars-cflags">
1787 <term><envar>CFLAGS</envar></term>
1788 <listitem>
1789 <para>
1790 options to pass to the C compiler
1791 </para>
1792 </listitem>
1793 </varlistentry>
1794
1795 <varlistentry id="configure-envvars-clang">
1796 <term><envar>CLANG</envar></term>
1797 <listitem>
1798 <para>
1799 path to <command>clang</command> program used to process source code
1800 for inlining when compiling with <literal>--with-llvm</literal>
1801 </para>
1802 </listitem>
1803 </varlistentry>
1804
1805 <varlistentry id="configure-envvars-cpp">
1806 <term><envar>CPP</envar></term>
1807 <listitem>
1808 <para>
1809 C preprocessor
1810 </para>
1811 </listitem>
1812 </varlistentry>
1813
1814 <varlistentry id="configure-envvars-cppflags">
1815 <term><envar>CPPFLAGS</envar></term>
1816 <listitem>
1817 <para>
1818 options to pass to the C preprocessor
1819 </para>
1820 </listitem>
1821 </varlistentry>
1822
1823 <varlistentry id="configure-envvars-cxx">
1824 <term><envar>CXX</envar></term>
1825 <listitem>
1826 <para>
1827 C++ compiler
1828 </para>
1829 </listitem>
1830 </varlistentry>
1831
1832 <varlistentry id="configure-envvars-cxxflags">
1833 <term><envar>CXXFLAGS</envar></term>
1834 <listitem>
1835 <para>
1836 options to pass to the C++ compiler
1837 </para>
1838 </listitem>
1839 </varlistentry>
1840
1841 <varlistentry id="configure-envvars-dtrace">
1842 <term><envar>DTRACE</envar></term>
1843 <listitem>
1844 <para>
1845 location of the <command>dtrace</command> program
1846 </para>
1847 </listitem>
1848 </varlistentry>
1849
1850 <varlistentry id="configure-envvars-dtraceflags">
1851 <term><envar>DTRACEFLAGS</envar></term>
1852 <listitem>
1853 <para>
1854 options to pass to the <command>dtrace</command> program
1855 </para>
1856 </listitem>
1857 </varlistentry>
1858
1859 <varlistentry id="configure-envvars-flex">
1860 <term><envar>FLEX</envar></term>
1861 <listitem>
1862 <para>
1863 Flex program
1864 </para>
1865 </listitem>
1866 </varlistentry>
1867
1868 <varlistentry id="configure-envvars-ldflags">
1869 <term><envar>LDFLAGS</envar></term>
1870 <listitem>
1871 <para>
1872 options to use when linking either executables or shared libraries
1873 </para>
1874 </listitem>
1875 </varlistentry>
1876
1877 <varlistentry id="configure-envvars-ldflags-ex">
1878 <term><envar>LDFLAGS_EX</envar></term>
1879 <listitem>
1880 <para>
1881 additional options for linking executables only
1882 </para>
1883 </listitem>
1884 </varlistentry>
1885
1886 <varlistentry id="configure-envvars-ldflags-sl">
1887 <term><envar>LDFLAGS_SL</envar></term>
1888 <listitem>
1889 <para>
1890 additional options for linking shared libraries only
1891 </para>
1892 </listitem>
1893 </varlistentry>
1894
1895 <varlistentry id="configure-envvars-llvm-config">
1896 <term><envar>LLVM_CONFIG</envar></term>
1897 <listitem>
1898 <para>
1899 <command>llvm-config</command> program used to locate the
1900 <productname>LLVM</productname> installation
1901 </para>
1902 </listitem>
1903 </varlistentry>
1904
1905 <varlistentry id="configure-envvars-msgfmt">
1906 <term><envar>MSGFMT</envar></term>
1907 <listitem>
1908 <para>
1909 <command>msgfmt</command> program for native language support
1910 </para>
1911 </listitem>
1912 </varlistentry>
1913
1914 <varlistentry id="configure-envvars-perl">
1915 <term><envar>PERL</envar></term>
1916 <listitem>
1917 <para>
1918 Perl interpreter program. This will be used to determine the
1919 dependencies for building PL/Perl. The default is
1920 <command>perl</command>.
1921 </para>
1922 </listitem>
1923 </varlistentry>
1924
1925 <varlistentry id="configure-envvars-python">
1926 <term><envar>PYTHON</envar></term>
1927 <listitem>
1928 <para>
1929 Python interpreter program. This will be used to determine the
1930 dependencies for building PL/Python. If this is not set, the
1931 following are probed in this order:
1932 <literal>python3 python</literal>.
1933 </para>
1934 </listitem>
1935 </varlistentry>
1936
1937 <varlistentry id="configure-envvars-tclsh">
1938 <term><envar>TCLSH</envar></term>
1939 <listitem>
1940 <para>
1941 Tcl interpreter program. This will be used to
1942 determine the dependencies for building PL/Tcl.
1943 If this is not set, the following are probed in this
1944 order: <literal>tclsh tcl tclsh8.6 tclsh86 tclsh8.5 tclsh85
1945 tclsh8.4 tclsh84</literal>.
1946 </para>
1947 </listitem>
1948 </varlistentry>
1949
1950 <varlistentry id="configure-envvars-xml2-config">
1951 <term><envar>XML2_CONFIG</envar></term>
1952 <listitem>
1953 <para>
1954 <command>xml2-config</command> program used to locate the
1955 libxml2 installation
1956 </para>
1957 </listitem>
1958 </varlistentry>
1959 </variablelist>
1960 </para>
1961
1962 <para>
1963 Sometimes it is useful to add compiler flags after-the-fact to the set
1964 that were chosen by <filename>configure</filename>. An important example is
1965 that <application>gcc</application>'s <option>-Werror</option> option cannot be included
1966 in the <envar>CFLAGS</envar> passed to <filename>configure</filename>, because
1967 it will break many of <filename>configure</filename>'s built-in tests. To add
1968 such flags, include them in the <envar>COPT</envar> environment variable
1969 while running <filename>make</filename>. The contents of <envar>COPT</envar>
1970 are added to the <envar>CFLAGS</envar>, <envar>CXXFLAGS</envar>, and <envar>LDFLAGS</envar>
1971 options set up by <filename>configure</filename>. For example, you could do
1972 <screen>
1973 <userinput>make COPT='-Werror'</userinput>
1974 </screen>
1975 or
1976 <screen>
1977 <userinput>export COPT='-Werror'</userinput>
1978 <userinput>make</userinput>
1979 </screen>
1980 </para>
1981
1982 <note>
1983 <para>
1984 If using GCC, it is best to build with an optimization level of
1985 at least <option>-O1</option>, because using no optimization
1986 (<option>-O0</option>) disables some important compiler warnings (such
1987 as the use of uninitialized variables). However, non-zero
1988 optimization levels can complicate debugging because stepping
1989 through compiled code will usually not match up one-to-one with
1990 source code lines. If you get confused while trying to debug
1991 optimized code, recompile the specific files of interest with
1992 <option>-O0</option>. An easy way to do this is by passing an option
1993 to <application>make</application>: <command>make PROFILE=-O0 file.o</command>.
1994 </para>
1995
1996 <para>
1997 The <envar>COPT</envar> and <envar>PROFILE</envar> environment variables are
1998 actually handled identically by the <productname>PostgreSQL</productname>
1999 makefiles. Which to use is a matter of preference, but a common habit
2000 among developers is to use <envar>PROFILE</envar> for one-time flag
2001 adjustments, while <envar>COPT</envar> might be kept set all the time.
2002 </para>
2003 </note>
2004 </sect2>
2005 </sect1>
2006
2007 <sect1 id="install-meson">
2008 <title>Building and Installation with Meson</title>
2009
2010 <sect2 id="install-short-meson">
2011 <title>Short Version</title>
2012
2013 <para>
2014 <synopsis>
2015 meson setup build --prefix=/usr/local/pgsql
2016 cd build
2017 ninja
2018 su
2019 ninja install
2020 adduser postgres
2021 mkdir -p /usr/local/pgsql/data
2022 chown postgres /usr/local/pgsql/data
2023 su - postgres
2024 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
2025 /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
2026 /usr/local/pgsql/bin/createdb test
2027 /usr/local/pgsql/bin/psql test
2028 </synopsis>
2029 The long version is the rest of this
2030 <phrase>section</phrase>.
2031 </para>
2032 </sect2>
2033
2034 <sect2 id="install-procedure-meson">
2035 <title>Installation Procedure</title>
2036
2037 <procedure>
2038
2039 <step id="meson-configure">
2040 <title>Configuration</title>
2041
2042 <para>
2043 The first step of the installation procedure is to configure the
2044 build tree for your system and choose the options you would like. To
2045 create and configure the build directory, you can start with the
2046 <literal>meson setup</literal> command.
2047 <screen>
2048 <userinput>meson setup build</userinput>
2049 </screen>
2050 The setup command takes a <literal>builddir</literal> and a <literal>srcdir</literal>
2051 argument. If no <literal>srcdir</literal> is given, Meson will deduce the
2052 <literal>srcdir</literal> based on the current directory and the location
2053 of <literal>meson.build</literal>. The <literal>builddir</literal> is mandatory.
2054 </para>
2055
2056 <para>
2057 Running <literal>meson setup</literal> loads the build configuration file and sets up the build directory.
2058 Additionally, you can also pass several build options to Meson. Some commonly
2059 used options are mentioned in the subsequent sections. For example:
2060
2061 <screen>
2062 # configure with a different installation prefix
2063 meson setup build --prefix=/home/user/pg-install
2064
2065 # configure to generate a debug build
2066 meson setup build --buildtype=debug
2067
2068 # configure to build with OpenSSL support
2069 meson setup build -Dssl=openssl
2070 </screen>
2071 </para>
2072
2073 <para>
2074 Setting up the build directory is a one-time step. To reconfigure before a
2075 new build, you can simply use the <literal>meson configure</literal> command
2076 <screen>
2077 meson configure -Dcassert=true
2078 </screen>
2079 <command>meson configure</command>'s commonly used command-line options
2080 are explained in <xref linkend="meson-options"/>.
2081 </para>
2082 </step>
2083
2084 <step id="meson-build">
2085 <title>Build</title>
2086
2087 <para>
2088 By default, <productname>Meson</productname> uses the <ulink
2089 url="https://ninja-build.org/">Ninja</ulink> build tool. To build
2090 <productname>PostgreSQL</productname> from source using Meson, you can
2091 simply use the <literal>ninja</literal> command in the build directory.
2092 <screen>
2093 ninja
2094 </screen>
2095 Ninja will automatically detect the number of CPUs in your computer and
2096 parallelize itself accordingly. You can override the number of parallel
2097 processes used with the command line argument <literal>-j</literal>.
2098 </para>
2099
2100 <para>
2101 It should be noted that after the initial configure step,
2102 <command>ninja</command> is the only command you ever need to type to
2103 compile. No matter how you alter your source tree (short of moving it to a
2104 completely new location), Meson will detect the changes and regenerate
2105 itself accordingly. This is especially handy if you have multiple build
2106 directories. Often one of them is used for development (the "debug" build)
2107 and others only every now and then (such as a "static analysis" build).
2108 Any configuration can be built just by cd'ing to the corresponding
2109 directory and running Ninja.
2110 </para>
2111
2112 <para>
2113 If you'd like to build with a backend other than ninja, you can use
2114 configure with the <option>--backend</option> option to select the one you
2115 want to use and then build using <literal>meson compile</literal>. To
2116 learn more about these backends and other arguments you can provide to
2117 ninja, you can refer to the <ulink
2118 url="https://mesonbuild.com/Running-Meson.html#building-from-the-source">
2119 Meson documentation</ulink>.
2120 </para>
2121 </step>
2122
2123 <step>
2124 <title>Regression Tests</title>
2125
2126 <indexterm>
2127 <primary>regression test</primary>
2128 </indexterm>
2129
2130 <para>
2131 If you want to test the newly built server before you install it,
2132 you can run the regression tests at this point. The regression
2133 tests are a test suite to verify that <productname>PostgreSQL</productname>
2134 runs on your machine in the way the developers expected it
2135 to. Type:
2136 <screen>
2137 <userinput>meson test</userinput>
2138 </screen>
2139 (This won't work as root; do it as an unprivileged user.)
2140 See <xref linkend="regress"/> for
2141 detailed information about interpreting the test results. You can
2142 repeat this test at any later time by issuing the same command.
2143 </para>
2144
2145 <para>
2146 To run pg_regress and pg_isolation_regress tests against a running
2147 postgres instance, specify <userinput>--setup running</userinput> as an
2148 argument to <userinput>meson test</userinput>.
2149 </para>
2150 </step>
2151
2152 <step id="meson-install">
2153 <title>Installing the Files</title>
2154
2155 <note>
2156 <para>
2157 If you are upgrading an existing system be sure to read
2158 <xref linkend="upgrading"/>,
2159 which has instructions about upgrading a
2160 cluster.
2161 </para>
2162 </note>
2163
2164 <para>
2165 Once PostgreSQL is built, you can install it by simply running the
2166 <literal>ninja install</literal> command.
2167 <screen>
2168 ninja install
2169 </screen>
2170 </para>
2171
2172 <para>
2173 This will install files into the directories that were specified
2174 in <xref linkend="meson-configure"/>. Make sure that you have appropriate
2175 permissions to write into that area. You might need to do this
2176 step as root. Alternatively, you can create the target directories
2177 in advance and arrange for appropriate permissions to be granted.
2178 The standard installation provides all the header files needed for client
2179 application development as well as for server-side program
2180 development, such as custom functions or data types written in C.
2181 </para>
2182
2183 <para>
2184 <literal>ninja install</literal> should work for most cases, but if you'd
2185 like to use more options (such as <option>--quiet</option> to suppress
2186 extra output), you could also use <literal>meson install</literal>
2187 instead. You can learn more about <ulink
2188 url="https://mesonbuild.com/Commands.html#install">meson install</ulink>
2189 and its options in the Meson documentation.
2190 </para>
2191 </step>
2192 </procedure>
2193
2194 <formalpara>
2195 <title>Uninstallation:</title>
2196 <para>
2197 To undo the installation, you can use the <command>ninja
2198 uninstall</command> command.
2199 </para>
2200 </formalpara>
2201
2202 <formalpara>
2203 <title>Cleaning:</title>
2204 <para>
2205 After the installation, you can free disk space by removing the built
2206 files from the source tree with the <command>ninja clean</command>
2207 command.
2208 </para>
2209 </formalpara>
2210 </sect2>
2211
2212 <sect2 id="meson-options">
2213 <title><literal>meson setup</literal> Options</title>
2214
2215 <para>
2216 <command>meson setup</command>'s command-line options are explained below.
2217 This list is not exhaustive (use <literal>meson configure --help</literal>
2218 to get one that is). The options not covered here are meant for advanced
2219 use-cases, and are documented in the standard <ulink
2220 url="https://mesonbuild.com/Commands.html#configure">Meson
2221 documentation</ulink>. These arguments can be used with <command>meson
2222 setup</command> as well.
2223 </para>
2224
2225 <sect3 id="meson-options-locations">
2226 <title>Installation Locations</title>
2227
2228 <para>
2229 These options control where <literal>ninja install</literal> (or <literal>meson install</literal>) will put
2230 the files. The <option>--prefix</option> option (example
2231 <xref linkend="install-short-meson"/>) is sufficient for
2232 most cases. If you have special needs, you can customize the
2233 installation subdirectories with the other options described in this
2234 section. Beware however that changing the relative locations of the
2235 different subdirectories may render the installation non-relocatable,
2236 meaning you won't be able to move it after installation.
2237 (The <literal>man</literal> and <literal>doc</literal> locations are
2238 not affected by this restriction.) For relocatable installs, you
2239 might want to use the <literal>-Drpath=false</literal> option
2240 described later.
2241 </para>
2242
2243 <variablelist>
2244 <varlistentry id="configure-prefix-meson">
2245 <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
2246 <listitem>
2247 <para>
2248 Install all files under the directory <replaceable>PREFIX</replaceable>
2249 instead of <filename>/usr/local/pgsql</filename> (on Unix based systems) or
2250 <filename><replaceable>current drive letter</replaceable>:/usr/local/pgsql</filename> (on Windows).
2251 The actual files will be installed into various subdirectories; no files
2252 will ever be installed directly into the
2253 <replaceable>PREFIX</replaceable> directory.
2254 </para>
2255 </listitem>
2256 </varlistentry>
2257
2258 <varlistentry id="configure-bindir-meson">
2259 <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
2260 <listitem>
2261 <para>
2262 Specifies the directory for executable programs. The default
2263 is <filename><replaceable>PREFIX</replaceable>/bin</filename>.
2264 </para>
2265 </listitem>
2266 </varlistentry>
2267
2268 <varlistentry id="configure-sysconfdir-meson">
2269 <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
2270 <listitem>
2271 <para>
2272 Sets the directory for various configuration files,
2273 <filename><replaceable>PREFIX</replaceable>/etc</filename> by default.
2274 </para>
2275 </listitem>
2276 </varlistentry>
2277
2278 <varlistentry id="configure-libdir-meson">
2279 <term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
2280 <listitem>
2281 <para>
2282 Sets the location to install libraries and dynamically loadable
2283 modules. The default is
2284 <filename><replaceable>PREFIX</replaceable>/lib</filename>.
2285 </para>
2286 </listitem>
2287 </varlistentry>
2288
2289 <varlistentry id="configure-includedir-meson">
2290 <term><option>--includedir=<replaceable>DIRECTORY</replaceable></option></term>
2291 <listitem>
2292 <para>
2293 Sets the directory for installing C and C++ header files. The
2294 default is <filename><replaceable>PREFIX</replaceable>/include</filename>.
2295 </para>
2296 </listitem>
2297 </varlistentry>
2298
2299 <varlistentry id="configure-datadir-meson">
2300 <term><option>--datadir=<replaceable>DIRECTORY</replaceable></option></term>
2301 <listitem>
2302 <para>
2303 Sets the directory for read-only data files used by the
2304 installed programs. The default is
2305 <filename><replaceable>PREFIX</replaceable>/share</filename>. Note that this has
2306 nothing to do with where your database files will be placed.
2307 </para>
2308 </listitem>
2309 </varlistentry>
2310
2311 <varlistentry id="configure-localedir-meson">
2312 <term><option>--localedir=<replaceable>DIRECTORY</replaceable></option></term>
2313 <listitem>
2314 <para>
2315 Sets the directory for installing locale data, in particular
2316 message translation catalog files. The default is
2317 <filename><replaceable>DATADIR</replaceable>/locale</filename>.
2318 </para>
2319 </listitem>
2320 </varlistentry>
2321
2322 <varlistentry id="configure-mandir-meson">
2323 <term><option>--mandir=<replaceable>DIRECTORY</replaceable></option></term>
2324 <listitem>
2325 <para>
2326 The man pages that come with <productname>PostgreSQL</productname> will be installed under
2327 this directory, in their respective
2328 <filename>man<replaceable>x</replaceable></filename> subdirectories.
2329 The default is <filename><replaceable>DATADIR</replaceable>/man</filename>.
2330 </para>
2331 </listitem>
2332 </varlistentry>
2333
2334 </variablelist>
2335
2336 <note>
2337 <para>
2338 Care has been taken to make it possible to install
2339 <productname>PostgreSQL</productname> into shared installation locations
2340 (such as <filename>/usr/local/include</filename>) without
2341 interfering with the namespace of the rest of the system. First,
2342 the string <quote><literal>/postgresql</literal></quote> is
2343 automatically appended to <varname>datadir</varname>,
2344 <varname>sysconfdir</varname>, and <varname>docdir</varname>,
2345 unless the fully expanded directory name already contains the
2346 string <quote><literal>postgres</literal></quote> or
2347 <quote><literal>pgsql</literal></quote>. For example, if you choose
2348 <filename>/usr/local</filename> as prefix, the documentation will
2349 be installed in <filename>/usr/local/doc/postgresql</filename>,
2350 but if the prefix is <filename>/opt/postgres</filename>, then it
2351 will be in <filename>/opt/postgres/doc</filename>. The public C
2352 header files of the client interfaces are installed into
2353 <varname>includedir</varname> and are namespace-clean. The
2354 internal header files and the server header files are installed
2355 into private directories under <varname>includedir</varname>. See
2356 the documentation of each interface for information about how to
2357 access its header files. Finally, a private subdirectory will
2358 also be created, if appropriate, under <varname>libdir</varname>
2359 for dynamically loadable modules.
2360 </para>
2361 </note>
2362 </sect3>
2363
2364 <sect3 id="meson-options-features">
2365 <title><productname>PostgreSQL</productname> Features</title>
2366
2367 <para>
2368 The options described in this section enable building of
2369 various optional <productname>PostgreSQL</productname> features.
2370 Most of these require additional software, as described in
2371 <xref linkend="install-requirements"/>, and will be automatically enabled if the
2372 required software is found. You can change this behavior by manually
2373 setting these features to <literal>enabled</literal> to require them
2374 or <literal>disabled</literal> to not build with them.
2375 </para>
2376
2377 <para>
2378 To specify PostgreSQL-specific options, the name of the option
2379 must be prefixed by <literal>-D</literal>.
2380 </para>
2381
2382 <variablelist>
2383 <varlistentry id="configure-with-nls-meson">
2384 <term><option>-Dnls={ auto | enabled | disabled }</option></term>
2385 <listitem>
2386 <para>
2387 Enables or disables Native Language Support (<acronym>NLS</acronym>),
2388 that is, the ability to display a program's messages in a language
2389 other than English. Defaults to auto and will be enabled
2390 automatically if an implementation of the <application>Gettext
2391 API</application> is found.
2392 </para>
2393 </listitem>
2394 </varlistentry>
2395
2396 <varlistentry id="configure-with-plperl-meson">
2397 <term><option>-Dplperl={ auto | enabled | disabled }</option></term>
2398 <listitem>
2399 <para>
2400 Build the <application>PL/Perl</application> server-side language.
2401 Defaults to auto.
2402 </para>
2403 </listitem>
2404 </varlistentry>
2405
2406 <varlistentry id="configure-with-plpython-meson">
2407 <term><option>-Dplpython={ auto | enabled | disabled }</option></term>
2408 <listitem>
2409 <para>
2410 Build the <application>PL/Python</application> server-side language.
2411 Defaults to auto.
2412 </para>
2413 </listitem>
2414 </varlistentry>
2415
2416 <varlistentry id="configure-with-pltcl-meson">
2417 <term><option>-Dpltcl={ auto | enabled | disabled }</option></term>
2418 <listitem>
2419 <para>
2420 Build the <application>PL/Tcl</application> server-side language.
2421 Defaults to auto.
2422 </para>
2423 </listitem>
2424 </varlistentry>
2425
2426 <varlistentry id="configure-with-tcl-version-meson">
2427 <term><option>-Dtcl_version=<replaceable>TCL_VERSION</replaceable></option></term>
2428 <listitem>
2429 <para>
2430 Specifies the Tcl version to use when building PL/Tcl.
2431 </para>
2432 </listitem>
2433 </varlistentry>
2434
2435 <varlistentry id="configure-with-icu-meson">
2436 <term><option>-Dicu={ auto | enabled | disabled }</option></term>
2437 <listitem>
2438 <para>
2439 Build with support for the
2440 <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
2441 library, enabling use of ICU collation features (see <xref
2442 linkend="collation"/>). Defaults to auto and requires the
2443 <productname>ICU4C</productname> package to be installed. The minimum
2444 required version of <productname>ICU4C</productname> is currently 4.2.
2445 </para>
2446 </listitem>
2447 </varlistentry>
2448
2449 <varlistentry id="configure-with-llvm-meson">
2450 <term><option>-Dllvm={ auto | enabled | disabled }</option></term>
2451 <listitem>
2452 <para>
2453 Build with support for <productname>LLVM</productname> based
2454 <acronym>JIT</acronym> compilation (see <xref linkend="jit"/>).
2455 This requires the <productname>LLVM</productname> library to be
2456 installed. The minimum required version of
2457 <productname>LLVM</productname> is currently 14. Disabled by
2458 default.
2459 </para>
2460
2461 <para>
2462 <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
2463 will be used to find the required compilation options.
2464 <command>llvm-config</command>, and then
2465 <command>llvm-config-$version</command> for all supported versions,
2466 will be searched for in your <envar>PATH</envar>. If that would not
2467 yield the desired program, use <envar>LLVM_CONFIG</envar> to specify a
2468 path to the correct <command>llvm-config</command>.
2469 </para>
2470 </listitem>
2471 </varlistentry>
2472
2473 <varlistentry id="configure-with-lz4-meson">
2474 <term><option>-Dlz4={ auto | enabled | disabled }</option></term>
2475 <listitem>
2476 <para>
2477 Build with <productname>LZ4</productname> compression support.
2478 Defaults to auto.
2479 </para>
2480 </listitem>
2481 </varlistentry>
2482
2483 <varlistentry id="configure-with-zstd-meson">
2484 <term><option>-Dzstd={ auto | enabled | disabled }</option></term>
2485 <listitem>
2486 <para>
2487 Build with <productname>Zstandard</productname> compression support.
2488 Defaults to auto.
2489 </para>
2490 </listitem>
2491 </varlistentry>
2492
2493 <varlistentry id="configure-with-ssl-meson">
2494 <term><option>-Dssl={ auto | <replaceable>LIBRARY</replaceable> }</option>
2495 <indexterm>
2496 <primary>OpenSSL</primary>
2497 <seealso>SSL</seealso>
2498 </indexterm>
2499 </term>
2500 <listitem>
2501 <para>
2502 Build with support for <acronym>SSL</acronym> (encrypted) connections.
2503 The only <replaceable>LIBRARY</replaceable> supported is
2504 <option>openssl</option>. This requires the
2505 <productname>OpenSSL</productname> package to be installed. Building
2506 with this will check for the required header files and libraries to
2507 make sure that your <productname>OpenSSL</productname> installation is
2508 sufficient before proceeding. The default for this option is auto.
2509 </para>
2510 </listitem>
2511 </varlistentry>
2512
2513 <varlistentry id="configure-with-gssapi-meson">
2514 <term><option>-Dgssapi={ auto | enabled | disabled }</option></term>
2515 <listitem>
2516 <para>
2517 Build with support for GSSAPI authentication. MIT Kerberos is required
2518 to be installed for GSSAPI. On many systems, the GSSAPI system (a part
2519 of the MIT Kerberos installation) is not installed in a location
2520 that is searched by default (e.g., <filename>/usr/include</filename>,
2521 <filename>/usr/lib</filename>). In
2522 those cases, PostgreSQL will query <command>pkg-config</command> to
2523 detect the required compiler and linker options. Defaults to auto.
2524 <filename>meson configure</filename> will check for the required
2525 header files and libraries to make sure that your GSSAPI installation
2526 is sufficient before proceeding.
2527 </para>
2528 </listitem>
2529 </varlistentry>
2530
2531 <varlistentry id="configure-with-ldap-meson">
2532 <term><option>-Dldap={ auto | enabled | disabled }</option></term>
2533 <listitem>
2534 <para>
2535 Build with
2536 <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
2537 support for authentication and connection parameter lookup (see
2538 <phrase id="install-ldap-links-meson"><xref linkend="libpq-ldap"/> and
2539 <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
2540 this requires the <productname>OpenLDAP</productname> package to be
2541 installed. On Windows, the default <productname>WinLDAP</productname>
2542 library is used. Defaults to auto. <filename>meson
2543 configure</filename> will check for the required header files and
2544 libraries to make sure that your <productname>OpenLDAP</productname>
2545 installation is sufficient before proceeding.
2546 </para>
2547 </listitem>
2548 </varlistentry>
2549
2550 <varlistentry id="configure-with-pam-meson">
2551 <term><option>-Dpam={ auto | enabled | disabled }</option></term>
2552 <listitem>
2553 <para>
2554 Build with
2555 <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
2556 (Pluggable Authentication Modules) support. Defaults to auto.
2557 </para>
2558 </listitem>
2559 </varlistentry>
2560
2561 <varlistentry id="configure-with-bsd-auth-meson">
2562 <term><option>-Dbsd_auth={ auto | enabled | disabled }</option></term>
2563 <listitem>
2564 <para>
2565 Build with BSD Authentication support. (The BSD Authentication
2566 framework is currently only available on OpenBSD.) Defaults to auto.
2567 </para>
2568 </listitem>
2569 </varlistentry>
2570
2571 <varlistentry id="configure-with-systemd-meson">
2572 <term><option>-Dsystemd={ auto | enabled | disabled }</option></term>
2573 <listitem>
2574 <para>
2575 Build with support for
2576 <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
2577 service notifications. This improves integration if the server is
2578 started under <application>systemd</application> but has no impact
2579 otherwise; see <xref
2580 linkend="server-start"/> for more information. Defaults to
2581 auto. <application>libsystemd</application> and the associated header
2582 files need to be installed to use this option.
2583 </para>
2584 </listitem>
2585 </varlistentry>
2586
2587 <varlistentry id="configure-with-bonjour-meson">
2588 <term><option>-Dbonjour={ auto | enabled | disabled }</option></term>
2589 <listitem>
2590 <para>
2591 Build with support for Bonjour automatic service discovery. Defaults
2592 to auto and requires Bonjour support in your operating system.
2593 Recommended on macOS.
2594 </para>
2595 </listitem>
2596 </varlistentry>
2597
2598 <varlistentry id="configure-with-uuid-meson">
2599 <term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term>
2600 <listitem>
2601 <para>
2602 Build the <xref linkend="uuid-ossp"/> module
2603 (which provides functions to generate UUIDs), using the specified
2604 UUID library.<indexterm><primary>UUID</primary></indexterm>
2605 <replaceable>LIBRARY</replaceable> must be one of:
2606 </para>
2607 <itemizedlist>
2608 <listitem>
2609 <para>
2610 <option>none</option> to not build the uuid module. This is the default.
2611 </para>
2612 </listitem>
2613 <listitem>
2614 <para>
2615 <option>bsd</option> to use the UUID functions found in FreeBSD,
2616 and some other BSD-derived systems
2617 </para>
2618 </listitem>
2619 <listitem>
2620 <para>
2621 <option>e2fs</option> to use the UUID library created by
2622 the <literal>e2fsprogs</literal> project; this library is present in most
2623 Linux systems and in macOS, and can be obtained for other
2624 platforms as well
2625 </para>
2626 </listitem>
2627 <listitem>
2628 <para>
2629 <option>ossp</option> to use the <ulink
2630 url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
2631 </para>
2632 </listitem>
2633 </itemizedlist>
2634 </listitem>
2635 </varlistentry>
2636
2637 <varlistentry id="configure-with-libcurl-meson">
2638 <term><option>-Dlibcurl={ auto | enabled | disabled }</option></term>
2639 <listitem>
2640 <para>
2641 Build with libcurl support for OAuth 2.0 client flows.
2642 Libcurl version 7.61.0 or later is required for this feature.
2643 Building with this will check for the required header files
2644 and libraries to make sure that your <productname>Curl</productname>
2645 installation is sufficient before proceeding. The default for this
2646 option is auto.
2647 </para>
2648 </listitem>
2649 </varlistentry>
2650
2651 <varlistentry id="configure-with-liburing-meson">
2652 <term><option>-Dliburing={ auto | enabled | disabled }</option></term>
2653 <listitem>
2654 <para>
2655 Build with liburing, enabling io_uring support for asynchronous I/O.
2656 Defaults to auto.
2657 </para>
2658
2659 <para>
2660 To use a liburing installation that is in an unusual location, you
2661 can set <command>pkg-config</command>-related environment
2662 variables (see its documentation).
2663 </para>
2664 </listitem>
2665 </varlistentry>
2666
2667 <varlistentry id="configure-with-libnuma-meson">
2668 <term><option>-Dlibnuma={ auto | enabled | disabled }</option></term>
2669 <listitem>
2670 <para>
2671 Build with libnuma support for basic NUMA support.
2672 Only supported on platforms for which the <productname>libnuma</productname>
2673 library is implemented. The default for this option is auto.
2674 </para>
2675 </listitem>
2676 </varlistentry>
2677
2678 <varlistentry id="configure-with-libxml-meson">
2679 <term><option>-Dlibxml={ auto | enabled | disabled }</option></term>
2680 <listitem>
2681 <para>
2682 Build with libxml2, enabling SQL/XML support. Defaults to
2683 auto. Libxml2 version 2.6.23 or later is required for this feature.
2684 </para>
2685
2686 <para>
2687 To use a libxml2 installation that is in an unusual location, you
2688 can set <command>pkg-config</command>-related environment
2689 variables (see its documentation).
2690 </para>
2691 </listitem>
2692 </varlistentry>
2693
2694 <varlistentry id="configure-with-libxslt-meson">
2695 <term><option>-Dlibxslt={ auto | enabled | disabled }</option></term>
2696 <listitem>
2697 <para>
2698 Build with libxslt, enabling the
2699 <xref linkend="xml2"/>
2700 module to perform XSL transformations of XML.
2701 <option>-Dlibxml</option> must be specified as well. Defaults to
2702 auto.
2703 </para>
2704 </listitem>
2705 </varlistentry>
2706
2707 <varlistentry id="configure-with-sepgsql-meson">
2708 <term><option>-Dselinux={ auto | enabled | disabled }</option></term>
2709 <listitem>
2710 <para>
2711 Build with SElinux support, enabling the <xref linkend="sepgsql"/>
2712 extension. Defaults to auto.
2713 </para>
2714 </listitem>
2715 </varlistentry>
2716
2717 </variablelist>
2718 </sect3>
2719
2720 <sect3 id="meson-options-anti-features">
2721 <title>Anti-Features</title>
2722
2723 <variablelist>
2724 <varlistentry id="configure-readline-meson">
2725 <term><option>-Dreadline={ auto | enabled | disabled }</option></term>
2726 <listitem>
2727 <para>
2728 Allows use of the <application>Readline</application> library (and
2729 <application>libedit</application> as well). This option defaults to
2730 auto and enables command-line editing and history in
2731 <application>psql</application> and is strongly recommended.
2732 </para>
2733 </listitem>
2734 </varlistentry>
2735
2736 <varlistentry id="configure-libedit-preferred-meson">
2737 <term><option>-Dlibedit_preferred={ true | false }</option></term>
2738 <listitem>
2739 <para>
2740 Setting this to true favors the use of the BSD-licensed
2741 <application>libedit</application> library rather than GPL-licensed
2742 <application>Readline</application>. This option is significant only
2743 if you have both libraries installed; the default is false, that is to
2744 use <application>Readline</application>.
2745 </para>
2746 </listitem>
2747 </varlistentry>
2748
2749 <varlistentry id="configure-zlib-meson">
2750 <term><option>-Dzlib={ auto | enabled | disabled }</option></term>
2751 <listitem>
2752 <para>
2753 <indexterm>
2754 <primary>zlib</primary>
2755 </indexterm>
2756 Enables use of the <application>Zlib</application> library.
2757 It defaults to auto and enables
2758 support for compressed archives in <application>pg_dump</application>,
2759 <application>pg_restore</application> and <application>pg_basebackup</application> and is recommended.
2760 </para>
2761 </listitem>
2762 </varlistentry>
2763
2764 </variablelist>
2765 </sect3>
2766
2767 <sect3 id="meson-options-build-process">
2768 <title>Build Process Details</title>
2769
2770 <variablelist>
2771 <varlistentry id="configure-auto-features-meson">
2772 <term><option>--auto-features={ auto | enabled | disabled }</option></term>
2773 <listitem>
2774 <para>
2775 Setting this option allows you to override the value of all
2776 <quote>auto</quote> features (features that are enabled automatically
2777 if the required software is found). This can be useful when you want
2778 to disable or enable all the <quote>optional</quote> features at once
2779 without having to set each of them manually. The default value for
2780 this parameter is auto.
2781 </para>
2782 </listitem>
2783 </varlistentry>
2784
2785 <varlistentry id="configure-backend-meson">
2786 <term><option>--backend=<replaceable>BACKEND</replaceable></option></term>
2787 <listitem>
2788 <para>
2789 The default backend Meson uses is ninja and that should suffice for
2790 most use cases. However, if you'd like to fully integrate with Visual
2791 Studio, you can set the <replaceable>BACKEND</replaceable> to
2792 <literal>vs</literal>.
2793 </para>
2794 </listitem>
2795 </varlistentry>
2796
2797 <varlistentry id="configure-c-args-meson">
2798 <term><option>-Dc_args=<replaceable>OPTIONS</replaceable></option></term>
2799 <listitem>
2800 <para>
2801 This option can be used to pass extra options to the C compiler.
2802 </para>
2803 </listitem>
2804 </varlistentry>
2805
2806 <varlistentry id="configure-c-link-args-meson">
2807 <term><option>-Dc_link_args=<replaceable>OPTIONS</replaceable></option></term>
2808 <listitem>
2809 <para>
2810 This option can be used to pass extra options to the C linker.
2811 </para>
2812 </listitem>
2813 </varlistentry>
2814
2815 <varlistentry id="configure-extra-include-dirs-meson">
2816 <term><option>-Dextra_include_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
2817 <listitem>
2818 <para>
2819 <replaceable>DIRECTORIES</replaceable> is a comma-separated list of
2820 directories that will be added to the list the compiler searches for
2821 header files. If you have optional packages (such as GNU
2822 <application>Readline</application>) installed in a non-standard
2823 location, you have to use this option and probably also the
2824 corresponding <option>-Dextra_lib_dirs</option> option.
2825 </para>
2826
2827 <para>
2828 Example: <literal>-Dextra_include_dirs=/opt/gnu/include,/usr/sup/include</literal>.
2829 </para>
2830 </listitem>
2831 </varlistentry>
2832
2833 <varlistentry id="configure-extra-lib-dirs-meson">
2834 <term><option>-Dextra_lib_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
2835 <listitem>
2836 <para>
2837 <replaceable>DIRECTORIES</replaceable> is a comma-separated list of
2838 directories to search for libraries. You will probably have to use
2839 this option (and the corresponding
2840 <option>-Dextra_include_dirs</option> option) if you have packages
2841 installed in non-standard locations.
2842 </para>
2843 <para>
2844 Example: <literal>-Dextra_lib_dirs=/opt/gnu/lib,/usr/sup/lib</literal>.
2845 </para>
2846 </listitem>
2847 </varlistentry>
2848
2849 <varlistentry id="configure-system-tzdata-meson">
2850 <term><option>-Dsystem_tzdata=<replaceable>DIRECTORY</replaceable></option>
2851 <indexterm>
2852 <primary>time zone data</primary>
2853 </indexterm>
2854 </term>
2855 <listitem>
2856 <para>
2857 <productname>PostgreSQL</productname> includes its own time zone
2858 database, which it requires for date and time operations. This time
2859 zone database is in fact compatible with the IANA time zone database
2860 provided by many operating systems such as FreeBSD, Linux, and
2861 Solaris, so it would be redundant to install it again. When this
2862 option is used, the system-supplied time zone database in
2863 <replaceable>DIRECTORY</replaceable> is used instead of the one
2864 included in the PostgreSQL source distribution.
2865 <replaceable>DIRECTORY</replaceable> must be specified as an absolute
2866 path. <filename>/usr/share/zoneinfo</filename> is a likely directory
2867 on some operating systems. Note that the installation routine will
2868 not detect mismatching or erroneous time zone data. If you use this
2869 option, you are advised to run the regression tests to verify that the
2870 time zone data you have pointed to works correctly with
2871 <productname>PostgreSQL</productname>.
2872 </para>
2873
2874 <indexterm><primary>cross compilation</primary></indexterm>
2875
2876 <para>
2877 This option is mainly aimed at binary package distributors who know
2878 their target operating system well. The main advantage of using this
2879 option is that the PostgreSQL package won't need to be upgraded
2880 whenever any of the many local daylight-saving time rules change.
2881 Another advantage is that PostgreSQL can be cross-compiled more
2882 straightforwardly if the time zone database files do not need to be
2883 built during the installation.
2884 </para>
2885 </listitem>
2886 </varlistentry>
2887
2888 <varlistentry id="configure-extra-version-meson">
2889 <term><option>-Dextra_version=<replaceable>STRING</replaceable></option></term>
2890 <listitem>
2891 <para>
2892 Append <replaceable>STRING</replaceable> to the PostgreSQL version
2893 number. You can use this, for example, to mark binaries built from
2894 unreleased <productname>Git</productname> snapshots or containing
2895 custom patches with an extra version string, such as a <command>git
2896 describe</command> identifier or a distribution package release
2897 number.
2898 </para>
2899 </listitem>
2900 </varlistentry>
2901
2902 <varlistentry id="configure-rpath-meson">
2903 <term><option>-Drpath={ true | false }</option></term>
2904 <listitem>
2905 <para>
2906 This option is set to true by default. If set to false,
2907 do not mark <productname>PostgreSQL</productname>'s executables
2908 to indicate that they should search for shared libraries in the
2909 installation's library directory (see <option>--libdir</option>).
2910 On most platforms, this marking uses an absolute path to the
2911 library directory, so that it will be unhelpful if you relocate
2912 the installation later. However, you will then need to provide
2913 some other way for the executables to find the shared libraries.
2914 Typically this requires configuring the operating system's
2915 dynamic linker to search the library directory; see
2916 <xref linkend="install-post-shlibs"/> for more detail.
2917 </para>
2918 </listitem>
2919 </varlistentry>
2920
2921 <varlistentry id="configure-binary-name-meson">
2922 <term><option>-D<replaceable>BINARY_NAME</replaceable>=<replaceable>PATH</replaceable></option></term>
2923 <listitem>
2924 <para>
2925 If a program required to build PostgreSQL (with or without optional
2926 flags) is stored at a non-standard path, you can specify it manually
2927 to <literal>meson configure</literal>. The complete list of programs
2928 for which this is supported can be found by running <literal>meson
2929 configure</literal>. Example:
2930 <programlisting>meson configure -DBISON=PATH_TO_BISON</programlisting>
2931 </para>
2932 </listitem>
2933 </varlistentry>
2934 </variablelist>
2935 </sect3>
2936
2937 <sect3 id="meson-options-docs">
2938 <title>Documentation</title>
2939
2940 <para>
2941 See <xref linkend="docguide-toolsets"/> for the tools needed for building
2942 the documentation.
2943 </para>
2944
2945 <variablelist>
2946
2947 <varlistentry id="configure-docs-meson">
2948 <term><option>-Ddocs={ auto | enabled | disabled }</option></term>
2949 <listitem>
2950 <para>
2951 Enables building the documentation in <acronym>HTML</acronym> and
2952 <acronym>man</acronym> format. It defaults to auto.
2953 </para>
2954 </listitem>
2955 </varlistentry>
2956
2957 <varlistentry id="configure-docs-pdf-meson">
2958 <term><option>-Ddocs_pdf={ auto | enabled | disabled }</option></term>
2959 <listitem>
2960 <para>
2961 Enables building the documentation in <acronym>PDF</acronym>
2962 format. It defaults to auto.
2963 </para>
2964 </listitem>
2965 </varlistentry>
2966
2967 <varlistentry id="configure-docs-html-style">
2968 <term><option>-Ddocs_html_style={ simple | website }</option></term>
2969 <listitem>
2970 <para>
2971 Controls which <acronym>CSS</acronym> stylesheet is used. The default
2972 is <literal>simple</literal>. If set to <literal>website</literal>,
2973 the HTML documentation will reference the stylesheet for <ulink
2974 url="https://www.postgresql.org/docs/current/">postgresql.org</ulink>.
2975 </para>
2976 </listitem>
2977 </varlistentry>
2978
2979 </variablelist>
2980 </sect3>
2981
2982 <sect3 id="meson-options-misc">
2983 <title>Miscellaneous</title>
2984
2985 <variablelist>
2986 <varlistentry id="configure-pgport-meson">
2987 <term><option>-Dpgport=<replaceable>NUMBER</replaceable></option></term>
2988 <listitem>
2989 <para>
2990 Set <replaceable>NUMBER</replaceable> as the default port number for
2991 server and clients. The default is 5432. The port can always
2992 be changed later on, but if you specify it here then both
2993 server and clients will have the same default compiled in,
2994 which can be very convenient. Usually the only good reason
2995 to select a non-default value is if you intend to run multiple
2996 <productname>PostgreSQL</productname> servers on the same machine.
2997 </para>
2998 </listitem>
2999 </varlistentry>
3000
3001 <varlistentry id="configure-krb-srvnam-meson">
3002 <term><option>-Dkrb_srvnam=<replaceable>NAME</replaceable></option></term>
3003 <listitem>
3004 <para>
3005 The default name of the Kerberos service principal used
3006 by GSSAPI.
3007 <literal>postgres</literal> is the default. There's usually no
3008 reason to change this unless you are building for a Windows
3009 environment, in which case it must be set to upper case
3010 <literal>POSTGRES</literal>.
3011 </para>
3012 </listitem>
3013 </varlistentry>
3014
3015 <varlistentry id="configure-segsize-meson">
3016 <term><option>-Dsegsize=<replaceable>SEGSIZE</replaceable></option></term>
3017 <listitem>
3018 <para>
3019 Set the <firstterm>segment size</firstterm>, in gigabytes. Large tables are
3020 divided into multiple operating-system files, each of size equal
3021 to the segment size. This avoids problems with file size limits
3022 that exist on many platforms. The default segment size, 1 gigabyte,
3023 is safe on all supported platforms. If your operating system has
3024 <quote>largefile</quote> support (which most do, nowadays), you can use
3025 a larger segment size. This can be helpful to reduce the number of
3026 file descriptors consumed when working with very large tables.
3027 But be careful not to select a value larger than is supported
3028 by your platform and the file systems you intend to use. Other
3029 tools you might wish to use, such as <application>tar</application>, could
3030 also set limits on the usable file size.
3031 It is recommended, though not absolutely required, that this value
3032 be a power of 2.
3033 </para>
3034 </listitem>
3035 </varlistentry>
3036
3037 <varlistentry id="configure-blocksize-meson">
3038 <term><option>-Dblocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
3039 <listitem>
3040 <para>
3041 Set the <firstterm>block size</firstterm>, in kilobytes. This is the unit
3042 of storage and I/O within tables. The default, 8 kilobytes,
3043 is suitable for most situations; but other values may be useful
3044 in special cases.
3045 The value must be a power of 2 between 1 and 32 (kilobytes).
3046 </para>
3047 </listitem>
3048 </varlistentry>
3049
3050 <varlistentry id="configure-wal-blocksize-meson">
3051 <term><option>-Dwal_blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
3052 <listitem>
3053 <para>
3054 Set the <firstterm>WAL block size</firstterm>, in kilobytes. This is the unit
3055 of storage and I/O within the WAL log. The default, 8 kilobytes,
3056 is suitable for most situations; but other values may be useful
3057 in special cases.
3058 The value must be a power of 2 between 1 and 64 (kilobytes).
3059 </para>
3060 </listitem>
3061 </varlistentry>
3062 </variablelist>
3063 </sect3>
3064
3065 <sect3 id="meson-options-devel">
3066 <title>Developer Options</title>
3067
3068 <para>
3069 Most of the options in this section are only of interest for
3070 developing or debugging <productname>PostgreSQL</productname>.
3071 They are not recommended for production builds, except
3072 for <option>--debug</option>, which can be useful to enable
3073 detailed bug reports in the unlucky event that you encounter a bug.
3074 On platforms supporting DTrace, <option>-Ddtrace</option>
3075 may also be reasonable to use in production.
3076 </para>
3077
3078 <para>
3079 When building an installation that will be used to develop code inside
3080 the server, it is recommended to use at least the <option>--buildtype=debug</option>
3081 and <option>-Dcassert</option> options.
3082 </para>
3083
3084 <variablelist>
3085 <varlistentry id="configure-buildtype-meson">
3086 <term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term>
3087 <listitem>
3088 <para>
3089 This option can be used to specify the buildtype to use; defaults to
3090 <option>debugoptimized</option>. If you'd like finer control on the debug
3091 symbols and optimization levels than what this option provides, you
3092 can refer to the <option>--debug</option> and
3093 <option>--optimization</option> flags.
3094 </para>
3095
3096 <para>
3097 The following build types are generally used: <option>plain</option>,
3098 <option>debug</option>, <option>debugoptimized</option> and
3099 <option>release</option>. More information about them can be found in
3100 the <ulink
3101 url="https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory">Meson
3102 documentation</ulink>.
3103 </para>
3104 </listitem>
3105 </varlistentry>
3106
3107 <varlistentry id="configure-debug-meson">
3108 <term><option>--debug</option></term>
3109 <listitem>
3110 <para>
3111 Compiles all programs and libraries with debugging symbols. This
3112 means that you can run the programs in a debugger to analyze
3113 problems. This enlarges the size of the installed executables
3114 considerably, and on non-GCC compilers it usually also disables
3115 compiler optimization, causing slowdowns. However, having the symbols
3116 available is extremely helpful for dealing with any problems that
3117 might arise. Currently, this option is recommended for production
3118 installations only if you use GCC. But you should always have it on
3119 if you are doing development work or running a beta version.
3120 </para>
3121 </listitem>
3122 </varlistentry>
3123
3124 <varlistentry id="configure-optimization-meson">
3125 <term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term>
3126 <listitem>
3127 <para>
3128 Specify the optimization level. <option>LEVEL</option> can be set to any of {0,g,1,2,3,s}.
3129 </para>
3130 </listitem>
3131 </varlistentry>
3132
3133 <varlistentry id="configure-werror-meson">
3134 <term><option>--werror</option></term>
3135 <listitem>
3136 <para>
3137 Setting this option asks the compiler to treat warnings as
3138 errors. This can be useful for code development.
3139 </para>
3140 </listitem>
3141 </varlistentry>
3142
3143 <varlistentry id="configure-cassert-meson">
3144 <term><option>-Dcassert={ true | false }</option></term>
3145 <listitem>
3146 <para>
3147 Enables <firstterm>assertion</firstterm> checks in the server, which
3148 test for many <quote>cannot happen</quote> conditions. This is
3149 invaluable for code development purposes, but the tests slow down the
3150 server significantly. Also, having the tests turned on won't
3151 necessarily enhance the stability of your server! The assertion
3152 checks are not categorized for severity, and so what might be a
3153 relatively harmless bug will still lead to server restarts if it
3154 triggers an assertion failure. This option is not recommended for
3155 production use, but you should have it on for development work or when
3156 running a beta version.
3157 </para>
3158 </listitem>
3159 </varlistentry>
3160
3161 <varlistentry id="configure-tap-tests-meson">
3162 <term><option>-Dtap_tests={ auto | enabled | disabled }</option></term>
3163 <listitem>
3164 <para>
3165 Enable tests using the Perl TAP tools. Defaults to auto and requires
3166 a Perl installation and the Perl module <literal>IPC::Run</literal>.
3167 See <xref linkend="regress-tap"/> for more information.
3168 </para>
3169 </listitem>
3170 </varlistentry>
3171
3172 <varlistentry id="configure-pg-test-extra-meson">
3173 <term><option>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
3174 <listitem>
3175 <para>
3176 Enable additional test suites, which are not run by default because
3177 they are not secure to run on a multiuser system, require special
3178 software to run, or are resource intensive. The argument is a
3179 whitespace-separated list of tests to enable. See
3180 <xref linkend="regress-additional"/> for details. If the
3181 <envar>PG_TEST_EXTRA</envar> environment variable is set when the
3182 tests are run, it overrides this setup-time option.
3183 </para>
3184 </listitem>
3185 </varlistentry>
3186
3187 <varlistentry id="configure-b-coverage-meson">
3188 <term><option>-Db_coverage={ true | false }</option></term>
3189 <listitem>
3190 <para>
3191 If using GCC, all programs and libraries are compiled with
3192 code coverage testing instrumentation. When run, they
3193 generate files in the build directory with code coverage
3194 metrics.
3195 See <xref linkend="regress-coverage"/>
3196 for more information. This option is for use only with GCC
3197 and when doing development work.
3198 </para>
3199 </listitem>
3200 </varlistentry>
3201
3202 <varlistentry id="configure-dtrace-meson">
3203 <term><option>-Ddtrace={ auto | enabled | disabled }</option></term>
3204 <listitem>
3205 <para>
3206 <indexterm>
3207 <primary>DTrace</primary>
3208 </indexterm>
3209 Enabling this compiles <productname>PostgreSQL</productname> with support for the
3210 dynamic tracing tool DTrace.
3211 See <xref linkend="dynamic-trace"/> for more information.
3212 </para>
3213
3214 <para>
3215 To point to the <command>dtrace</command> program, the
3216 <option>DTRACE</option> option can be set. This
3217 will often be necessary because <command>dtrace</command> is
3218 typically installed under <filename>/usr/sbin</filename>,
3219 which might not be in your <envar>PATH</envar>.
3220 </para>
3221 </listitem>
3222 </varlistentry>
3223
3224 <varlistentry id="configure-injection-points-meson">
3225 <term><option>-Dinjection_points={ true | false }</option></term>
3226 <listitem>
3227 <para>
3228 Compiles <productname>PostgreSQL</productname> with support for
3229 injection points in the server. Injection points allow to run
3230 user-defined code from within the server in pre-defined code paths.
3231 This helps in testing and in the investigation of concurrency scenarios
3232 in a controlled fashion. This option is disabled by default. See
3233 <xref linkend="xfunc-addin-injection-points"/> for more details. This
3234 option is intended to be used only by developers for testing.
3235 </para>
3236 </listitem>
3237 </varlistentry>
3238
3239 <varlistentry id="configure-segsize-blocks-meson">
3240 <term><option>-Dsegsize_blocks=SEGSIZE_BLOCKS</option></term>
3241 <listitem>
3242 <para>
3243 Specify the relation segment size in blocks. If both
3244 <option>-Dsegsize</option> and this option are specified, this option
3245 wins.
3246
3247 This option is only for developers, to test segment related code.
3248 </para>
3249 </listitem>
3250 </varlistentry>
3251
3252 </variablelist>
3253 </sect3>
3254 </sect2>
3255
3256 <sect2 id="targets-meson">
3257 <title><literal>meson</literal> Build Targets</title>
3258
3259 <para>
3260 Individual build targets can be built using <command>ninja</command> <replaceable>target</replaceable>.
3261
3262 When no target is specified, everything except documentation is
3263 built. Individual build products can be built using the path/filename as
3264 <replaceable>target</replaceable>.
3265 </para>
3266
3267 &targets-meson;
3268 </sect2>
3269
3270 </sect1>
3271
3272 <sect1 id="install-post">
3273 <title>Post-Installation Setup</title>
3274
3275 <sect2 id="install-post-shlibs">
3276 <title>Shared Libraries</title>
3277
3278 <indexterm>
3279 <primary>shared library</primary>
3280 </indexterm>
3281
3282 <para>
3283 On some systems with shared libraries
3284 you need to tell the system how to find the newly installed
3285 shared libraries. The systems on which this is
3286 <emphasis>not</emphasis> necessary include
3287 <systemitem class="osname">FreeBSD</systemitem>,
3288 <systemitem class="osname">Linux</systemitem>,
3289 <systemitem class="osname">NetBSD</systemitem>, <systemitem
3290 class="osname">OpenBSD</systemitem>, and
3291 <systemitem class="osname">Solaris</systemitem>.
3292 </para>
3293
3294 <para>
3295 The method to set the shared library search path varies between
3296 platforms, but the most widely-used method is to set the
3297 environment variable <envar>LD_LIBRARY_PATH</envar> like so: In Bourne
3298 shells (<command>sh</command>, <command>ksh</command>, <command>bash</command>, <command>zsh</command>):
3299 <programlisting>
3300 LD_LIBRARY_PATH=/usr/local/pgsql/lib
3301 export LD_LIBRARY_PATH
3302 </programlisting>
3303 or in <command>csh</command> or <command>tcsh</command>:
3304 <programlisting>
3305 setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
3306 </programlisting>
3307 Replace <literal>/usr/local/pgsql/lib</literal> with whatever you set
3308 <option><literal>--libdir</literal></option> to in <xref linkend="configure"/>.
3309 You should put these commands into a shell start-up file such as
3310 <filename>/etc/profile</filename> or <filename>~/.bash_profile</filename>. Some
3311 good information about the caveats associated with this method can
3312 be found at <ulink
3313 url="http://xahlee.info/UnixResource_dir/_/ldpath.html"></ulink>.
3314 </para>
3315
3316 <para>
3317 On some systems it might be preferable to set the environment
3318 variable <envar>LD_RUN_PATH</envar> <emphasis>before</emphasis>
3319 building.
3320 </para>
3321
3322 <para>
3323 On <systemitem class="osname">Cygwin</systemitem>, put the library
3324 directory in the <envar>PATH</envar> or move the
3325 <filename>.dll</filename> files into the <filename>bin</filename>
3326 directory.
3327 </para>
3328
3329 <para>
3330 If in doubt, refer to the manual pages of your system (perhaps
3331 <command>ld.so</command> or <command>rld</command>). If you later
3332 get a message like:
3333 <screen>
3334 psql: error in loading shared libraries
3335 libpq.so.2.1: cannot open shared object file: No such file or directory
3336 </screen>
3337 then this step was necessary. Simply take care of it then.
3338 </para>
3339
3340 <para>
3341 <indexterm>
3342 <primary>ldconfig</primary>
3343 </indexterm>
3344 If you are on <systemitem class="osname">Linux</systemitem> and you have root
3345 access, you can run:
3346 <programlisting>
3347 /sbin/ldconfig /usr/local/pgsql/lib
3348 </programlisting>
3349 (or equivalent directory) after installation to enable the
3350 run-time linker to find the shared libraries faster. Refer to the
3351 manual page of <command>ldconfig</command> for more information. On
3352 <systemitem class="osname">FreeBSD</systemitem>, <systemitem
3353 class="osname">NetBSD</systemitem>, and <systemitem
3354 class="osname">OpenBSD</systemitem> the command is:
3355 <programlisting>
3356 /sbin/ldconfig -m /usr/local/pgsql/lib
3357 </programlisting>
3358 instead. Other systems are not known to have an equivalent
3359 command.
3360 </para>
3361 </sect2>
3362
3363 <sect2 id="install-post-env-vars">
3364 <title>Environment Variables</title>
3365
3366 <indexterm>
3367 <primary><envar>PATH</envar></primary>
3368 </indexterm>
3369
3370 <para>
3371 If you installed into <filename>/usr/local/pgsql</filename> or some other
3372 location that is not searched for programs by default, you should
3373 add <filename>/usr/local/pgsql/bin</filename> (or whatever you set
3374 <option><literal>--bindir</literal></option> to in <xref linkend="configure"/>)
3375 into your <envar>PATH</envar>. Strictly speaking, this is not
3376 necessary, but it will make the use of <productname>PostgreSQL</productname>
3377 much more convenient.
3378 </para>
3379
3380 <para>
3381 To do this, add the following to your shell start-up file, such as
3382 <filename>~/.bash_profile</filename> (or <filename>/etc/profile</filename>, if you
3383 want it to affect all users):
3384 <programlisting>
3385 PATH=/usr/local/pgsql/bin:$PATH
3386 export PATH
3387 </programlisting>
3388 If you are using <command>csh</command> or <command>tcsh</command>, then use this command:
3389 <programlisting>
3390 set path = ( /usr/local/pgsql/bin $path )
3391 </programlisting>
3392 </para>
3393
3394 <para>
3395 <indexterm>
3396 <primary><envar>MANPATH</envar></primary>
3397 </indexterm>
3398 To enable your system to find the <application>man</application>
3399 documentation, you need to add lines like the following to a
3400 shell start-up file unless you installed into a location that is
3401 searched by default:
3402 <programlisting>
3403 MANPATH=/usr/local/pgsql/share/man:$MANPATH
3404 export MANPATH
3405 </programlisting>
3406 </para>
3407
3408 <para>
3409 The environment variables <envar>PGHOST</envar> and <envar>PGPORT</envar>
3410 specify to client applications the host and port of the database
3411 server, overriding the compiled-in defaults. If you are going to
3412 run client applications remotely then it is convenient if every
3413 user that plans to use the database sets <envar>PGHOST</envar>. This
3414 is not required, however; the settings can be communicated via command
3415 line options to most client programs.
3416 </para>
3417 </sect2>
3418 </sect1>
3419
3420 <sect1 id="supported-platforms">
3421 <title>Supported Platforms</title>
3422
3423 <para>
3424 A platform (that is, a CPU architecture and operating system combination)
3425 is considered supported by the <productname>PostgreSQL</productname> development
3426 community if the code contains provisions to work on that platform and
3427 it has recently been verified to build and pass its regression tests
3428 on that platform. Currently, most testing of platform compatibility
3429 is done automatically by test machines in the
3430 <ulink url="https://buildfarm.postgresql.org/">PostgreSQL Build Farm</ulink>.
3431 If you are interested in using <productname>PostgreSQL</productname> on a platform
3432 that is not represented in the build farm, but on which the code works
3433 or can be made to work, you are strongly encouraged to set up a build
3434 farm member machine so that continued compatibility can be assured.
3435 </para>
3436
3437 <para>
3438 In general, <productname>PostgreSQL</productname> can be expected to work on
3439 these CPU architectures: x86, PowerPC, S/390, SPARC, ARM, MIPS,
3440 and RISC-V, including
3441 big-endian, little-endian, 32-bit, and 64-bit variants where applicable.
3442 </para>
3443
3444 <para>
3445 <productname>PostgreSQL</productname> can be expected to work on current
3446 versions of these operating systems: Linux, Windows,
3447 FreeBSD, OpenBSD, NetBSD, DragonFlyBSD, macOS, Solaris, and illumos.
3448 Other Unix-like systems may also work but are not currently
3449 being tested. In most cases, all CPU architectures supported by
3450 a given operating system will work. Look in
3451 <xref linkend="installation-platform-notes"/> below to see if
3452 there is information
3453 specific to your operating system, particularly if using an older system.
3454 </para>
3455
3456 <para>
3457 If you have installation problems on a platform that is known
3458 to be supported according to recent build farm results, please report
3459 it to <email>[email protected]</email>. If you are interested
3460 in porting <productname>PostgreSQL</productname> to a new platform,
3461 <email>[email protected]</email> is the appropriate place
3462 to discuss that.
3463 </para>
3464
3465 <para>
3466 Historical versions of <productname>PostgreSQL</productname> or POSTGRES
3467 also ran on CPU architectures including Alpha, Itanium, M32R, M68K,
3468 M88K, NS32K, PA-RISC, SuperH, and VAX,
3469 and operating systems including 4.3BSD, AIX, BEOS,
3470 BSD/OS, DG/UX, Dynix, HP-UX, IRIX, NeXTSTEP, QNX, SCO, SINIX, Sprite, SunOS,
3471 Tru64 UNIX, and ULTRIX.
3472 </para>
3473 </sect1>
3474
3475 <sect1 id="installation-platform-notes">
3476 <title>Platform-Specific Notes</title>
3477
3478 <para>
3479 This section documents additional platform-specific issues
3480 regarding the installation and setup of PostgreSQL. Be sure to
3481 read the installation instructions, and in
3482 particular <xref linkend="install-requirements"/> as well. Also,
3483 check <xref linkend="regress"/> regarding the
3484 interpretation of regression test results.
3485 </para>
3486
3487 <para>
3488 Platforms that are not covered here have no known platform-specific
3489 installation issues.
3490 </para>
3491
3492 <sect2 id="installation-notes-cygwin">
3493 <title>Cygwin</title>
3494
3495 <indexterm zone="installation-notes-cygwin">
3496 <primary>Cygwin</primary>
3497 <secondary>installation on</secondary>
3498 </indexterm>
3499
3500 <para>
3501 PostgreSQL can be built using Cygwin, a Linux-like environment for
3502 Windows, but that method is inferior to the native Windows build
3503 and running a server under Cygwin is no longer recommended.
3504 </para>
3505
3506 <para>
3507 When building from source, proceed according to the Unix-style
3508 installation procedure (i.e., <literal>./configure;
3509 make</literal>; etc.), noting the following Cygwin-specific
3510 differences:
3511
3512 <itemizedlist>
3513 <listitem>
3514 <para>
3515 Set your path to use the Cygwin bin directory before the
3516 Windows utilities. This will help prevent problems with
3517 compilation.
3518 </para>
3519 </listitem>
3520
3521 <listitem>
3522 <para>
3523 The <command>adduser</command> command is not supported; use
3524 the appropriate user management application on Windows.
3525 Otherwise, skip this step.
3526 </para>
3527 </listitem>
3528
3529 <listitem>
3530 <para>
3531 The <command>su</command> command is not supported; use ssh to
3532 simulate su on Windows. Otherwise, skip this step.
3533 </para>
3534 </listitem>
3535
3536 <listitem>
3537 <para>
3538 <productname>OpenSSL</productname> is not supported.
3539 </para>
3540 </listitem>
3541
3542 <listitem>
3543 <para>
3544 Start <command>cygserver</command> for shared memory support.
3545 To do this, enter the command <literal>/usr/sbin/cygserver
3546 &amp;</literal>. This program needs to be running anytime you
3547 start the PostgreSQL server or initialize a database cluster
3548 (<command>initdb</command>). The
3549 default <command>cygserver</command> configuration may need to
3550 be changed (e.g., increase <symbol>SEMMNS</symbol>) to prevent
3551 PostgreSQL from failing due to a lack of system resources.
3552 </para>
3553 </listitem>
3554
3555 <listitem>
3556 <para>
3557 Building might fail on some systems where a locale other than
3558 C is in use. To fix this, set the locale to C by doing
3559 <command>export LANG=C.utf8</command> before building, and then
3560 setting it back to the previous setting after you have installed
3561 PostgreSQL.
3562 </para>
3563 </listitem>
3564
3565 <listitem>
3566 <para>
3567 The parallel regression tests (<literal>make check</literal>)
3568 can generate spurious regression test failures due to
3569 overflowing the <function>listen()</function> backlog queue
3570 which causes connection refused errors or hangs. You can limit
3571 the number of connections using the make
3572 variable <varname>MAX_CONNECTIONS</varname> thus:
3573 <programlisting>
3574 make MAX_CONNECTIONS=5 check
3575 </programlisting>
3576 (On some systems you can have up to about 10 simultaneous
3577 connections.)
3578 </para>
3579 </listitem>
3580 </itemizedlist>
3581 </para>
3582
3583 <para>
3584 It is possible to install <command>cygserver</command> and the
3585 PostgreSQL server as Windows NT services. For information on how
3586 to do this, please refer to the <filename>README</filename>
3587 document included with the PostgreSQL binary package on Cygwin.
3588 It is installed in the
3589 directory <filename>/usr/share/doc/Cygwin</filename>.
3590 </para>
3591 </sect2>
3592
3593 <sect2 id="installation-notes-macos">
3594 <title>macOS</title>
3595
3596 <indexterm zone="installation-notes-macos">
3597 <primary>macOS</primary>
3598 <secondary>installation on</secondary>
3599 </indexterm>
3600
3601 <para>
3602 To build <productname>PostgreSQL</productname> from source
3603 on <productname>macOS</productname>, you will need to install Apple's
3604 command line developer tools, which can be done by issuing
3605 <programlisting>
3606 xcode-select --install
3607 </programlisting>
3608 (note that this will pop up a GUI dialog window for confirmation).
3609 You may or may not wish to also install Xcode.
3610 </para>
3611
3612 <para>
3613 On recent <productname>macOS</productname> releases, it's necessary to
3614 embed the <quote>sysroot</quote> path in the include switches used to
3615 find some system header files. This results in the outputs of
3616 the <application>configure</application> script varying depending on
3617 which SDK version was used during <application>configure</application>.
3618 That shouldn't pose any problem in simple scenarios, but if you are
3619 trying to do something like building an extension on a different machine
3620 than the server code was built on, you may need to force use of a
3621 different sysroot path. To do that, set <varname>PG_SYSROOT</varname>,
3622 for example
3623 <programlisting>
3624 make PG_SYSROOT=<replaceable>/desired/path</replaceable> all
3625 </programlisting>
3626 To find out the appropriate path on your machine, run
3627 <programlisting>
3628 xcrun --show-sdk-path
3629 </programlisting>
3630 Note that building an extension using a different sysroot version than
3631 was used to build the core server is not really recommended; in the
3632 worst case it could result in hard-to-debug ABI inconsistencies.
3633 </para>
3634
3635 <para>
3636 You can also select a non-default sysroot path when configuring, by
3637 specifying <varname>PG_SYSROOT</varname>
3638 to <application>configure</application>:
3639 <programlisting>
3640 ./configure ... PG_SYSROOT=<replaceable>/desired/path</replaceable>
3641 </programlisting>
3642 This would primarily be useful to cross-compile for some other
3643 macOS version. There is no guarantee that the resulting executables
3644 will run on the current host.
3645 </para>
3646
3647 <para>
3648 To suppress the <option>-isysroot</option> options altogether, use
3649 <programlisting>
3650 ./configure ... PG_SYSROOT=none
3651 </programlisting>
3652 (any nonexistent pathname will work). This might be useful if you wish
3653 to build with a non-Apple compiler, but beware that that case is not
3654 tested or supported by the PostgreSQL developers.
3655 </para>
3656
3657 <para>
3658 <productname>macOS</productname>'s <quote>System Integrity
3659 Protection</quote> (SIP) feature breaks <literal>make check</literal>,
3660 because it prevents passing the needed setting
3661 of <literal>DYLD_LIBRARY_PATH</literal> down to the executables being
3662 tested. You can work around that by doing <literal>make
3663 install</literal> before <literal>make check</literal>.
3664 Most PostgreSQL developers just turn off SIP, though.
3665 </para>
3666 </sect2>
3667
3668 <sect2 id="installation-notes-mingw">
3669 <title>MinGW</title>
3670
3671 <indexterm zone="installation-notes-mingw">
3672 <primary>MinGW</primary>
3673 <secondary>installation on</secondary>
3674 </indexterm>
3675
3676 <para>
3677 PostgreSQL for Windows can be built using MinGW, a Unix-like build
3678 environment for Windows. It is recommended to use the <ulink
3679 url="https://www.msys2.org/">MSYS2</ulink> environment for this and also
3680 to install any prerequisite packages.
3681 </para>
3682
3683 <sect3 id="mingw-crash-dumps">
3684 <title>Collecting Crash Dumps</title>
3685
3686 <para>
3687 If PostgreSQL on Windows crashes, it has the ability to generate
3688 <productname>minidumps</productname> that can be used to track down the cause
3689 for the crash, similar to core dumps on Unix. These dumps can be
3690 read using the <productname>Windows Debugger Tools</productname> or using
3691 <productname>Visual Studio</productname>. To enable the generation of dumps
3692 on Windows, create a subdirectory named <filename>crashdumps</filename>
3693 inside the cluster data directory. The dumps will then be written
3694 into this directory with a unique name based on the identifier of
3695 the crashing process and the current time of the crash.
3696 </para>
3697 </sect3>
3698 </sect2>
3699
3700 <sect2 id="installation-notes-solaris">
3701 <title>Solaris</title>
3702
3703 <indexterm zone="installation-notes-solaris">
3704 <primary>Solaris</primary>
3705 <secondary>installation on</secondary>
3706 </indexterm>
3707
3708 <para>
3709 PostgreSQL is well-supported on Solaris. The more up to date your
3710 operating system, the fewer issues you will experience.
3711 </para>
3712
3713 <sect3 id="installation-notes-solaris-req-tools">
3714 <title>Required Tools</title>
3715
3716 <para>
3717 You can build with either GCC or Sun's compiler suite. For
3718 better code optimization, Sun's compiler is strongly recommended
3719 on the SPARC architecture. If
3720 you are using Sun's compiler, be careful not to select
3721 <filename>/usr/ucb/cc</filename>;
3722 use <filename>/opt/SUNWspro/bin/cc</filename>.
3723 </para>
3724
3725 <para>
3726 You can download Sun Studio
3727 from <ulink url="https://www.oracle.com/technetwork/server-storage/solarisstudio/downloads/"></ulink>.
3728 Many GNU tools are integrated into Solaris 10, or they are
3729 present on the Solaris companion CD. If you need packages for
3730 older versions of Solaris, you can find these tools
3731 at <ulink url="http://www.sunfreeware.com"></ulink>.
3732 If you prefer
3733 sources, look
3734 at <ulink url="https://www.gnu.org/prep/ftp"></ulink>.
3735 </para>
3736 </sect3>
3737
3738 <sect3 id="installation-notes-solaris-configure-complains">
3739 <title>configure Complains About a Failed Test Program</title>
3740
3741 <para>
3742 If <command>configure</command> complains about a failed test
3743 program, this is probably a case of the run-time linker being
3744 unable to find some library, probably libz, libreadline or some
3745 other non-standard library such as libssl. To point it to the
3746 right location, set the <envar>LDFLAGS</envar> environment
3747 variable on the <command>configure</command> command line, e.g.,
3748 <programlisting>
3749 configure ... LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib"
3750 </programlisting>
3751 See
3752 the <citerefentry><refentrytitle>ld</refentrytitle><manvolnum>1</manvolnum></citerefentry>
3753 man page for more information.
3754 </para>
3755 </sect3>
3756
3757 <sect3 id="installation-notes-solaris-comp-opt-perf">
3758 <title>Compiling for Optimal Performance</title>
3759
3760 <para>
3761 On the SPARC architecture, Sun Studio is strongly recommended for
3762 compilation. Try using the <option>-xO5</option> optimization
3763 flag to generate significantly faster binaries. Do not use any
3764 flags that modify behavior of floating-point operations
3765 and <varname>errno</varname> processing (e.g.,
3766 <option>-fast</option>).
3767 </para>
3768
3769 <para>
3770 If you do not have a reason to use 64-bit binaries on SPARC,
3771 prefer the 32-bit version. The 64-bit operations are slower and
3772 64-bit binaries are slower than the 32-bit variants. On the
3773 other hand, 32-bit code on the AMD64 CPU family is not native,
3774 so 32-bit code is significantly slower on that CPU family.
3775 </para>
3776 </sect3>
3777
3778 <sect3 id="installation-notes-solaris-using-dtrace">
3779 <title>Using DTrace for Tracing PostgreSQL</title>
3780
3781 <para>
3782 Yes, using DTrace is possible. See <xref linkend="dynamic-trace"/> for
3783 further information.
3784 </para>
3785
3786 <para>
3787 If you see the linking of the <command>postgres</command> executable abort with an
3788 error message like:
3789 <screen>
3790 Undefined first referenced
3791 symbol in file
3792 AbortTransaction utils/probes.o
3793 CommitTransaction utils/probes.o
3794 ld: fatal: Symbol referencing errors. No output written to postgres
3795 collect2: ld returned 1 exit status
3796 make: *** [postgres] Error 1
3797 </screen>
3798 your DTrace installation is too old to handle probes in static
3799 functions. You need Solaris 10u4 or newer to use DTrace.
3800 </para>
3801 </sect3>
3802 </sect2>
3803
3804 <sect2 id="installation-notes-visual-studio">
3805 <title>Visual Studio</title>
3806
3807 <indexterm zone="installation-notes-visual-studio">
3808 <primary>Visual Studio</primary>
3809 <secondary>installation on</secondary>
3810 </indexterm>
3811
3812 <para>
3813 It is recommended that most users download the binary distribution for
3814 Windows, available as a graphical installer package from the
3815 <productname>PostgreSQL</productname> website at
3816 <ulink url="https://www.postgresql.org/download/"></ulink>. Building from
3817 source is only intended for people developing
3818 <productname>PostgreSQL</productname> or extensions.
3819 </para>
3820
3821 <para>
3822 PostgreSQL for Windows with Visual Studio can be built using Meson, as
3823 described in <xref linkend="install-meson"/>.
3824 The native Windows port requires a 32 or 64-bit version of Windows
3825 10 or later.
3826 </para>
3827
3828 <para>
3829 Native builds of <application>psql</application> don't support command
3830 line editing. The <productname>Cygwin</productname> build does support
3831 command line editing, so it should be used where psql is needed for
3832 interactive use on <productname>Windows</productname>.
3833 </para>
3834
3835 <para>
3836 PostgreSQL can be built using the Visual C++ compiler suite from Microsoft.
3837 These compilers can be either from <productname>Visual Studio</productname>,
3838 <productname>Visual Studio Express</productname> or some versions of the
3839 <productname>Microsoft Windows SDK</productname>. If you do not already have a
3840 <productname>Visual Studio</productname> environment set up, the easiest
3841 ways are to use the compilers from
3842 <productname>Visual Studio 2022</productname> or those in the
3843 <productname>Windows SDK 10</productname>, which are both free downloads
3844 from Microsoft.
3845 </para>
3846
3847 <para>
3848 Both 32-bit and 64-bit builds are possible with the Microsoft Compiler suite.
3849 32-bit PostgreSQL builds are possible with
3850 <productname>Visual Studio 2015</productname> to
3851 <productname>Visual Studio 2022</productname>,
3852 as well as standalone Windows SDK releases 10 and above.
3853 64-bit PostgreSQL builds are supported with
3854 <productname>Microsoft Windows SDK</productname> version 10 and above or
3855 <productname>Visual Studio 2015</productname> and above.
3856 <!--
3857 For 2015 requirements:
3858 https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2015-sysrequirements-vs
3859 For 2017 requirements:
3860 https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2017-system-requirements-vs
3861 For 2019 requirements:
3862 https://docs.microsoft.com/en-us/visualstudio/releases/2019/system-requirements
3863 For 2022 requirements:
3864 https://docs.microsoft.com/en-us/visualstudio/releases/2022/system-requirements
3865 -->
3866 </para>
3867
3868 <para>
3869 If your build environment doesn't ship with a supported version of the
3870 <productname>Microsoft Windows SDK</productname> it is recommended
3871 that you upgrade to the latest version (currently version 10), available
3872 for download from <ulink url="https://www.microsoft.com/download"></ulink>.
3873 </para>
3874
3875 <para>
3876 You must always include the
3877 <application>Windows Headers and Libraries</application> part of the SDK.
3878 If you install a <productname>Windows SDK</productname>
3879 including the <application>Visual C++ Compilers</application>,
3880 you don't need <productname>Visual Studio</productname> to build.
3881 Note that as of Version 8.0a the Windows SDK no longer ships with a
3882 complete command-line build environment.
3883 </para>
3884
3885 <sect3 id="windows-requirements">
3886 <title>Requirements</title>
3887 <para>
3888 The following additional products are required to build
3889 <productname>PostgreSQL</productname> on Windows.
3890
3891 <variablelist>
3892 <varlistentry>
3893 <term><productname>Strawberry Perl</productname></term>
3894 <listitem><para>
3895 Strawberry Perl is required to run the build generation scripts. MinGW
3896 or Cygwin Perl will not work. It must also be present in the PATH.
3897 Binaries can be downloaded from
3898 <ulink url="https://strawberryperl.com"></ulink>.
3899 </para></listitem>
3900 </varlistentry>
3901
3902 <varlistentry>
3903 <term><productname>Bison</productname> and
3904 <productname>Flex</productname></term>
3905 <listitem>
3906 <para>
3907 Binaries for <productname>Bison</productname> and
3908 <productname>Flex</productname> can be downloaded from <ulink
3909 url="https://github.com/lexxmark/winflexbison"></ulink>.
3910 </para>
3911 </listitem>
3912 </varlistentry>
3913 </variablelist>
3914 </para>
3915
3916 <para>
3917 The following additional products are not required to get started,
3918 but are required to build the complete package.
3919
3920 <variablelist>
3921 <varlistentry>
3922 <term><productname>Magicsplat Tcl</productname></term>
3923 <listitem><para>
3924 Required for building <application>PL/Tcl</application>.
3925 Binaries can be downloaded from
3926 <ulink url="https://www.magicsplat.com/tcl-installer/index.html"></ulink>.
3927 </para></listitem>
3928 </varlistentry>
3929
3930 <varlistentry>
3931 <term><productname>Diff</productname></term>
3932 <listitem><para>
3933 Diff is required to run the regression tests, and can be downloaded
3934 from <ulink url="http://gnuwin32.sourceforge.net"></ulink>.
3935 </para></listitem>
3936 </varlistentry>
3937
3938 <varlistentry>
3939 <term><productname>Gettext</productname></term>
3940 <listitem><para>
3941 Gettext is required to build with NLS support, and can be downloaded
3942 from <ulink url="http://gnuwin32.sourceforge.net"></ulink>. Note that binaries,
3943 dependencies and developer files are all needed.
3944 </para></listitem>
3945 </varlistentry>
3946
3947 <varlistentry>
3948 <term><productname>MIT Kerberos</productname></term>
3949 <listitem><para>
3950 Required for GSSAPI authentication support. MIT Kerberos can be
3951 downloaded from
3952 <ulink url="https://web.mit.edu/Kerberos/dist/index.html"></ulink>.
3953 </para></listitem>
3954 </varlistentry>
3955
3956 <varlistentry>
3957 <term><productname>libxml2</productname> and
3958 <productname>libxslt</productname></term>
3959 <listitem><para>
3960 Required for XML support. Binaries can be downloaded from
3961 <ulink url="https://zlatkovic.com/pub/libxml"></ulink> or source from
3962 <ulink url="http://xmlsoft.org"></ulink>. Note that libxml2 requires iconv,
3963 which is available from the same download location.
3964 </para></listitem>
3965 </varlistentry>
3966
3967 <varlistentry>
3968 <term><productname>LZ4</productname></term>
3969 <listitem><para>
3970 Required for supporting <productname>LZ4</productname> compression.
3971 Binaries and source can be downloaded from
3972 <ulink url="https://github.com/lz4/lz4/releases"></ulink>.
3973 </para></listitem>
3974 </varlistentry>
3975
3976 <varlistentry>
3977 <term><productname>Zstandard</productname></term>
3978 <listitem><para>
3979 Required for supporting <productname>Zstandard</productname> compression.
3980 Binaries and source can be downloaded from
3981 <ulink url="https://github.com/facebook/zstd/releases"></ulink>.
3982 </para></listitem>
3983 </varlistentry>
3984
3985 <varlistentry>
3986 <term><productname>OpenSSL</productname></term>
3987 <listitem><para>
3988 Required for SSL support. Binaries can be downloaded from
3989 <ulink url="https://slproweb.com/products/Win32OpenSSL.html"></ulink>
3990 or source from <ulink url="https://www.openssl.org"></ulink>.
3991 </para></listitem>
3992 </varlistentry>
3993
3994 <varlistentry>
3995 <term><productname>ossp-uuid</productname></term>
3996 <listitem><para>
3997 Required for UUID-OSSP support (contrib only). Source can be
3998 downloaded from
3999 <ulink url="http://www.ossp.org/pkg/lib/uuid/"></ulink>.
4000 </para></listitem>
4001 </varlistentry>
4002
4003 <varlistentry>
4004 <term><productname>Python</productname></term>
4005 <listitem><para>
4006 Required for building <application>PL/Python</application>. Binaries can
4007 be downloaded from <ulink url="https://www.python.org"></ulink>.
4008 </para></listitem>
4009 </varlistentry>
4010
4011 <varlistentry>
4012 <term><productname>zlib</productname></term>
4013 <listitem><para>
4014 Required for compression support in <application>pg_dump</application>
4015 and <application>pg_restore</application>. Binaries can be downloaded
4016 from <ulink url="https://www.zlib.net"></ulink>.
4017 </para></listitem>
4018 </varlistentry>
4019
4020 </variablelist>
4021 </para>
4022 </sect3>
4023
4024 <sect3 id="install-windows-full-64-bit">
4025 <title>Special Considerations for 64-Bit Windows</title>
4026 <para>
4027 PostgreSQL will only build for the x64 architecture on 64-bit Windows.
4028 </para>
4029 <para>
4030 Mixing 32- and 64-bit versions in the same build tree is not supported.
4031 The build system will automatically detect if it's running in a 32- or
4032 64-bit environment, and build PostgreSQL accordingly. For this reason, it
4033 is important to start the correct command prompt before building.
4034 </para>
4035 <para>
4036 To use a server-side third party library such as <productname>Python</productname> or
4037 <productname>OpenSSL</productname>, this library <emphasis>must</emphasis> also be
4038 64-bit. There is no support for loading a 32-bit library in a 64-bit
4039 server. Several of the third party libraries that PostgreSQL supports may
4040 only be available in 32-bit versions, in which case they cannot be used with
4041 64-bit PostgreSQL.
4042 </para>
4043 </sect3>
4044
4045 <sect3 id="windows-crash-dumps">
4046 <title>Collecting Crash Dumps</title>
4047
4048 <para>
4049 If PostgreSQL on Windows crashes, it has the ability to generate
4050 <productname>minidumps</productname> that can be used to track down the cause
4051 for the crash, similar to core dumps on Unix. These dumps can be
4052 read using the <productname>Windows Debugger Tools</productname> or using
4053 <productname>Visual Studio</productname>. To enable the generation of dumps
4054 on Windows, create a subdirectory named <filename>crashdumps</filename>
4055 inside the cluster data directory. The dumps will then be written
4056 into this directory with a unique name based on the identifier of
4057 the crashing process and the current time of the crash.
4058 </para>
4059 </sect3>
4060 </sect2>
4061 </sect1>
4062
4063 </chapter>