1 2PostgreSQL Installation from Source Code 3 4------------------------------------------------------------------------ 5 6This document describes the installation of PostgreSQL using this source 7code distribution. 8 9If you are building PostgreSQL for Microsoft Windows, read this document 10if you intend to build with MinGW or Cygwin; but if you intend to build 11with Microsoft's Visual C++, see the main documentation instead. 12 13------------------------------------------------------------------------ 14 15 16Short Version 17 18 ./configure 19 make 20 su 21 make install 22 adduser postgres 23 mkdir /usr/local/pgsql/data 24 chown postgres /usr/local/pgsql/data 25 su - postgres 26 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data 27 /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start 28 /usr/local/pgsql/bin/createdb test 29 /usr/local/pgsql/bin/psql test 30 31The long version is the rest of this document. 32 33------------------------------------------------------------------------ 34 35 36Requirements 37 38In general, a modern Unix-compatible platform should be able to run 39PostgreSQL. The platforms that had received specific testing at the time 40of release are described in the section called "Supported Platforms" 41below. 42 43The following software packages are required for building PostgreSQL: 44 45- GNU make version 3.80 or newer is required; other make programs or 46 older GNU make versions will *not* work. (GNU make is sometimes 47 installed under the name "gmake".) To test for GNU make enter: 48 49 make --version 50 51- You need an ISO/ANSI C compiler (at least C99-compliant). Recent 52 versions of GCC are recommended, but PostgreSQL is known to build 53 using a wide variety of compilers from different vendors. 54 55- tar is required to unpack the source distribution, in addition to 56 either gzip or bzip2. 57 58- The GNU Readline library is used by default. It allows psql (the 59 PostgreSQL command line SQL interpreter) to remember each command 60 you type, and allows you to use arrow keys to recall and edit 61 previous commands. This is very helpful and is strongly recommended. 62 If you don't want to use it then you must specify the 63 "--without-readline" option to "configure". As an alternative, you 64 can often use the BSD-licensed "libedit" library, originally 65 developed on NetBSD. The "libedit" library is GNU 66 Readline-compatible and is used if "libreadline" is not found, or if 67 "--with-libedit-preferred" is used as an option to "configure". If 68 you are using a package-based Linux distribution, be aware that you 69 need both the readline and readline-devel packages, if those are 70 separate in your distribution. 71 72- The zlib compression library is used by default. If you don't want 73 to use it then you must specify the "--without-zlib" option to 74 "configure". Using this option disables support for compressed 75 archives in pg_dump and pg_restore. 76 77The following packages are optional. They are not required in the 78default configuration, but they are needed when certain build options 79are enabled, as explained below: 80 81- To build the server programming language PL/Perl you need a full 82 Perl installation, including the "libperl" library and the header 83 files. The minimum required version is Perl 5.8.3. Since PL/Perl 84 will be a shared library, the "libperl" library must be a shared 85 library also on most platforms. This appears to be the default in 86 recent Perl versions, but it was not in earlier versions, and in any 87 case it is the choice of whomever installed Perl at your site. 88 "configure" will fail if building PL/Perl is selected but it cannot 89 find a shared "libperl". In that case, you will have to rebuild and 90 install Perl manually to be able to build PL/Perl. During the 91 configuration process for Perl, request a shared library. 92 93 If you intend to make more than incidental use of PL/Perl, you 94 should ensure that the Perl installation was built with the 95 usemultiplicity option enabled (perl -V will show whether this is 96 the case). 97 98- To build the PL/Python server programming language, you need a 99 Python installation with the header files and the distutils module. 100 The minimum required version is Python 2.6. Python 3 is supported if 101 it's version 3.1 or later; but see the PL/Python documentation when 102 using Python 3. 103 104 Since PL/Python will be a shared library, the "libpython" library 105 must be a shared library also on most platforms. This is not the 106 case in a default Python installation built from source, but a 107 shared library is available in many operating system distributions. 108 "configure" will fail if building PL/Python is selected but it 109 cannot find a shared "libpython". That might mean that you either 110 have to install additional packages or rebuild (part of) your Python 111 installation to provide this shared library. When building from 112 source, run Python's configure with the --enable-shared flag. 113 114- To build the PL/Tcl procedural language, you of course need a Tcl 115 installation. The minimum required version is Tcl 8.4. 116 117- To enable Native Language Support (NLS), that is, the ability to 118 display a program's messages in a language other than English, you 119 need an implementation of the Gettext API. Some operating systems 120 have this built-in (e.g., Linux, NetBSD, Solaris), for other systems 121 you can download an add-on package from 122 http://www.gnu.org/software/gettext/. If you are using the Gettext 123 implementation in the GNU C library then you will additionally need 124 the GNU Gettext package for some utility programs. For any of the 125 other implementations you will not need it. 126 127- You need OpenSSL, if you want to support encrypted client 128 connections. OpenSSL is also required for random number generation 129 on platforms that do not have "/dev/urandom" (except Windows). The 130 minimum version required is 1.0.1. 131 132- You need Kerberos, OpenLDAP, and/or PAM, if you want to support 133 authentication using those services. 134 135- To build the PostgreSQL documentation, there is a separate set of 136 requirements; see the main documentation's appendix on 137 documentation. 138 139If you are building from a Git tree instead of using a released source 140package, or if you want to do server development, you also need the 141following packages: 142 143- Flex and Bison are needed to build from a Git checkout, or if you 144 changed the actual scanner and parser definition files. If you need 145 them, be sure to get Flex 2.5.31 or later and Bison 1.875 or later. 146 Other lex and yacc programs cannot be used. 147 148- Perl 5.8.3 or later is needed to build from a Git checkout, or if 149 you changed the input files for any of the build steps that use Perl 150 scripts. If building on Windows you will need Perl in any case. Perl 151 is also required to run some test suites. 152 153If you need to get a GNU package, you can find it at your local GNU 154mirror site (see https://www.gnu.org/prep/ftp for a list) or at 155ftp://ftp.gnu.org/gnu/. 156 157Also check that you have sufficient disk space. You will need about 350 158MB for the source tree during compilation and about 60 MB for the 159installation directory. An empty database cluster takes about 40 MB; 160databases take about five times the amount of space that a flat text 161file with the same data would take. If you are going to run the 162regression tests you will temporarily need up to an extra 300 MB. Use 163the "df" command to check free disk space. 164 165------------------------------------------------------------------------ 166 167 168Installation Procedure 169 1701. CONFIGURATION 171 172 The first step of the installation procedure is to configure the 173 source tree for your system and choose the options you would like. 174 This is done by running the "configure" script. For a default 175 installation simply enter: 176 177 ./configure 178 179 This script will run a number of tests to determine values for 180 various system dependent variables and detect any quirks of your 181 operating system, and finally will create several files in the build 182 tree to record what it found. 183 184 You can also run "configure" in a directory outside the source tree, 185 and then build there, if you want to keep the build directory 186 separate from the original source files. This procedure is called a 187 VPATH build. Here's how: 188 189 mkdir build_dir 190 cd build_dir 191 /path/to/source/tree/configure [options go here] 192 make 193 194 The default configuration will build the server and utilities, as 195 well as all client applications and interfaces that require only a C 196 compiler. All files will be installed under "/usr/local/pgsql" by 197 default. 198 199 You can customize the build and installation process by supplying 200 one or more command line options to "configure". Typically you would 201 customize the install location, or the set of optional features that 202 are built. "configure" has a large number of options, which are 203 described in the section called "configure Options". 204 205 Also, "configure" responds to certain environment variables, as 206 described in the section called "configure Environment Variables". 207 These provide additional ways to customize the configuration. 208 2092. BUILD 210 211 To start the build, type either of: 212 213 make 214 make all 215 216 (Remember to use GNU make.) The build will take a few minutes 217 depending on your hardware. 218 219 If you want to build everything that can be built, including the 220 documentation (HTML and man pages), and the additional modules 221 ("contrib"), type instead: 222 223 make world 224 225 If you want to build everything that can be built, including the 226 additional modules ("contrib"), but without the documentation, type 227 instead: 228 229 make world-bin 230 231 If you want to invoke the build from another makefile rather than 232 manually, you must unset MAKELEVEL or set it to zero, for instance 233 like this: 234 235 build-postgresql: 236 $(MAKE) -C postgresql MAKELEVEL=0 all 237 238 Failure to do that can lead to strange error messages, typically 239 about missing header files. 240 2413. REGRESSION TESTS 242 243 If you want to test the newly built server before you install it, 244 you can run the regression tests at this point. The regression tests 245 are a test suite to verify that PostgreSQL runs on your machine in 246 the way the developers expected it to. Type: 247 248 make check 249 250 (This won't work as root; do it as an unprivileged user.) See the 251 file "src/test/regress/README" and the documentation for detailed 252 information about interpreting the test results. You can repeat this 253 test at any later time by issuing the same command. 254 2554. INSTALLING THE FILES 256 257 NOTE: 258 259 If you are upgrading an existing system be sure to read the 260 documentation, which has instructions about upgrading a cluster. 261 262 To install PostgreSQL enter: 263 264 make install 265 266 This will install files into the directories that were specified in 267 Step 1. Make sure that you have appropriate permissions to write 268 into that area. Normally you need to do this step as root. 269 Alternatively, you can create the target directories in advance and 270 arrange for appropriate permissions to be granted. 271 272 To install the documentation (HTML and man pages), enter: 273 274 make install-docs 275 276 If you built the world above, type instead: 277 278 make install-world 279 280 This also installs the documentation. 281 282 If you built the world without the documentation above, type 283 instead: 284 285 make install-world-bin 286 287 You can use make install-strip instead of make install to strip the 288 executable files and libraries as they are installed. This will save 289 some space. If you built with debugging support, stripping will 290 effectively remove the debugging support, so it should only be done 291 if debugging is no longer needed. install-strip tries to do a 292 reasonable job saving space, but it does not have perfect knowledge 293 of how to strip every unneeded byte from an executable file, so if 294 you want to save all the disk space you possibly can, you will have 295 to do manual work. 296 297 The standard installation provides all the header files needed for 298 client application development as well as for server-side program 299 development, such as custom functions or data types written in C. 300 (Prior to PostgreSQL 8.0, a separate make install-all-headers 301 command was needed for the latter, but this step has been folded 302 into the standard install.) 303 304 CLIENT-ONLY INSTALLATION: If you want to install only the client 305 applications and interface libraries, then you can use these 306 commands: 307 308 make -C src/bin install 309 make -C src/include install 310 make -C src/interfaces install 311 make -C doc install 312 313 "src/bin" has a few binaries for server-only use, but they are 314 small. 315 316UNINSTALLATION: To undo the installation use the command "make 317uninstall". However, this will not remove any created directories. 318 319CLEANING: After the installation you can free disk space by removing 320the built files from the source tree with the command "make clean". This 321will preserve the files made by the "configure" program, so that you can 322rebuild everything with "make" later on. To reset the source tree to the 323state in which it was distributed, use "make distclean". If you are 324going to build for several platforms within the same source tree you 325must do this and re-configure for each platform. (Alternatively, use a 326separate build tree for each platform, so that the source tree remains 327unmodified.) 328 329If you perform a build and then discover that your "configure" options 330were wrong, or if you change anything that "configure" investigates (for 331example, software upgrades), then it's a good idea to do "make 332distclean" before reconfiguring and rebuilding. Without this, your 333changes in configuration choices might not propagate everywhere they 334need to. 335 336------------------------------------------------------------------------ 337 338configure Options 339 340"configure"'s command line options are explained below. This list is not 341exhaustive (use ./configure --help to get one that is). The options not 342covered here are meant for advanced use-cases such as cross-compilation, 343and are documented in the standard Autoconf documentation. 344 345------------------------------------------------------------------------ 346 347Installation Locations 348 349These options control where make install will put the files. The 350"--prefix" option is sufficient for most cases. If you have special 351needs, you can customize the installation subdirectories with the other 352options described in this section. Beware however that changing the 353relative locations of the different subdirectories may render the 354installation non-relocatable, meaning you won't be able to move it after 355installation. (The man and doc locations are not affected by this 356restriction.) For relocatable installs, you might want to use the 357--disable-rpath option described later. 358 359--prefix=PREFIX 360 361 Install all files under the directory "PREFIX" instead of 362 "/usr/local/pgsql". The actual files will be installed into various 363 subdirectories; no files will ever be installed directly into the 364 "PREFIX" directory. 365 366--exec-prefix=EXEC-PREFIX 367 368 You can install architecture-dependent files under a different 369 prefix, "EXEC-PREFIX", than what "PREFIX" was set to. This can be 370 useful to share architecture-independent files between hosts. If you 371 omit this, then "EXEC-PREFIX" is set equal to "PREFIX" and both 372 architecture-dependent and independent files will be installed under 373 the same tree, which is probably what you want. 374 375--bindir=DIRECTORY 376 377 Specifies the directory for executable programs. The default is 378 "EXEC-PREFIX/bin", which normally means "/usr/local/pgsql/bin". 379 380--sysconfdir=DIRECTORY 381 382 Sets the directory for various configuration files, "PREFIX/etc" by 383 default. 384 385--libdir=DIRECTORY 386 387 Sets the location to install libraries and dynamically loadable 388 modules. The default is "EXEC-PREFIX/lib". 389 390--includedir=DIRECTORY 391 392 Sets the directory for installing C and C++ header files. The 393 default is "PREFIX/include". 394 395--datarootdir=DIRECTORY 396 397 Sets the root directory for various types of read-only data files. 398 This only sets the default for some of the following options. The 399 default is "PREFIX/share". 400 401--datadir=DIRECTORY 402 403 Sets the directory for read-only data files used by the installed 404 programs. The default is "DATAROOTDIR". Note that this has nothing 405 to do with where your database files will be placed. 406 407--localedir=DIRECTORY 408 409 Sets the directory for installing locale data, in particular message 410 translation catalog files. The default is "DATAROOTDIR/locale". 411 412--mandir=DIRECTORY 413 414 The man pages that come with PostgreSQL will be installed under this 415 directory, in their respective "manx" subdirectories. The default is 416 "DATAROOTDIR/man". 417 418--docdir=DIRECTORY 419 420 Sets the root directory for installing documentation files, except 421 "man" pages. This only sets the default for the following options. 422 The default value for this option is "DATAROOTDIR/doc/postgresql". 423 424--htmldir=DIRECTORY 425 426 The HTML-formatted documentation for PostgreSQL will be installed 427 under this directory. The default is "DATAROOTDIR". 428 429NOTE: 430 431Care has been taken to make it possible to install PostgreSQL into 432shared installation locations (such as "/usr/local/include") without 433interfering with the namespace of the rest of the system. First, the 434string "/postgresql" is automatically appended to datadir, sysconfdir, 435and docdir, unless the fully expanded directory name already contains 436the string "postgres" or "pgsql". For example, if you choose 437"/usr/local" as prefix, the documentation will be installed in 438"/usr/local/doc/postgresql", but if the prefix is "/opt/postgres", then 439it will be in "/opt/postgres/doc". The public C header files of the 440client interfaces are installed into includedir and are namespace-clean. 441The internal header files and the server header files are installed into 442private directories under includedir. See the documentation of each 443interface for information about how to access its header files. Finally, 444a private subdirectory will also be created, if appropriate, under 445libdir for dynamically loadable modules. 446 447------------------------------------------------------------------------ 448 449PostgreSQL Features 450 451The options described in this section enable building of various 452PostgreSQL features that are not built by default. Most of these are 453non-default only because they require additional software, as described 454in the section called "Requirements". 455 456--enable-nls[=LANGUAGES] 457 458 Enables Native Language Support (NLS), that is, the ability to 459 display a program's messages in a language other than English. 460 "LANGUAGES" is an optional space-separated list of codes of the 461 languages that you want supported, for example --enable-nls='de fr'. 462 (The intersection between your list and the set of actually provided 463 translations will be computed automatically.) If you do not specify 464 a list, then all available translations are installed. 465 466 To use this option, you will need an implementation of the Gettext 467 API. 468 469--with-perl 470 471 Build the PL/Perl server-side language. 472 473--with-python 474 475 Build the PL/Python server-side language. 476 477--with-tcl 478 479 Build the PL/Tcl server-side language. 480 481--with-tclconfig=DIRECTORY 482 483 Tcl installs the file "tclConfig.sh", which contains configuration 484 information needed to build modules interfacing to Tcl. This file is 485 normally found automatically at a well-known location, but if you 486 want to use a different version of Tcl you can specify the directory 487 in which to look for "tclConfig.sh". 488 489--with-icu 490 491 Build with support for the ICU library, enabling use of ICU 492 collation features. This requires the ICU4C package to be installed. 493 The minimum required version of ICU4C is currently 4.2. 494 495 By default, pkg-config will be used to find the required compilation 496 options. This is supported for ICU4C version 4.6 and later. For 497 older versions, or if pkg-config is not available, the variables 498 ICU_CFLAGS and ICU_LIBS can be specified to "configure", like in 499 this example: 500 501 ./configure ... --with-icu ICU_CFLAGS='-I/some/where/include' ICU_LIBS='-L/some/where/lib -licui18n -licuuc -licudata' 502 503 (If ICU4C is in the default search path for the compiler, then you 504 still need to specify nonempty strings in order to avoid use of 505 pkg-config, for example, ICU_CFLAGS=' '.) 506 507--with-llvm 508 509 Build with support for LLVM based JIT compilation. This requires the 510 LLVM library to be installed. The minimum required version of LLVM 511 is currently 3.9. 512 513 "llvm-config" will be used to find the required compilation options. 514 "llvm-config", and then "llvm-config-$major-$minor" for all 515 supported versions, will be searched for in your PATH. If that would 516 not yield the desired program, use LLVM_CONFIG to specify a path to 517 the correct "llvm-config". For example 518 519 ./configure ... --with-llvm LLVM_CONFIG='/path/to/llvm/bin/llvm-config' 520 521 LLVM support requires a compatible "clang" compiler (specified, if 522 necessary, using the CLANG environment variable), and a working C++ 523 compiler (specified, if necessary, using the CXX environment 524 variable). 525 526--with-openssl 527 528 Build with support for SSL (encrypted) connections. This requires 529 the OpenSSL package to be installed. "configure" will check for the 530 required header files and libraries to make sure that your OpenSSL 531 installation is sufficient before proceeding. 532 533--with-gssapi 534 535 Build with support for GSSAPI authentication. On many systems, the 536 GSSAPI system (usually a part of the Kerberos installation) is not 537 installed in a location that is searched by default (e.g., 538 "/usr/include", "/usr/lib"), so you must use the options 539 "--with-includes" and "--with-libraries" in addition to this option. 540 "configure" will check for the required header files and libraries 541 to make sure that your GSSAPI installation is sufficient before 542 proceeding. 543 544--with-ldap 545 546 Build with LDAP support for authentication and connection parameter 547 lookup (see the documentation about client authentication and libpq 548 for more information). On Unix, this requires the OpenLDAP package 549 to be installed. On Windows, the default WinLDAP library is used. 550 "configure" will check for the required header files and libraries 551 to make sure that your OpenLDAP installation is sufficient before 552 proceeding. 553 554--with-pam 555 556 Build with PAM (Pluggable Authentication Modules) support. 557 558--with-bsd-auth 559 560 Build with BSD Authentication support. (The BSD Authentication 561 framework is currently only available on OpenBSD.) 562 563--with-systemd 564 565 Build with support for systemd service notifications. This improves 566 integration if the server is started under systemd but has no impact 567 otherwise. libsystemd and the associated header files need to be 568 installed to use this option. 569 570--with-bonjour 571 572 Build with support for Bonjour automatic service discovery. This 573 requires Bonjour support in your operating system. Recommended on 574 macOS. 575 576--with-uuid=LIBRARY 577 578 Build the uuid-ossp module (which provides functions to generate 579 UUIDs), using the specified UUID library. "LIBRARY" must be one of: 580 581 - "bsd" to use the UUID functions found in FreeBSD, NetBSD, and 582 some other BSD-derived systems 583 584 - "e2fs" to use the UUID library created by the e2fsprogs project; 585 this library is present in most Linux systems and in macOS, and 586 can be obtained for other platforms as well 587 588 - "ossp" to use the OSSP UUID library 589 590--with-ossp-uuid 591 592 Obsolete equivalent of --with-uuid=ossp. 593 594--with-libxml 595 596 Build with libxml2, enabling SQL/XML support. Libxml2 version 2.6.23 597 or later is required for this feature. 598 599 To detect the required compiler and linker options, PostgreSQL will 600 query "pkg-config", if that is installed and knows about libxml2. 601 Otherwise the program "xml2-config", which is installed by libxml2, 602 will be used if it is found. Use of "pkg-config" is preferred, 603 because it can deal with multi-architecture installations better. 604 605 To use a libxml2 installation that is in an unusual location, you 606 can set "pkg-config"-related environment variables (see its 607 documentation), or set the environment variable XML2_CONFIG to point 608 to the "xml2-config" program belonging to the libxml2 installation, 609 or set the variables XML2_CFLAGS and XML2_LIBS. (If "pkg-config" is 610 installed, then to override its idea of where libxml2 is you must 611 either set XML2_CONFIG or set both XML2_CFLAGS and XML2_LIBS to 612 nonempty strings.) 613 614--with-libxslt 615 616 Build with libxslt, enabling the xml2 module to perform XSL 617 transformations of XML. "--with-libxml" must be specified as well. 618 619------------------------------------------------------------------------ 620 621Anti-Features 622 623The options described in this section allow disabling certain PostgreSQL 624features that are built by default, but which might need to be turned 625off if the required software or system features are not available. Using 626these options is not recommended unless really necessary. 627 628--without-readline 629 630 Prevents use of the Readline library (and libedit as well). This 631 option disables command-line editing and history in psql. 632 633--with-libedit-preferred 634 635 Favors the use of the BSD-licensed libedit library rather than 636 GPL-licensed Readline. This option is significant only if you have 637 both libraries installed; the default in that case is to use 638 Readline. 639 640--without-zlib 641 642 Prevents use of the Zlib library. This disables support for 643 compressed archives in pg_dump and pg_restore. 644 645--disable-spinlocks 646 647 Allow the build to succeed even if PostgreSQL has no CPU spinlock 648 support for the platform. The lack of spinlock support will result 649 in very poor performance; therefore, this option should only be used 650 if the build aborts and informs you that the platform lacks spinlock 651 support. If this option is required to build PostgreSQL on your 652 platform, please report the problem to the PostgreSQL developers. 653 654--disable-atomics 655 656 Disable use of CPU atomic operations. This option does nothing on 657 platforms that lack such operations. On platforms that do have them, 658 this will result in poor performance. This option is only useful for 659 debugging or making performance comparisons. 660 661--disable-thread-safety 662 663 Disable the thread-safety of client libraries. This prevents 664 concurrent threads in libpq and ECPG programs from safely 665 controlling their private connection handles. Use this only on 666 platforms with deficient threading support. 667 668------------------------------------------------------------------------ 669 670Build Process Details 671 672--with-includes=DIRECTORIES 673 674 "DIRECTORIES" is a colon-separated list of directories that will be 675 added to the list the compiler searches for header files. If you 676 have optional packages (such as GNU Readline) installed in a 677 non-standard location, you have to use this option and probably also 678 the corresponding "--with-libraries" option. 679 680 Example: --with-includes=/opt/gnu/include:/usr/sup/include. 681 682--with-libraries=DIRECTORIES 683 684 "DIRECTORIES" is a colon-separated list of directories to search for 685 libraries. You will probably have to use this option (and the 686 corresponding "--with-includes" option) if you have packages 687 installed in non-standard locations. 688 689 Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib. 690 691--with-system-tzdata=DIRECTORY 692 693 PostgreSQL includes its own time zone database, which it requires 694 for date and time operations. This time zone database is in fact 695 compatible with the IANA time zone database provided by many 696 operating systems such as FreeBSD, Linux, and Solaris, so it would 697 be redundant to install it again. When this option is used, the 698 system-supplied time zone database in "DIRECTORY" is used instead of 699 the one included in the PostgreSQL source distribution. "DIRECTORY" 700 must be specified as an absolute path. "/usr/share/zoneinfo" is a 701 likely directory on some operating systems. Note that the 702 installation routine will not detect mismatching or erroneous time 703 zone data. If you use this option, you are advised to run the 704 regression tests to verify that the time zone data you have pointed 705 to works correctly with PostgreSQL. 706 707 This option is mainly aimed at binary package distributors who know 708 their target operating system well. The main advantage of using this 709 option is that the PostgreSQL package won't need to be upgraded 710 whenever any of the many local daylight-saving time rules change. 711 Another advantage is that PostgreSQL can be cross-compiled more 712 straightforwardly if the time zone database files do not need to be 713 built during the installation. 714 715--with-extra-version=STRING 716 717 Append "STRING" to the PostgreSQL version number. You can use this, 718 for example, to mark binaries built from unreleased Git snapshots or 719 containing custom patches with an extra version string, such as a 720 "git describe" identifier or a distribution package release number. 721 722--disable-rpath 723 724 Do not mark PostgreSQL's executables to indicate that they should 725 search for shared libraries in the installation's library directory 726 (see "--libdir"). On most platforms, this marking uses an absolute 727 path to the library directory, so that it will be unhelpful if you 728 relocate the installation later. However, you will then need to 729 provide some other way for the executables to find the shared 730 libraries. Typically this requires configuring the operating 731 system's dynamic linker to search the library directory; see the 732 section called "Shared Libraries" for more detail. 733 734------------------------------------------------------------------------ 735 736Miscellaneous 737 738It's fairly common, particularly for test builds, to adjust the default 739port number with "--with-pgport". The other options in this section are 740recommended only for advanced users. 741 742--with-pgport=NUMBER 743 744 Set "NUMBER" as the default port number for server and clients. The 745 default is 5432. The port can always be changed later on, but if you 746 specify it here then both server and clients will have the same 747 default compiled in, which can be very convenient. Usually the only 748 good reason to select a non-default value is if you intend to run 749 multiple PostgreSQL servers on the same machine. 750 751--with-krb-srvnam=NAME 752 753 The default name of the Kerberos service principal used by GSSAPI. 754 postgres is the default. There's usually no reason to change this 755 unless you are building for a Windows environment, in which case it 756 must be set to upper case POSTGRES. 757 758--with-segsize=SEGSIZE 759 760 Set the segment size, in gigabytes. Large tables are divided into 761 multiple operating-system files, each of size equal to the segment 762 size. This avoids problems with file size limits that exist on many 763 platforms. The default segment size, 1 gigabyte, is safe on all 764 supported platforms. If your operating system has "largefile" 765 support (which most do, nowadays), you can use a larger segment 766 size. This can be helpful to reduce the number of file descriptors 767 consumed when working with very large tables. But be careful not to 768 select a value larger than is supported by your platform and the 769 file systems you intend to use. Other tools you might wish to use, 770 such as tar, could also set limits on the usable file size. It is 771 recommended, though not absolutely required, that this value be a 772 power of 2. Note that changing this value breaks on-disk database 773 compatibility, meaning you cannot use "pg_upgrade" to upgrade to a 774 build with a different segment size. 775 776--with-blocksize=BLOCKSIZE 777 778 Set the block size, in kilobytes. This is the unit of storage and 779 I/O within tables. The default, 8 kilobytes, is suitable for most 780 situations; but other values may be useful in special cases. The 781 value must be a power of 2 between 1 and 32 (kilobytes). Note that 782 changing this value breaks on-disk database compatibility, meaning 783 you cannot use "pg_upgrade" to upgrade to a build with a different 784 block size. 785 786--with-wal-blocksize=BLOCKSIZE 787 788 Set the WAL block size, in kilobytes. This is the unit of storage 789 and I/O within the WAL log. The default, 8 kilobytes, is suitable 790 for most situations; but other values may be useful in special 791 cases. The value must be a power of 2 between 1 and 64 (kilobytes). 792 Note that changing this value breaks on-disk database compatibility, 793 meaning you cannot use "pg_upgrade" to upgrade to a build with a 794 different WAL block size. 795 796------------------------------------------------------------------------ 797 798Developer Options 799 800Most of the options in this section are only of interest for developing 801or debugging PostgreSQL. They are not recommended for production builds, 802except for "--enable-debug", which can be useful to enable detailed bug 803reports in the unlucky event that you encounter a bug. On platforms 804supporting DTrace, "--enable-dtrace" may also be reasonable to use in 805production. 806 807When building an installation that will be used to develop code inside 808the server, it is recommended to use at least the options 809"--enable-debug" and "--enable-cassert". 810 811--enable-debug 812 813 Compiles all programs and libraries with debugging symbols. This 814 means that you can run the programs in a debugger to analyze 815 problems. This enlarges the size of the installed executables 816 considerably, and on non-GCC compilers it usually also disables 817 compiler optimization, causing slowdowns. However, having the 818 symbols available is extremely helpful for dealing with any problems 819 that might arise. Currently, this option is recommended for 820 production installations only if you use GCC. But you should always 821 have it on if you are doing development work or running a beta 822 version. 823 824--enable-cassert 825 826 Enables assertion checks in the server, which test for many "cannot 827 happen" conditions. This is invaluable for code development 828 purposes, but the tests can slow down the server significantly. 829 Also, having the tests turned on won't necessarily enhance the 830 stability of your server! The assertion checks are not categorized 831 for severity, and so what might be a relatively harmless bug will 832 still lead to server restarts if it triggers an assertion failure. 833 This option is not recommended for production use, but you should 834 have it on for development work or when running a beta version. 835 836--enable-tap-tests 837 838 Enable tests using the Perl TAP tools. This requires a Perl 839 installation and the Perl module IPC::Run. 840 841--enable-depend 842 843 Enables automatic dependency tracking. With this option, the 844 makefiles are set up so that all affected object files will be 845 rebuilt when any header file is changed. This is useful if you are 846 doing development work, but is just wasted overhead if you intend 847 only to compile once and install. At present, this option only works 848 with GCC. 849 850--enable-coverage 851 852 If using GCC, all programs and libraries are compiled with code 853 coverage testing instrumentation. When run, they generate files in 854 the build directory with code coverage metrics. This option is for 855 use only with GCC and when doing development work. 856 857--enable-profiling 858 859 If using GCC, all programs and libraries are compiled so they can be 860 profiled. On backend exit, a subdirectory will be created that 861 contains the "gmon.out" file containing profile data. This option is 862 for use only with GCC and when doing development work. 863 864--enable-dtrace 865 866 Compiles PostgreSQL with support for the dynamic tracing tool 867 DTrace. 868 869 To point to the "dtrace" program, the environment variable DTRACE 870 can be set. This will often be necessary because "dtrace" is 871 typically installed under "/usr/sbin", which might not be in your 872 PATH. 873 874 Extra command-line options for the "dtrace" program can be specified 875 in the environment variable DTRACEFLAGS. On Solaris, to include 876 DTrace support in a 64-bit binary, you must specify 877 DTRACEFLAGS="-64". For example, using the GCC compiler: 878 879 ./configure CC='gcc -m64' --enable-dtrace DTRACEFLAGS='-64' ... 880 881 Using Sun's compiler: 882 883 ./configure CC='/opt/SUNWspro/bin/cc -xtarget=native64' --enable-dtrace DTRACEFLAGS='-64' ... 884 885------------------------------------------------------------------------ 886 887configure Environment Variables 888 889In addition to the ordinary command-line options described above, 890"configure" responds to a number of environment variables. You can 891specify environment variables on the "configure" command line, for 892example: 893 894 ./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe' 895 896In this usage an environment variable is little different from a 897command-line option. You can also set such variables beforehand: 898 899 export CC=/opt/bin/gcc 900 export CFLAGS='-O2 -pipe' 901 ./configure 902 903This usage can be convenient because many programs' configuration 904scripts respond to these variables in similar ways. 905 906The most commonly used of these environment variables are CC and CFLAGS. 907If you prefer a C compiler different from the one "configure" picks, you 908can set the variable CC to the program of your choice. By default, 909"configure" will pick "gcc" if available, else the platform's default 910(usually "cc"). Similarly, you can override the default compiler flags 911if needed with the CFLAGS variable. 912 913Here is a list of the significant variables that can be set in this 914manner: 915 916BISON 917 918 Bison program 919 920CC 921 922 C compiler 923 924CFLAGS 925 926 options to pass to the C compiler 927 928CLANG 929 930 path to "clang" program used to process source code for inlining 931 when compiling with --with-llvm 932 933CPP 934 935 C preprocessor 936 937CPPFLAGS 938 939 options to pass to the C preprocessor 940 941CXX 942 943 C++ compiler 944 945CXXFLAGS 946 947 options to pass to the C++ compiler 948 949DTRACE 950 951 location of the "dtrace" program 952 953DTRACEFLAGS 954 955 options to pass to the "dtrace" program 956 957FLEX 958 959 Flex program 960 961LDFLAGS 962 963 options to use when linking either executables or shared libraries 964 965LDFLAGS_EX 966 967 additional options for linking executables only 968 969LDFLAGS_SL 970 971 additional options for linking shared libraries only 972 973LLVM_CONFIG 974 975 "llvm-config" program used to locate the LLVM installation 976 977MSGFMT 978 979 "msgfmt" program for native language support 980 981PERL 982 983 Perl interpreter program. This will be used to determine the 984 dependencies for building PL/Perl. The default is "perl". 985 986PYTHON 987 988 Python interpreter program. This will be used to determine the 989 dependencies for building PL/Python. Also, whether Python 2 or 3 is 990 specified here (or otherwise implicitly chosen) determines which 991 variant of the PL/Python language becomes available. See the 992 PL/Python documentation for more information. If this is not set, 993 the following are probed in this order: python python3 python2. 994 995TCLSH 996 997 Tcl interpreter program. This will be used to determine the 998 dependencies for building PL/Tcl. If this is not set, the following 999 are probed in this order: 1000 tclsh tcl tclsh8.6 tclsh86 tclsh8.5 tclsh85 tclsh8.4 tclsh84. 1001 1002XML2_CONFIG 1003 1004 "xml2-config" program used to locate the libxml2 installation 1005 1006Sometimes it is useful to add compiler flags after-the-fact to the set 1007that were chosen by "configure". An important example is that gcc's 1008"-Werror" option cannot be included in the CFLAGS passed to "configure", 1009because it will break many of "configure"'s built-in tests. To add such 1010flags, include them in the COPT environment variable while running 1011"make". The contents of COPT are added to both the CFLAGS and LDFLAGS 1012options set up by "configure". For example, you could do 1013 1014 make COPT='-Werror' 1015 1016or 1017 1018 export COPT='-Werror' 1019 make 1020 1021NOTE: 1022 1023If using GCC, it is best to build with an optimization level of at least 1024"-O1", because using no optimization ("-O0") disables some important 1025compiler warnings (such as the use of uninitialized variables). However, 1026non-zero optimization levels can complicate debugging because stepping 1027through compiled code will usually not match up one-to-one with source 1028code lines. If you get confused while trying to debug optimized code, 1029recompile the specific files of interest with "-O0". An easy way to do 1030this is by passing an option to make: "make PROFILE=-O0 file.o". 1031 1032The COPT and PROFILE environment variables are actually handled 1033identically by the PostgreSQL makefiles. Which to use is a matter of 1034preference, but a common habit among developers is to use PROFILE for 1035one-time flag adjustments, while COPT might be kept set all the time. 1036 1037------------------------------------------------------------------------ 1038 1039 1040Post-Installation Setup 1041 1042------------------------------------------------------------------------ 1043 1044Shared Libraries 1045 1046On some systems with shared libraries you need to tell the system how to 1047find the newly installed shared libraries. The systems on which this is 1048*not* necessary include FreeBSD, HP-UX, Linux, NetBSD, OpenBSD, and 1049Solaris. 1050 1051The method to set the shared library search path varies between 1052platforms, but the most widely-used method is to set the environment 1053variable LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh", "bash", 1054"zsh"): 1055 1056 LD_LIBRARY_PATH=/usr/local/pgsql/lib 1057 export LD_LIBRARY_PATH 1058 1059or in "csh" or "tcsh": 1060 1061 setenv LD_LIBRARY_PATH /usr/local/pgsql/lib 1062 1063Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in Step 10641. You should put these commands into a shell start-up file such as 1065"/etc/profile" or "~/.bash_profile". Some good information about the 1066caveats associated with this method can be found at 1067http://xahlee.info/UnixResource_dir/_/ldpath.html. 1068 1069On some systems it might be preferable to set the environment variable 1070LD_RUN_PATH *before* building. 1071 1072On Cygwin, put the library directory in the PATH or move the ".dll" 1073files into the "bin" directory. 1074 1075If in doubt, refer to the manual pages of your system (perhaps "ld.so" 1076or "rld"). If you later get a message like: 1077 1078 psql: error in loading shared libraries 1079 libpq.so.2.1: cannot open shared object file: No such file or directory 1080 1081then this step was necessary. Simply take care of it then. 1082 1083If you are on Linux and you have root access, you can run: 1084 1085 /sbin/ldconfig /usr/local/pgsql/lib 1086 1087(or equivalent directory) after installation to enable the run-time 1088linker to find the shared libraries faster. Refer to the manual page of 1089"ldconfig" for more information. On FreeBSD, NetBSD, and OpenBSD the 1090command is: 1091 1092 /sbin/ldconfig -m /usr/local/pgsql/lib 1093 1094instead. Other systems are not known to have an equivalent command. 1095 1096------------------------------------------------------------------------ 1097 1098Environment Variables 1099 1100If you installed into "/usr/local/pgsql" or some other location that is 1101not searched for programs by default, you should add 1102"/usr/local/pgsql/bin" (or whatever you set "--bindir" to in Step 1) 1103into your PATH. Strictly speaking, this is not necessary, but it will 1104make the use of PostgreSQL much more convenient. 1105 1106To do this, add the following to your shell start-up file, such as 1107"~/.bash_profile" (or "/etc/profile", if you want it to affect all 1108users): 1109 1110 PATH=/usr/local/pgsql/bin:$PATH 1111 export PATH 1112 1113If you are using "csh" or "tcsh", then use this command: 1114 1115 set path = ( /usr/local/pgsql/bin $path ) 1116 1117To enable your system to find the man documentation, you need to add 1118lines like the following to a shell start-up file unless you installed 1119into a location that is searched by default: 1120 1121 MANPATH=/usr/local/pgsql/share/man:$MANPATH 1122 export MANPATH 1123 1124The environment variables PGHOST and PGPORT specify to client 1125applications the host and port of the database server, overriding the 1126compiled-in defaults. If you are going to run client applications 1127remotely then it is convenient if every user that plans to use the 1128database sets PGHOST. This is not required, however; the settings can be 1129communicated via command line options to most client programs. 1130 1131------------------------------------------------------------------------ 1132 1133 1134Getting Started 1135 1136The following is a quick summary of how to get PostgreSQL up and running 1137once installed. The main documentation contains more information. 1138 11391. Create a user account for the PostgreSQL server. This is the user 1140 the server will run as. For production use you should create a 1141 separate, unprivileged account ("postgres" is commonly used). If you 1142 do not have root access or just want to play around, your own user 1143 account is enough, but running the server as root is a security risk 1144 and will not work. 1145 1146 adduser postgres 1147 11482. Create a database installation with the "initdb" command. To run 1149 "initdb" you must be logged in to your PostgreSQL server account. It 1150 will not work as root. 1151 1152 root# mkdir /usr/local/pgsql/data 1153 root# chown postgres /usr/local/pgsql/data 1154 root# su - postgres 1155 postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data 1156 1157 The "-D" option specifies the location where the data will be 1158 stored. You can use any path you want, it does not have to be under 1159 the installation directory. Just make sure that the server account 1160 can write to the directory (or create it, if it doesn't already 1161 exist) before starting "initdb", as illustrated here. 1162 11633. At this point, if you did not use the "initdb" -A option, you might 1164 want to modify "pg_hba.conf" to control local access to the server 1165 before you start it. The default is to trust all local users. 1166 11674. The previous "initdb" step should have told you how to start up the 1168 database server. Do so now. The command should look something like: 1169 1170 /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start 1171 1172 To stop a server running in the background you can type: 1173 1174 /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data stop 1175 11765. Create a database: 1177 1178 /usr/local/pgsql/bin/createdb testdb 1179 1180 Then enter: 1181 1182 /usr/local/pgsql/bin/psql testdb 1183 1184 to connect to that database. At the prompt you can enter SQL 1185 commands and start experimenting. 1186 1187------------------------------------------------------------------------ 1188 1189 1190What Now? 1191 1192- The PostgreSQL distribution contains a comprehensive documentation 1193 set, which you should read sometime. After installation, the 1194 documentation can be accessed by pointing your browser to 1195 "/usr/local/pgsql/doc/html/index.html", unless you changed the 1196 installation directories. 1197 1198 The first few chapters of the main documentation are the Tutorial, 1199 which should be your first reading if you are completely new to SQL 1200 databases. If you are familiar with database concepts then you want 1201 to proceed with part on server administration, which contains 1202 information about how to set up the database server, database users, 1203 and authentication. 1204 1205- Usually, you will want to modify your computer so that it will 1206 automatically start the database server whenever it boots. Some 1207 suggestions for this are in the documentation. 1208 1209- Run the regression tests against the installed server (using "make 1210 installcheck"). If you didn't run the tests before installation, you 1211 should definitely do it now. This is also explained in the 1212 documentation. 1213 1214- By default, PostgreSQL is configured to run on minimal hardware. 1215 This allows it to start up with almost any hardware configuration. 1216 The default configuration is, however, not designed for optimum 1217 performance. To achieve optimum performance, several server 1218 parameters must be adjusted, the two most common being 1219 shared_buffers and work_mem. Other parameters mentioned in the 1220 documentation also affect performance. 1221 1222------------------------------------------------------------------------ 1223 1224 1225Supported Platforms 1226 1227A platform (that is, a CPU architecture and operating system 1228combination) is considered supported by the PostgreSQL development 1229community if the code contains provisions to work on that platform and 1230it has recently been verified to build and pass its regression tests on 1231that platform. Currently, most testing of platform compatibility is done 1232automatically by test machines in the PostgreSQL Build Farm. If you are 1233interested in using PostgreSQL on a platform that is not represented in 1234the build farm, but on which the code works or can be made to work, you 1235are strongly encouraged to set up a build farm member machine so that 1236continued compatibility can be assured. 1237 1238In general, PostgreSQL can be expected to work on these CPU 1239architectures: x86, x86_64, IA64, PowerPC, PowerPC 64, S/390, S/390x, 1240Sparc, Sparc 64, ARM, MIPS, MIPSEL, and PA-RISC. Code support exists for 1241M68K, M32R, and VAX, but these architectures are not known to have been 1242tested recently. It is often possible to build on an unsupported CPU 1243type by configuring with "--disable-spinlocks", but performance will be 1244poor. 1245 1246PostgreSQL can be expected to work on these operating systems: Linux 1247(all recent distributions), Windows (XP and later), FreeBSD, OpenBSD, 1248NetBSD, macOS, AIX, HP/UX, and Solaris. Other Unix-like systems may also 1249work but are not currently being tested. In most cases, all CPU 1250architectures supported by a given operating system will work. Look in 1251the section called "Platform-Specific Notes" below to see if there is 1252information specific to your operating system, particularly if using an 1253older system. 1254 1255If you have installation problems on a platform that is known to be 1256supported according to recent build farm results, please report it to 1257<pgsql-bugs@lists.postgresql.org>. If you are interested in porting 1258PostgreSQL to a new platform, <pgsql-hackers@lists.postgresql.org> is 1259the appropriate place to discuss that. 1260 1261------------------------------------------------------------------------ 1262 1263 1264Platform-Specific Notes 1265 1266This section documents additional platform-specific issues regarding the 1267installation and setup of PostgreSQL. Be sure to read the installation 1268instructions, and in particular the section called "Requirements" as 1269well. Also, check the file "src/test/regress/README" and the 1270documentation regarding the interpretation of regression test results. 1271 1272Platforms that are not covered here have no known platform-specific 1273installation issues. 1274 1275------------------------------------------------------------------------ 1276 1277AIX 1278 1279PostgreSQL works on AIX, but AIX versions before about 6.1 have various 1280issues and are not recommended. You can use GCC or the native IBM 1281compiler "xlc". 1282 1283------------------------------------------------------------------------ 1284 1285Memory Management 1286 1287AIX can be somewhat peculiar with regards to the way it does memory 1288management. You can have a server with many multiples of gigabytes of 1289RAM free, but still get out of memory or address space errors when 1290running applications. One example is loading of extensions failing with 1291unusual errors. For example, running as the owner of the PostgreSQL 1292installation: 1293 1294 =# CREATE EXTENSION plperl; 1295 ERROR: could not load library "/opt/dbs/pgsql/lib/plperl.so": A memory address is not in the address space for the process. 1296 1297Running as a non-owner in the group possessing the PostgreSQL 1298installation: 1299 1300 =# CREATE EXTENSION plperl; 1301 ERROR: could not load library "/opt/dbs/pgsql/lib/plperl.so": Bad address 1302 1303Another example is out of memory errors in the PostgreSQL server logs, 1304with every memory allocation near or greater than 256 MB failing. 1305 1306The overall cause of all these problems is the default bittedness and 1307memory model used by the server process. By default, all binaries built 1308on AIX are 32-bit. This does not depend upon hardware type or kernel in 1309use. These 32-bit processes are limited to 4 GB of memory laid out in 1310256 MB segments using one of a few models. The default allows for less 1311than 256 MB in the heap as it shares a single segment with the stack. 1312 1313In the case of the plperl example, above, check your umask and the 1314permissions of the binaries in your PostgreSQL installation. The 1315binaries involved in that example were 32-bit and installed as mode 750 1316instead of 755. Due to the permissions being set in this fashion, only 1317the owner or a member of the possessing group can load the library. 1318Since it isn't world-readable, the loader places the object into the 1319process' heap instead of the shared library segments where it would 1320otherwise be placed. 1321 1322The "ideal" solution for this is to use a 64-bit build of PostgreSQL, 1323but that is not always practical, because systems with 32-bit processors 1324can build, but not run, 64-bit binaries. 1325 1326If a 32-bit binary is desired, set LDR_CNTRL to MAXDATA=0xn0000000, 1327where 1 <= n <= 8, before starting the PostgreSQL server, and try 1328different values and "postgresql.conf" settings to find a configuration 1329that works satisfactorily. This use of LDR_CNTRL tells AIX that you want 1330the server to have MAXDATA bytes set aside for the heap, allocated in 1331256 MB segments. When you find a workable configuration, "ldedit" can be 1332used to modify the binaries so that they default to using the desired 1333heap size. PostgreSQL can also be rebuilt, passing 1334configure LDFLAGS="-Wl,-bmaxdata:0xn0000000" to achieve the same 1335effect. 1336 1337For a 64-bit build, set OBJECT_MODE to 64 and pass CC="gcc -maix64" and 1338LDFLAGS="-Wl,-bbigtoc" to "configure". (Options for "xlc" might differ.) 1339If you omit the export of OBJECT_MODE, your build may fail with linker 1340errors. When OBJECT_MODE is set, it tells AIX's build utilities such as 1341"ar", "as", and "ld" what type of objects to default to handling. 1342 1343By default, overcommit of paging space can happen. While we have not 1344seen this occur, AIX will kill processes when it runs out of memory and 1345the overcommit is accessed. The closest to this that we have seen is 1346fork failing because the system decided that there was not enough memory 1347for another process. Like many other parts of AIX, the paging space 1348allocation method and out-of-memory kill is configurable on a system- or 1349process-wide basis if this becomes a problem. 1350 1351------------------------------------------------------------------------ 1352 1353Cygwin 1354 1355PostgreSQL can be built using Cygwin, a Linux-like environment for 1356Windows, but that method is inferior to the native Windows build and 1357running a server under Cygwin is no longer recommended. 1358 1359When building from source, proceed according to the Unix-style 1360installation procedure (i.e., ./configure; make; etc.), noting the 1361following Cygwin-specific differences: 1362 1363- Set your path to use the Cygwin bin directory before the Windows 1364 utilities. This will help prevent problems with compilation. 1365 1366- The "adduser" command is not supported; use the appropriate user 1367 management application on Windows NT, 2000, or XP. Otherwise, skip 1368 this step. 1369 1370- The "su" command is not supported; use ssh to simulate su on Windows 1371 NT, 2000, or XP. Otherwise, skip this step. 1372 1373- OpenSSL is not supported. 1374 1375- Start "cygserver" for shared memory support. To do this, enter the 1376 command /usr/sbin/cygserver &. This program needs to be 1377 running anytime you start the PostgreSQL server or initialize a 1378 database cluster ("initdb"). The default "cygserver" configuration 1379 may need to be changed (e.g., increase SEMMNS) to prevent PostgreSQL 1380 from failing due to a lack of system resources. 1381 1382- Building might fail on some systems where a locale other than C is 1383 in use. To fix this, set the locale to C by doing "export 1384 LANG=C.utf8" before building, and then setting it back to the 1385 previous setting after you have installed PostgreSQL. 1386 1387- The parallel regression tests (make check) can generate spurious 1388 regression test failures due to overflowing the listen() backlog 1389 queue which causes connection refused errors or hangs. You can limit 1390 the number of connections using the make variable MAX_CONNECTIONS 1391 thus: 1392 1393 make MAX_CONNECTIONS=5 check 1394 1395 (On some systems you can have up to about 10 simultaneous 1396 connections.) 1397 1398It is possible to install "cygserver" and the PostgreSQL server as 1399Windows NT services. For information on how to do this, please refer to 1400the "README" document included with the PostgreSQL binary package on 1401Cygwin. It is installed in the directory "/usr/share/doc/Cygwin". 1402 1403------------------------------------------------------------------------ 1404 1405macOS 1406 1407To build PostgreSQL from source on macOS, you will need to install 1408Apple's command line developer tools, which can be done by issuing 1409 1410 xcode-select --install 1411 1412(note that this will pop up a GUI dialog window for confirmation). You 1413may or may not wish to also install Xcode. 1414 1415On recent macOS releases, it's necessary to embed the "sysroot" path in 1416the include switches used to find some system header files. This results 1417in the outputs of the configure script varying depending on which SDK 1418version was used during configure. That shouldn't pose any problem in 1419simple scenarios, but if you are trying to do something like building an 1420extension on a different machine than the server code was built on, you 1421may need to force use of a different sysroot path. To do that, set 1422PG_SYSROOT, for example 1423 1424 make PG_SYSROOT=/desired/path all 1425 1426To find out the appropriate path on your machine, run 1427 1428 xcrun --show-sdk-path 1429 1430Note that building an extension using a different sysroot version than 1431was used to build the core server is not really recommended; in the 1432worst case it could result in hard-to-debug ABI inconsistencies. 1433 1434You can also select a non-default sysroot path when configuring, by 1435specifying PG_SYSROOT to configure: 1436 1437 ./configure ... PG_SYSROOT=/desired/path 1438 1439This would primarily be useful to cross-compile for some other macOS 1440version. There is no guarantee that the resulting executables will run 1441on the current host. 1442 1443To suppress the "-isysroot" options altogether, use 1444 1445 ./configure ... PG_SYSROOT=none 1446 1447(any nonexistent pathname will work). This might be useful if you wish 1448to build with a non-Apple compiler, but beware that that case is not 1449tested or supported by the PostgreSQL developers. 1450 1451macOS's "System Integrity Protection" (SIP) feature breaks make check, 1452because it prevents passing the needed setting of DYLD_LIBRARY_PATH down 1453to the executables being tested. You can work around that by doing 1454make install before make check. Most PostgreSQL developers just turn 1455off SIP, though. 1456 1457------------------------------------------------------------------------ 1458 1459MinGW/Native Windows 1460 1461PostgreSQL for Windows can be built using MinGW, a Unix-like build 1462environment for Microsoft operating systems, or using Microsoft's Visual 1463C++ compiler suite. The MinGW build procedure uses the normal build 1464system described in this chapter; the Visual C++ build works completely 1465differently and is described in the documentation. 1466 1467The native Windows port requires a 32 or 64-bit version of Windows 2000 1468or later. Earlier operating systems do not have sufficient 1469infrastructure (but Cygwin may be used on those). MinGW, the Unix-like 1470build tools, and MSYS, a collection of Unix tools required to run shell 1471scripts like "configure", can be downloaded from http://www.mingw.org/. 1472Neither is required to run the resulting binaries; they are needed only 1473for creating the binaries. 1474 1475To build 64 bit binaries using MinGW, install the 64 bit tool set from 1476https://mingw-w64.org/, put its bin directory in the PATH, and run 1477"configure" with the "--host=x86_64-w64-mingw32" option. 1478 1479After you have everything installed, it is suggested that you run psql 1480under "CMD.EXE", as the MSYS console has buffering issues. 1481 1482------------------------------------------------------------------------ 1483 1484Collecting Crash Dumps on Windows 1485 1486If PostgreSQL on Windows crashes, it has the ability to generate 1487minidumps that can be used to track down the cause for the crash, 1488similar to core dumps on Unix. These dumps can be read using the Windows 1489Debugger Tools or using Visual Studio. To enable the generation of dumps 1490on Windows, create a subdirectory named "crashdumps" inside the cluster 1491data directory. The dumps will then be written into this directory with 1492a unique name based on the identifier of the crashing process and the 1493current time of the crash. 1494 1495------------------------------------------------------------------------ 1496 1497Solaris 1498 1499PostgreSQL is well-supported on Solaris. The more up to date your 1500operating system, the fewer issues you will experience. 1501 1502------------------------------------------------------------------------ 1503 1504Required Tools 1505 1506You can build with either GCC or Sun's compiler suite. For better code 1507optimization, Sun's compiler is strongly recommended on the SPARC 1508architecture. If you are using Sun's compiler, be careful not to select 1509"/usr/ucb/cc"; use "/opt/SUNWspro/bin/cc". 1510 1511You can download Sun Studio from 1512https://www.oracle.com/technetwork/server-storage/solarisstudio/downloads/. 1513Many GNU tools are integrated into Solaris 10, or they are present on 1514the Solaris companion CD. If you need packages for older versions of 1515Solaris, you can find these tools at http://www.sunfreeware.com. If you 1516prefer sources, look at https://www.gnu.org/prep/ftp. 1517 1518------------------------------------------------------------------------ 1519 1520configure Complains About a Failed Test Program 1521 1522If "configure" complains about a failed test program, this is probably a 1523case of the run-time linker being unable to find some library, probably 1524libz, libreadline or some other non-standard library such as libssl. To 1525point it to the right location, set the LDFLAGS environment variable on 1526the "configure" command line, e.g., 1527 1528 configure ... LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib" 1529 1530See the ld man page for more information. 1531 1532------------------------------------------------------------------------ 1533 1534Compiling for Optimal Performance 1535 1536On the SPARC architecture, Sun Studio is strongly recommended for 1537compilation. Try using the "-xO5" optimization flag to generate 1538significantly faster binaries. Do not use any flags that modify behavior 1539of floating-point operations and errno processing (e.g., "-fast"). 1540 1541If you do not have a reason to use 64-bit binaries on SPARC, prefer the 154232-bit version. The 64-bit operations are slower and 64-bit binaries are 1543slower than the 32-bit variants. On the other hand, 32-bit code on the 1544AMD64 CPU family is not native, so 32-bit code is significantly slower 1545on that CPU family. 1546 1547------------------------------------------------------------------------ 1548 1549Using DTrace for Tracing PostgreSQL 1550 1551Yes, using DTrace is possible. See the documentation for further 1552information. 1553 1554If you see the linking of the "postgres" executable abort with an error 1555message like: 1556 1557 Undefined first referenced 1558 symbol in file 1559 AbortTransaction utils/probes.o 1560 CommitTransaction utils/probes.o 1561 ld: fatal: Symbol referencing errors. No output written to postgres 1562 collect2: ld returned 1 exit status 1563 make: *** [postgres] Error 1 1564 1565your DTrace installation is too old to handle probes in static 1566functions. You need Solaris 10u4 or newer to use DTrace. 1567