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