begriffs open source - ai-pg/blob - full-docs/txt/installation-platform-notes.txt

   1
   2 17.7. Platform-Specific Notes #
   3
   4    17.7.1. Cygwin
   5    17.7.2. macOS
   6    17.7.3. MinGW
   7    17.7.4. Solaris
   8    17.7.5. Visual Studio
   9
  10    This section documents additional platform-specific issues regarding
  11    the installation and setup of PostgreSQL. Be sure to read the
  12    installation instructions, and in particular Section 17.1 as well.
  13    Also, check Chapter 31 regarding the interpretation of regression test
  14    results.
  15
  16    Platforms that are not covered here have no known platform-specific
  17    installation issues.
  18
  19 17.7.1. Cygwin #
  20
  21    PostgreSQL can be built using Cygwin, a Linux-like environment for
  22    Windows, but that method is inferior to the native Windows build and
  23    running a server under Cygwin is no longer recommended.
  24
  25    When building from source, proceed according to the Unix-style
  26    installation procedure (i.e., ./configure; make; etc.), noting the
  27    following Cygwin-specific differences:
  28      * Set your path to use the Cygwin bin directory before the Windows
  29        utilities. This will help prevent problems with compilation.
  30      * The adduser command is not supported; use the appropriate user
  31        management application on Windows. Otherwise, skip this step.
  32      * The su command is not supported; use ssh to simulate su on Windows.
  33        Otherwise, skip this step.
  34      * OpenSSL is not supported.
  35      * Start cygserver for shared memory support. To do this, enter the
  36        command /usr/sbin/cygserver &. This program needs to be running
  37        anytime you start the PostgreSQL server or initialize a database
  38        cluster (initdb). The default cygserver configuration may need to
  39        be changed (e.g., increase SEMMNS) to prevent PostgreSQL from
  40        failing due to a lack of system resources.
  41      * Building might fail on some systems where a locale other than C is
  42        in use. To fix this, set the locale to C by doing export
  43        LANG=C.utf8 before building, and then setting it back to the
  44        previous setting after you have installed PostgreSQL.
  45      * The parallel regression tests (make check) can generate spurious
  46        regression test failures due to overflowing the listen() backlog
  47        queue which causes connection refused errors or hangs. You can
  48        limit the number of connections using the make variable
  49        MAX_CONNECTIONS thus:
  50 make MAX_CONNECTIONS=5 check
  51
  52        (On some systems you can have up to about 10 simultaneous
  53        connections.)
  54
  55    It is possible to install cygserver and the PostgreSQL server as
  56    Windows NT services. For information on how to do this, please refer to
  57    the README document included with the PostgreSQL binary package on
  58    Cygwin. It is installed in the directory /usr/share/doc/Cygwin.
  59
  60 17.7.2. macOS #
  61
  62    To build PostgreSQL from source on macOS, you will need to install
  63    Apple's command line developer tools, which can be done by issuing
  64 xcode-select --install
  65
  66    (note that this will pop up a GUI dialog window for confirmation). You
  67    may or may not wish to also install Xcode.
  68
  69    On recent macOS releases, it's necessary to embed the “sysroot” path in
  70    the include switches used to find some system header files. This
  71    results in the outputs of the configure script varying depending on
  72    which SDK version was used during configure. That shouldn't pose any
  73    problem in simple scenarios, but if you are trying to do something like
  74    building an extension on a different machine than the server code was
  75    built on, you may need to force use of a different sysroot path. To do
  76    that, set PG_SYSROOT, for example
  77 make PG_SYSROOT=/desired/path all
  78
  79    To find out the appropriate path on your machine, run
  80 xcrun --show-sdk-path
  81
  82    Note that building an extension using a different sysroot version than
  83    was used to build the core server is not really recommended; in the
  84    worst case it could result in hard-to-debug ABI inconsistencies.
  85
  86    You can also select a non-default sysroot path when configuring, by
  87    specifying PG_SYSROOT to configure:
  88 ./configure ... PG_SYSROOT=/desired/path
  89
  90    This would primarily be useful to cross-compile for some other macOS
  91    version. There is no guarantee that the resulting executables will run
  92    on the current host.
  93
  94    To suppress the -isysroot options altogether, use
  95 ./configure ... PG_SYSROOT=none
  96
  97    (any nonexistent pathname will work). This might be useful if you wish
  98    to build with a non-Apple compiler, but beware that that case is not
  99    tested or supported by the PostgreSQL developers.
 100
 101    macOS's “System Integrity Protection” (SIP) feature breaks make check,
 102    because it prevents passing the needed setting of DYLD_LIBRARY_PATH
 103    down to the executables being tested. You can work around that by doing
 104    make install before make check. Most PostgreSQL developers just turn
 105    off SIP, though.
 106
 107 17.7.3. MinGW #
 108
 109    PostgreSQL for Windows can be built using MinGW, a Unix-like build
 110    environment for Windows. It is recommended to use the MSYS2 environment
 111    for this and also to install any prerequisite packages.
 112
 113 17.7.3.1. Collecting Crash Dumps #
 114
 115    If PostgreSQL on Windows crashes, it has the ability to generate
 116    minidumps that can be used to track down the cause for the crash,
 117    similar to core dumps on Unix. These dumps can be read using the
 118    Windows Debugger Tools or using Visual Studio. To enable the generation
 119    of dumps on Windows, create a subdirectory named crashdumps inside the
 120    cluster data directory. The dumps will then be written into this
 121    directory with a unique name based on the identifier of the crashing
 122    process and the current time of the crash.
 123
 124 17.7.4. Solaris #
 125
 126    PostgreSQL is well-supported on Solaris. The more up to date your
 127    operating system, the fewer issues you will experience.
 128
 129 17.7.4.1. Required Tools #
 130
 131    You can build with either GCC or Sun's compiler suite. For better code
 132    optimization, Sun's compiler is strongly recommended on the SPARC
 133    architecture. If you are using Sun's compiler, be careful not to select
 134    /usr/ucb/cc; use /opt/SUNWspro/bin/cc.
 135
 136    You can download Sun Studio from
 137    https://www.oracle.com/technetwork/server-storage/solarisstudio/downloa
 138    ds/. Many GNU tools are integrated into Solaris 10, or they are present
 139    on the Solaris companion CD. If you need packages for older versions of
 140    Solaris, you can find these tools at http://www.sunfreeware.com. If you
 141    prefer sources, look at https://www.gnu.org/prep/ftp.
 142
 143 17.7.4.2. configure Complains About a Failed Test Program #
 144
 145    If configure complains about a failed test program, this is probably a
 146    case of the run-time linker being unable to find some library, probably
 147    libz, libreadline or some other non-standard library such as libssl. To
 148    point it to the right location, set the LDFLAGS environment variable on
 149    the configure command line, e.g.,
 150 configure ... LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib"
 151
 152    See the ld man page for more information.
 153
 154 17.7.4.3. Compiling for Optimal Performance #
 155
 156    On the SPARC architecture, Sun Studio is strongly recommended for
 157    compilation. Try using the -xO5 optimization flag to generate
 158    significantly faster binaries. Do not use any flags that modify
 159    behavior of floating-point operations and errno processing (e.g.,
 160    -fast).
 161
 162    If you do not have a reason to use 64-bit binaries on SPARC, prefer the
 163    32-bit version. The 64-bit operations are slower and 64-bit binaries
 164    are slower than the 32-bit variants. On the other hand, 32-bit code on
 165    the AMD64 CPU family is not native, so 32-bit code is significantly
 166    slower on that CPU family.
 167
 168 17.7.4.4. Using DTrace for Tracing PostgreSQL #
 169
 170    Yes, using DTrace is possible. See Section 27.5 for further
 171    information.
 172
 173    If you see the linking of the postgres executable abort with an error
 174    message like:
 175 Undefined                       first referenced
 176  symbol                             in file
 177 AbortTransaction                    utils/probes.o
 178 CommitTransaction                   utils/probes.o
 179 ld: fatal: Symbol referencing errors. No output written to postgres
 180 collect2: ld returned 1 exit status
 181 make: *** [postgres] Error 1
 182
 183    your DTrace installation is too old to handle probes in static
 184    functions. You need Solaris 10u4 or newer to use DTrace.
 185
 186 17.7.5. Visual Studio #
 187
 188    It is recommended that most users download the binary distribution for
 189    Windows, available as a graphical installer package from the PostgreSQL
 190    website at https://www.postgresql.org/download/. Building from source
 191    is only intended for people developing PostgreSQL or extensions.
 192
 193    PostgreSQL for Windows with Visual Studio can be built using Meson, as
 194    described in Section 17.4. The native Windows port requires a 32 or
 195    64-bit version of Windows 10 or later.
 196
 197    Native builds of psql don't support command line editing. The Cygwin
 198    build does support command line editing, so it should be used where
 199    psql is needed for interactive use on Windows.
 200
 201    PostgreSQL can be built using the Visual C++ compiler suite from
 202    Microsoft. These compilers can be either from Visual Studio, Visual
 203    Studio Express or some versions of the Microsoft Windows SDK. If you do
 204    not already have a Visual Studio environment set up, the easiest ways
 205    are to use the compilers from Visual Studio 2022 or those in the
 206    Windows SDK 10, which are both free downloads from Microsoft.
 207
 208    Both 32-bit and 64-bit builds are possible with the Microsoft Compiler
 209    suite. 32-bit PostgreSQL builds are possible with Visual Studio 2015 to
 210    Visual Studio 2022, as well as standalone Windows SDK releases 10 and
 211    above. 64-bit PostgreSQL builds are supported with Microsoft Windows
 212    SDK version 10 and above or Visual Studio 2015 and above.
 213
 214    If your build environment doesn't ship with a supported version of the
 215    Microsoft Windows SDK it is recommended that you upgrade to the latest
 216    version (currently version 10), available for download from
 217    https://www.microsoft.com/download.
 218
 219    You must always include the Windows Headers and Libraries part of the
 220    SDK. If you install a Windows SDK including the Visual C++ Compilers,
 221    you don't need Visual Studio to build. Note that as of Version 8.0a the
 222    Windows SDK no longer ships with a complete command-line build
 223    environment.
 224
 225 17.7.5.1. Requirements #
 226
 227    The following additional products are required to build PostgreSQL on
 228    Windows.
 229
 230    Strawberry Perl
 231           Strawberry Perl is required to run the build generation scripts.
 232           MinGW or Cygwin Perl will not work. It must also be present in
 233           the PATH. Binaries can be downloaded from
 234           https://strawberryperl.com.
 235
 236    Bison and Flex
 237           Binaries for Bison and Flex can be downloaded from
 238           https://github.com/lexxmark/winflexbison.
 239
 240    The following additional products are not required to get started, but
 241    are required to build the complete package.
 242
 243    Magicsplat Tcl
 244           Required for building PL/Tcl. Binaries can be downloaded from
 245           https://www.magicsplat.com/tcl-installer/index.html.
 246
 247    Diff
 248           Diff is required to run the regression tests, and can be
 249           downloaded from http://gnuwin32.sourceforge.net.
 250
 251    Gettext
 252           Gettext is required to build with NLS support, and can be
 253           downloaded from http://gnuwin32.sourceforge.net. Note that
 254           binaries, dependencies and developer files are all needed.
 255
 256    MIT Kerberos
 257           Required for GSSAPI authentication support. MIT Kerberos can be
 258           downloaded from https://web.mit.edu/Kerberos/dist/index.html.
 259
 260    libxml2 and libxslt
 261           Required for XML support. Binaries can be downloaded from
 262           https://zlatkovic.com/pub/libxml or source from
 263           http://xmlsoft.org. Note that libxml2 requires iconv, which is
 264           available from the same download location.
 265
 266    LZ4
 267           Required for supporting LZ4 compression. Binaries and source can
 268           be downloaded from https://github.com/lz4/lz4/releases.
 269
 270    Zstandard
 271           Required for supporting Zstandard compression. Binaries and
 272           source can be downloaded from
 273           https://github.com/facebook/zstd/releases.
 274
 275    OpenSSL
 276           Required for SSL support. Binaries can be downloaded from
 277           https://slproweb.com/products/Win32OpenSSL.html or source from
 278           https://www.openssl.org.
 279
 280    ossp-uuid
 281           Required for UUID-OSSP support (contrib only). Source can be
 282           downloaded from http://www.ossp.org/pkg/lib/uuid/.
 283
 284    Python
 285           Required for building PL/Python. Binaries can be downloaded from
 286           https://www.python.org.
 287
 288    zlib
 289           Required for compression support in pg_dump and pg_restore.
 290           Binaries can be downloaded from https://www.zlib.net.
 291
 292 17.7.5.2. Special Considerations for 64-Bit Windows #
 293
 294    PostgreSQL will only build for the x64 architecture on 64-bit Windows.
 295
 296    Mixing 32- and 64-bit versions in the same build tree is not supported.
 297    The build system will automatically detect if it's running in a 32- or
 298    64-bit environment, and build PostgreSQL accordingly. For this reason,
 299    it is important to start the correct command prompt before building.
 300
 301    To use a server-side third party library such as Python or OpenSSL,
 302    this library must also be 64-bit. There is no support for loading a
 303    32-bit library in a 64-bit server. Several of the third party libraries
 304    that PostgreSQL supports may only be available in 32-bit versions, in
 305    which case they cannot be used with 64-bit PostgreSQL.
 306
 307 17.7.5.3. Collecting Crash Dumps #
 308
 309    If PostgreSQL on Windows crashes, it has the ability to generate
 310    minidumps that can be used to track down the cause for the crash,
 311    similar to core dumps on Unix. These dumps can be read using the
 312    Windows Debugger Tools or using Visual Studio. To enable the generation
 313    of dumps on Windows, create a subdirectory named crashdumps inside the
 314    cluster data directory. The dumps will then be written into this
 315    directory with a unique name based on the identifier of the crashing
 316    process and the current time of the crash.