From e2b73f4a4de6c2df6a1e623ad06b42f1bb2471ad Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 22 Dec 2023 13:32:15 -0500 Subject: [PATCH] Stop generating plain-text INSTALL instructions. Up to now, our distribution tarballs have included a plain-text form of the installation.sgml chapter. The rationale for that was that a recipient might not have either ready internet access or HTML-viewing tools; a theory that seems downright quaint today. Maintaining the ability to generate this file is not without cost, because it puts special requirements on installation.sgml that are often overlooked. Moreover, we are moving in the direction of making our distribution tarballs be pure git snapshots for traceability/reproducibility reasons; including generated files doesn't fit into that plan. Hence, let's just drop INSTALL and remove the infrastructure for generating it. The top-level README will now recommend visiting our website to see the installation instructions. As a useful side-effect, we can get rid of README.git which has provoked confusion. Discussion: https://postgr.es/m/20231220114927.faccqqprmuyrzdip@alap3.anarazel.de Discussion: https://postgr.es/m/e07408d9-e5f2-d9fd-5672-f53354e9305e@eisentraut.org --- GNUmakefile.in | 3 - Makefile | 8 +- README | 15 ++- README.git | 14 --- doc/src/sgml/.gitignore | 3 - doc/src/sgml/Makefile | 25 +--- doc/src/sgml/docguide.sgml | 22 ---- doc/src/sgml/installation.sgml | 53 +++------ doc/src/sgml/meson.build | 37 ------ doc/src/sgml/standalone-install.xml | 170 ---------------------------- doc/src/sgml/standalone-profile.xsl | 97 ---------------- src/pl/plperl/README | 3 +- src/tools/RELEASE_CHANGES | 3 + 13 files changed, 32 insertions(+), 421 deletions(-) delete mode 100644 README.git delete mode 100644 doc/src/sgml/standalone-install.xml delete mode 100644 doc/src/sgml/standalone-profile.xsl diff --git a/GNUmakefile.in b/GNUmakefile.in index 80db4c73f8..eba569e930 100644 --- a/GNUmakefile.in +++ b/GNUmakefile.in @@ -109,10 +109,7 @@ distdir: || cp "$(top_srcdir)/$$file" "$(distdir)/$$file"; \ fi || exit; \ done - $(MAKE) -C $(distdir)/doc/src/sgml/ INSTALL - cp $(distdir)/doc/src/sgml/INSTALL $(distdir)/ $(MAKE) -C $(distdir) distclean - rm -f $(distdir)/README.git distcheck: dist rm -rf $(dummy) diff --git a/Makefile b/Makefile index c66fb3027b..9bc1a4ec17 100644 --- a/Makefile +++ b/Makefile @@ -17,13 +17,7 @@ all: all check install installdirs installcheck installcheck-parallel uninstall clean distclean maintainer-clean dist distcheck world check-world install-world installcheck-world: @if [ ! -f GNUmakefile ] ; then \ - if [ -f INSTALL ] ; then \ - INSTRUCTIONS="INSTALL"; \ - else \ - INSTRUCTIONS="README.git"; \ - fi; \ - echo "You need to run the 'configure' program first. See the file"; \ - echo "'$$INSTRUCTIONS' for installation instructions, or visit: " ; \ + echo "You need to run the 'configure' program first. Please see"; \ echo "" ; \ false ; \ fi diff --git a/README b/README index 56d0c951a9..e40e610ccb 100644 --- a/README +++ b/README @@ -9,14 +9,13 @@ that supports an extended subset of the SQL standard, including transactions, foreign keys, subqueries, triggers, user-defined types and functions. This distribution also contains C language bindings. -See the file INSTALL for instructions on how to build and install -PostgreSQL. That file also lists supported operating systems and -hardware platforms and contains information regarding any other -software packages that are required to build or run the PostgreSQL -system. Copyright and license information can be found in the -file COPYRIGHT. A comprehensive documentation set is included in this -distribution; it can be read as described in the installation -instructions. +Copyright and license information can be found in the file COPYRIGHT. + +General documentation about this version of PostgreSQL can be found at: +https://www.postgresql.org/docs/devel/ +In particular, information about building PostgreSQL from the source +code can be found at: +https://www.postgresql.org/docs/devel/installation.html The latest version of this software, and related software, may be obtained at https://www.postgresql.org/download/. For more information diff --git a/README.git b/README.git deleted file mode 100644 index 4bf614eea4..0000000000 --- a/README.git +++ /dev/null @@ -1,14 +0,0 @@ -(This file does not appear in release tarballs.) - -In a release or snapshot tarball of PostgreSQL, a documentation file named -INSTALL will appear in this directory. However, this file is not stored in -git and so will not be present if you are using a git checkout. - -If you are using a git checkout, you can view the most recent installation -instructions at: - https://www.postgresql.org/docs/devel/installation.html - -Users compiling from git will also need compatible versions of Bison, Flex, -and Perl, as discussed in the install documentation. These programs are not -needed when using a tarball, since the files they are needed to build are -already present in the tarball. (On Windows, however, you need Perl anyway.) diff --git a/doc/src/sgml/.gitignore b/doc/src/sgml/.gitignore index 88a07d852e..91f2781fe7 100644 --- a/doc/src/sgml/.gitignore +++ b/doc/src/sgml/.gitignore @@ -6,7 +6,6 @@ /man7/ /man-stamp # Other popular build targets -/INSTALL /postgres-US.pdf /postgres-A4.pdf /postgres.html @@ -21,7 +20,5 @@ /wait_event_types.sgml # Assorted byproducts from building the above /postgres-full.xml -/INSTALL.html -/INSTALL.xml /postgres-US.fo /postgres-A4.fo diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 2ef818900f..725fec59e7 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -36,6 +36,8 @@ ifndef FOP FOP = $(missing) fop endif +PANDOC = pandoc + XMLINCLUDE = --path . --path $(srcdir) ifdef XMLLINT @@ -113,25 +115,6 @@ wait_event_types.sgml: $(top_srcdir)/src/backend/utils/activity/wait_event_names targets-meson.sgml: targets-meson.txt $(srcdir)/generate-targets-meson.pl $(PERL) $(srcdir)/generate-targets-meson.pl $^ > $@ -## -## Generation of some text files. -## - -ICONV = iconv -PANDOC = pandoc - -INSTALL: % : %.html - $(PANDOC) -t plain -o $@.tmp $< - $(ICONV) -f utf8 -t us-ascii//TRANSLIT $@.tmp > $@ - rm $@.tmp - -INSTALL.html: %.html : stylesheet-text.xsl %.xml - $(XMLLINT) --noout --valid $*.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@ - -INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres-full.xml - $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@ - ## ## HTML @@ -284,13 +267,9 @@ check-tabs: # keeping the dependencies satisfied. .SECONDARY: $(GENERATED_SGML) .SECONDARY: postgres-full.xml -.SECONDARY: INSTALL.html INSTALL.xml .SECONDARY: postgres-A4.fo postgres-US.fo clean: -# text --- these are shipped, but not in this directory - rm -f INSTALL - rm -f INSTALL.html INSTALL.xml # single-page output rm -f postgres.html postgres.txt # print diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index c129215dd3..db4bcce56e 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -393,28 +393,6 @@ LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN - - Plain Text Files - - - The installation instructions are also distributed as plain text, - in case they are needed in a situation where better reading tools - are not available. The INSTALL file - corresponds to , with some minor - changes to account for the different context. To recreate the - file, change to the directory doc/src/sgml - and enter make INSTALL. Building text output - requires Pandoc version 1.13 or newer as an - additional build tool. - - - - In the past, the release notes and regression testing instructions - were also distributed as plain text, but this practice has been - discontinued. - - - Syntax Check diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index e23c784aa5..bb55695300 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,12 +1,4 @@ - Installation from Source Code @@ -15,7 +7,6 @@ documentation. See standalone-profile.xsl for details. installation - This chapter describes the installation of PostgreSQL using the source code @@ -942,9 +933,7 @@ build-postgresql: Build with support for LLVM based - JIT compilation (see ). This + JIT compilation (see ). This requires the LLVM library to be installed. The minimum required version of LLVM is currently 3.9. @@ -1085,8 +1074,8 @@ build-postgresql: for systemdsystemd service notifications. This improves integration if the server is started under systemd but has no impact - otherwise; see for more - information. libsystemd and the + otherwise; see for more + information. libsystemd and the associated header files need to be installed to use this option. @@ -1224,9 +1213,8 @@ build-postgresql: Build without support for the ICUICU - library, disabling the use of ICU collation features (see ). + library, disabling the use of ICU collation features (see ). @@ -1583,7 +1571,7 @@ build-postgresql: Enable tests using the Perl TAP tools. This requires a Perl installation and the Perl module IPC::Run. - See for more information. + See for more information. @@ -1610,8 +1598,8 @@ build-postgresql: code coverage testing instrumentation. When run, they generate files in the build directory with code coverage metrics. - See - for more information. This option is for use only with GCC + See + for more information. This option is for use only with GCC and when doing development work. @@ -1639,8 +1627,7 @@ build-postgresql: Compiles PostgreSQL with support for the dynamic tracing tool DTrace. - See - for more information. + See for more information. @@ -2406,9 +2393,8 @@ ninja install Build with support for the ICUICU - library, enabling use of ICU collation features (see ). Defaults to auto and requires the + library, enabling use of ICU collation features (see ). Defaults to auto and requires the ICU4C package to be installed. The minimum required version of ICU4C is currently 4.2. @@ -2420,8 +2406,7 @@ ninja install Build with support for LLVM based - JIT compilation (see ). + JIT compilation (see ). This requires the LLVM library to be installed. The minimum required version of LLVM is currently 3.9. Disabled by @@ -2546,8 +2531,8 @@ ninja install systemdsystemd service notifications. This improves integration if the server is started under systemd but has no impact - otherwise; see for more information. Defaults to + otherwise; see for more information. Defaults to auto. libsystemd and the associated header files need to be installed to use this option. @@ -3122,8 +3107,7 @@ ninja install Enable tests using the Perl TAP tools. Defaults to auto and requires a Perl installation and the Perl module IPC::Run. - See for more information. + See for more information. @@ -3147,8 +3131,8 @@ ninja install code coverage testing instrumentation. When run, they generate files in the build directory with code coverage metrics. - See - for more information. This option is for use only with GCC + See + for more information. This option is for use only with GCC and when doing development work. @@ -3163,8 +3147,7 @@ ninja install Enabling this compiles PostgreSQL with support for the dynamic tracing tool DTrace. - See - for more information. + See for more information. diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build index e1a85dc607..94ec2bda1c 100644 --- a/doc/src/sgml/meson.build +++ b/doc/src/sgml/meson.build @@ -182,43 +182,6 @@ if docs_dep.found() endif -# -# INSTALL in html, text -# -if docs_dep.found() - # Depend on postgres_full_xml, so validity errors are raised in one place, - # and so dependencies don't need to be re-specified. - install_xml = custom_target('INSTALL.xml', - input: ['standalone-profile.xsl', 'standalone-install.xml'], - output: 'INSTALL.xml', - depfile: 'INSTALL.xml.d', - depends: postgres_full_xml, - command: [xsltproc, '-o', '@OUTPUT@', xsltproc_flags, '--xinclude', '@INPUT@'], - build_by_default: false, - ) - install_html = custom_target('INSTALL.html', - input: ['stylesheet-text.xsl', install_xml], - output: 'INSTALL.html', - depfile: 'INSTALL.html.d', - command: [xsltproc, '-o', '@OUTPUT@', xsltproc_html_flags, '@INPUT@'], - build_by_default: false, - ) - alldocs += install_html - - if pandoc.found() - # XXX: Makefile does an iconv translit here, but unclear why? - install = custom_target('INSTALL', - input: [install_html], - output: 'INSTALL', - command: [pandoc, '-t', 'plain', '-o', '@OUTPUT@', '@INPUT@'], - build_by_default: false, - ) - alldocs += install - endif - -endif - - # # Man pages # diff --git a/doc/src/sgml/standalone-install.xml b/doc/src/sgml/standalone-install.xml deleted file mode 100644 index b29e90daf9..0000000000 --- a/doc/src/sgml/standalone-install.xml +++ /dev/null @@ -1,170 +0,0 @@ - - - -
- <productname>PostgreSQL</productname> Installation from Source Code - - - - This document describes the installation of - PostgreSQL using this source code distribution. - - - - If you are building PostgreSQL for Microsoft - Windows, read this document if you intend to build with MinGW or Cygwin; - but if you intend to build with Microsoft's Visual - C++, see the main documentation instead. - - - - - - - - Getting Started - - - The following is a quick summary of how to get PostgreSQL up and - running once installed. The main documentation contains more information. - - - - - - Create a user account for the PostgreSQL - server. This is the user the server will run as. For production - use you should create a separate, unprivileged account - (postgres is commonly used). If you do not have root - access or just want to play around, your own user account is - enough, but running the server as root is a security risk and - will not work. -adduser postgres - - - - - - Create a database installation with the initdb - command. To run initdb you must be logged in to your - PostgreSQL server account. It will not work as - root. -root# mkdir /usr/local/pgsql/data -root# chown postgres /usr/local/pgsql/data -root# su - postgres -postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data - - - - The option specifies the location where the data - will be stored. You can use any path you want, it does not have - to be under the installation directory. Just make sure that the - server account can write to the directory (or create it, if it - doesn't already exist) before starting initdb, as - illustrated here. - - - - - - At this point, if you did not use the initdb -A - option, you might want to modify pg_hba.conf to control - local access to the server before you start it. The default is to - trust all local users. - - - - - - The previous initdb step should have told you how to - start up the database server. Do so now. The command should look - something like: -/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start - - - - To stop a server running in the background you can type: -/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data stop - - - - - - Create a database: -/usr/local/pgsql/bin/createdb testdb - Then enter: -/usr/local/pgsql/bin/psql testdb - to connect to that database. At the prompt you can enter SQL - commands and start experimenting. - - - - - - - What Now? - - - - - - The PostgreSQL distribution contains a - comprehensive documentation set, which you should read sometime. - After installation, the documentation can be accessed by - pointing your browser to - /usr/local/pgsql/doc/html/index.html, unless you - changed the installation directories. - - - - The first few chapters of the main documentation are the Tutorial, - which should be your first reading if you are completely new to - SQL databases. If you are familiar with database - concepts then you want to proceed with part on server - administration, which contains information about how to set up - the database server, database users, and authentication. - - - - - - Usually, you will want to modify your computer so that it will - automatically start the database server whenever it boots. Some - suggestions for this are in the documentation. - - - - - - Run the regression tests against the installed server (using - make installcheck). If you didn't run the - tests before installation, you should definitely do it now. This - is also explained in the documentation. - - - - - - By default, PostgreSQL is configured to run on - minimal hardware. This allows it to start up with almost any - hardware configuration. The default configuration is, however, - not designed for optimum performance. To achieve optimum - performance, several server parameters must be adjusted, the two - most common being shared_buffers and - work_mem. - Other parameters mentioned in the documentation also affect - performance. - - - - - - - - -
diff --git a/doc/src/sgml/standalone-profile.xsl b/doc/src/sgml/standalone-profile.xsl deleted file mode 100644 index a2d78bc10d..0000000000 --- a/doc/src/sgml/standalone-profile.xsl +++ /dev/null @@ -1,97 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - document - - - - the documentation about client authentication and libpq - - - - the documentation - - - - the main documentation's appendix on documentation - - - - the documentation - - - - the documentation - - - - the configuration parameter default_toast_compression - - - - the configuration parameter wal_compression - - - - the documentation - - - - the PL/Python documentation - - - - the file - src/test/regress/README - and the documentation - - - - the documentation - - - - uuid-ossp - - - - xml2 - - - - sepgsql - - - diff --git a/src/pl/plperl/README b/src/pl/plperl/README index e61dd57f53..bdf2dc05b0 100644 --- a/src/pl/plperl/README +++ b/src/pl/plperl/README @@ -6,5 +6,4 @@ To build from this directory use 'make all; make install'. libperl must have been built as a shared library, which is usually not the case in standard installations. -Consult the PostgreSQL User's Guide and the INSTALL file in the -top-level directory of the source distribution for more information. +Consult the PostgreSQL User's Guide for more information. diff --git a/src/tools/RELEASE_CHANGES b/src/tools/RELEASE_CHANGES index 73b02fa2a4..0f30f85ec7 100644 --- a/src/tools/RELEASE_CHANGES +++ b/src/tools/RELEASE_CHANGES @@ -107,6 +107,9 @@ Starting a New Development Cycle placeholder), "git rm" the previous one, and update release.sgml and filelist.sgml to match. +* In the newly-made branch, replace "devel" with the branch's major version + number in the URLs appearing in the top-level README and Makefile files. + * In the newly-made branch, change src/backend/nodes/gen_node_support.pl to enforce ABI stability of the NodeTag list (see "ARM ABI STABILITY CHECK HERE" therein).